path: root/server/scripts/tmw_evolved.md

# The Mana World Evolved
### Custom Functions

Last Update: 2021-07-30

## About custom functions
The bulk of functions used are NPC scripts.
They are loaded by npc/scripts.conf and divide in a few blocks:

- Critical Functions
- General Purpose Framework Functions
- Pre-Loading Functions
- Main Functions
- Item Functions
- Magic Functions
- GM Commands
- Events
- Post-Loading Functions
- NPC Functions

## Critical Functions
These functions are critical, and breaking them will break several other functions,
breaking in turn several NPCs, and will probably cause the server to crash.

In other words: They are nested by NPCs, scripts and functions.

### Main

#### menuimage ( image, string )

Formatting for select

#### dnext ( )
Same as next, but honors `GSET_LONGMENU_DENSITY`

#### menuaction ( str )
Returns `[str]`

#### setq1 ( quest, val )
Sets quest field 1.

#### setq2 ( quest, val )
Sets quest field 2.

#### setq3 ( quest, val )
Sets quest field 3.

#### setqtime ( quest, val )
Sets quest time field. Unused and does not work properly.

#### mesn ( {name} )
Header for NPC dialog. Use it before NPC start talking.

#### mesq ( message )
Sends a NPC message enclosed in quotes. You should give it an `l()` function.

#### g ( female, male )
Returns something variating with gender.
Is totally useless, difficult to translate, and its use is generally frowned upon.

#### b ( message )
Makes the message bold

#### col( message{, color} )
Send message in color. Defaults to color code 9.

#### adddefaultskills ( )
Ensure a player have the default skills (sit, walk, talk, resync, etc.)

#### addremovemapmask ( map, mask, mask )
Updates map mask. I'm not sure how it actually works.

#### mesc ( message, {color} )
Same as `mes(col(message{, color}))`

#### get_race ( {class} )
Returns the human readable form of your race (from `$@allraces$`)
Currently unused and broken.

#### tutmes ( message, {header=Tutorial, headerfirst=True} )
Sends the message if `TUTORIAL` is set.
Came with Moubootaur Legends and is unused.

#### narrator ( flag, str )
// Function to show narrator text. Accepts string args.
// If first arg is a number N, then it represents bit flags.
// Bit flags :
//   0x1 -- blank line at beginning
//   0x2 -- blank line at the end
//   0x4 -- use last "next;"
//   0x8 -- don't use first "mesn;"

Came with Evol and is unused.

#### speech ( flag, string )
See narrator, but for NPCs

#### npcdebug ( message )
Shows debug message on server console if `.debug` is set.

#### askyesno ( )
Ask players to select between YES and NO.

Returns the choice in `ASK_YES` or `ASK_NO` constants.

#### compareandsetq ( quest, current, next )
Checks if quest is current and updates to next if true.
Returns true if it updated the quest.

#### npctalkonce ( text{, delay=1{, function=npctalk3}} )
// Use a delay to prevent spams from NPC that display text without the
// use of (a) close/next function(s).
// Argument:
//  0 Text to display
//  1 Lock delay (default = 1)
//  2 Message function:  (default = 0)
//      0 = npctalk3
//      1 = npctalk
//      2 = message
// TODO: Use temp player var, because NPC var affect other players

#### rand2 ( min{, max} )
Same as `rand` but for small numbers. Increases entropy.

#### any( <arg>{, ...<arg>} )
returns one argument randomly

#### any_of( <array> )
returns any member of the array

#### die ( )
Kills the player. If `$HARDCORE` is true, it'll set `@grace` variable.
This allows hardcore servers to NOT send players to the abyss when they were
killed by script.

#### ispvpmap( {mapid} )
Returns true if the map has PVP enabled.

#### msObjective ( condition , message )
Function from Moubootaur Legends, colors `message` based if `condition` is true
or not.

#### getmap ( )
Same as `getmapname()` but using `getmapxy()` instead.
Performance was not measured.

#### isin ( map, x1, y1, {[x2, y2][radius]} )
Verifies if the player is in the specific rectangle (or square, if radius is
provided instead of a x2,y2 tuple)

#### isat ( map, x1, y1 )
Same as `isin` but only for the specific tile.

#### delinventorylist ( )
Clear output of getinventorylist()

#### gf_accid / gf_charnameid / gf_charname / gf_charid / validatepin
Moubootaur Legends functions. Should never be used.

####  Exception( Message, {Flags{, Return Code}} )
Error handling. See RB_ constants for flags which may be used.

#### mescordialog ( text, color, {dialog=1} )
If dialog is set, sends text as a mesc. Otherwise, sends it as a dispbottom.

#### itheal ( hp{, mp{, time}} )
// Delayed healing. Takes 3~5 seconds. Variates with Vit up to +100%.
// The vit can have an additional 20% bonus as well.
Mana regenerates instantly.

#### sqldate ( {day variation, month variation} )
Offsets and returns current date in SQL format

#### set_aggro( monster{, mode=MD_AGGRESSIVE} )
Makes a monster aggressive. Can set other monster mobs as well, such as MD_LOOTER
and MD_ASSIST.

#### numdate ( )
Special function which makes current date (ISO) a progressive number.
eg. `20210730`.

If `$@OVERRIDE_NUMDATE` is set, it'll return that instead.

#### json_encode ( {varname, varvalue}, {varname 2, varvalue 2}... )
Formats a dictionary in JSON format.

#### api_send ( code, data )
Dumps data into `api_export` table. Used by Mirror Lake.
Code is an integer and data is a JSON-string.

#### getquestlink ( quest )
Returns the quest link in M+

#### getmonsterlink ( mob )
Returns the mob link in M+

#### getpetlink ( pet )
Returns the pet link in M+

#### getmercenarylink ( merc )
Returns the merc link in M+

#### gethomunculuslink ( homun )
Returns the homun link in M+

#### mapexit ( )
Does nothing. It won't even print a sensible error message in console.

#### destroy ( )
Disable the current NPC.

#### npcaction
Compatibility layer, do not use.

#### gmlog ( message )
Writes message to GM Log.

#### getx ( )
Returns X position

#### gety ( )
Returns Y position

#### getnpcx ( )
Returns .x variable

#### getnpcy ( )
Returns .y variable

#### title
Alias for `setnpcdialogtitle`

#### camera
Alias for `setcamnpc` (if argument provided) or `restorecam` (otherwise)

#### mapmask
Alias for `sendmapmask`

#### getmask
Always return 1

#### if_then_else
Alias for `(if ? then : else)` unary

#### misceffect ( eff{, target} )
Shows effect for everyone in area, centered in NPC or target if provided.

#### selfeffect ( eff{, target} )
Shows effect for yourself, centered in NPC or target if provided.

#### fakenpcname
Alias for `setnpcdisplay`

#### npcwarp ( x, y{, npcid} )
Warps a NPC without animations.

#### get
Alias for `getvariableofnpc`

#### sc_check
Alias for `getstatus`. If the second argument is not passed, defaults to `0`.

#### wgm
Sends a `@request`.

#### registercmd
Alias for `bindatcmd`.

#### iscollision
Alias for `checknpccell` (with `cell_chkpass`)

#### readparam2
Alias for `readbattleparam` but without asking for account ID.

#### updateskill
Alias for `skill` with flag 0.

#### npctalk2
Same as `npctalk` but with arguments swapped.

#### learnskill
Same as `updateskill`, but only runs if your skill level is less than provided.
If no skill level is given, defaults to 1.

#### spawndummy ( map, x, y, ID{, name{, event}} )
Creates a dummy monster for cutscenes. Returns the GID.

#### DelItemFromEveryPlayer( ID )
#### DelAccRegFromEveryPlayer( KEY )
#### DelChrRegFromEveryPlayer( KEY )
#### DelQuestFromEveryPlayer( ID )
#### ReplaceItemFromEveryPlayer( OldID, NewID )
#### ReplaceSkillFromEveryPlayer( OldID, NewID )

Functions for ServerUpdate().

### String

### Array
Deals with arrays.

#### array_pad ( array, size, value )
prepend or append <value> until the array is of <size> size
returns the amount added on success, or false (0) if nothing changed

#### array_replace ( <array>, <needle>, <replace>{, <neq>} )
replace every occurence of <needle> with <replace>
returns the number of replaced elements

#### array_find ( <array>, <needle>{, <neq>} )
return the index of the first occurence of <needle> in <array>
if not found it returns -1

#### array_rfind(<array>, <needle>{, <neq>})
//     return the index of the last occurence of <needle> in <array>
//     if not found it returns -1

#### array_exists(<array>, <needle>{, <neq>})
//     return true or false accordingly if <needle> is found in <array>

#### array_count(<array>, <needle>{, <neq>})
//     counts the number of occurrence of <needle> in the <array>

#### array_entries(<array>)
//     returns the number of non-empty entries

#### array_remove(<array>, <needle>{, <neq>})
//     removes every occurrence of <needle> in the <array> while shifting left

#### array_reverse(<array>)
//     reverses the array

#### array_sum(<array>)
//     return the sum of every element of the array

#### array_difference(<array>)
//     return the difference of every element of the array

#### array_shift(<array>)
//     returns the first element of the array and removes it, while shifting left

#### array_unshift(<array>, <value>)
//     adds <value> to the start of the array, while shifting right
//     returns the new size

#### array_pop(<array>)
//     returns the last element of the array and removes it

#### array_push(<array>, <value>)
//     adds <value> to the end of the array
//     returns the new size

#### array_shuffle(<array>)
//     shuffles the array

#### array_unique(<array>{, <threshold>})
//     allows entries to appear up to <threshold> in the array

#### array_diff(<array1>, <array2>{, <array>...}, <array>)
//     compares array1 against one or more other arrays and fills the last array
//     with the values in array1 that are not present in any of the other arrays
//     returns the number of entries not matching

#### array_filter(<array>, "<function>")
//     filters the array using a callback function

#### array_highest(<array>)
//     Returns the index of the highest value in <array>
//     NOTE: Array must be an INT array!

#### relative_array_random(<array: 0, {[value, probability]..}>)
//     returns a random entry from the array, by relative probability
//     the first key of the array should be 0 and every entries are a tuple
//     of [value, probability]

### Math

### Bitwise

#### bitwise_get ( variable, mask, {shift} )
Gets a bitmasked value in from an integer. If the shift is omitted, it will be
deduced from the mask.

#### bitwise_set ( variable, mask, shift, new value )
Sets a bitmasked value in a variable.

Returns a reference to the variable.

#### bitwise_count ( int )
//    returns the number of bits set in <int>

#### get_nibble ( VAR, NIBBLEID )
Gets a nibble from a bitmasked variable.

// A Nibble can go up to 15. There are 7 nibbles.

#### get_byte ( VAR, BYTEID )
Gets a byte from a bitmasked variable.

// A Byte can go up to 255. There are 3 bytes, and a fourth going up to 127.

#### get_bitword ( VAR )
// A Bitword can go up to 65535 and is fixed in position to handle Soul EXP.

#### set_nibble ( VAR, NIBBLEID, VAL )
Returns bitwise_set

#### set_byte ( VAR, BYTEID, VAL )
Returns bitwise_set

#### set_bitword ( VAR, VAL )
Returns bitwise_set


### Permissions

## General Purpose Framework Functions
These are tools used by NPCs and scripts; But generally not by other functions

### Input

#### menuint ( «struct» )
Composed by tuples of (string, int); Causes a menu to show up.
Will save the int from selected option in `@menuret` variable.
And then, return it.

#### menustr ( «struct» )
Same as menuint, but arguments are strings. Uses `@menuret$`.

#### menuint2 ( array )
Same as menuint but takes a single array and then extrapolates it.

### Time

### Timer

### Goodbye

#### goodbye_msg ( )
Returns a random goodbye message.

#### cwarp ( {x,y}/{map, x, y} )
Closes the dialog, then warps the player.
- If map is not specified, will slide to coordinates.
- If no coordinates are passed, will warp randomly.

#### cshop ( {name} )
Closes the dialog, then opens a shop.
It is optimized for evol use, so {name} should always be supplied.

#### cstorage ( )
Closes the dialog, then opens storage.

#### bye ( {emote} )
//     closes the dialog without waiting for the player to press close
//     can also display an emote

#### goodbye ( {emote} )
//     same as bye, but also displays a canned message
//     can also display an emote

#### goodbye2 ( {emote} )
//     Waits for the player to press close, displays a canned message,
//     ends execution.
//     Can also display an emote

### Vault

## Pre-Loading Functions
Most of these are scripts, with some exceptions. They are pre-loading because they
may be needed by other scripts.

### clear_vars

#### ClearVariables ( )
Post-login updater for players

#### ServerUpdate ( )
Post-Init updater for server

### asklanguage

#### languagecode()
Returns the string language code of user's language.

#### asklanguage()
Allows player to change their game language.

### inventoryplace

#### inventoryplace ( {item, number, item, number, item, number...} )
Checks if player have enough space for the items.
Closes dialog if false.

### random-talk

### inc_sc_bonus

#### SC_Bonus ( delay, SC, min{, max} )
//    Applies effects for INC_* (STR doesn't exist)
//    Valid values: INCAGI INCVIT INCINT INCDEX INCLUK INCHIT INCFLEE SC_FURY
//    Doesn't works: SC_STRUP
//    Works if .@min == .@max: INCMHP INCMHPRATE INCMSP INCMSPRATE
///   Untested Values: WALKSPEED (reverse logic) INVINCIBLE (broken)
//    PS. SC_FURY causes crit rate to increase
//
// Variables:
//    .@delay    Second of buffing
//    .@type     SC_*
//    .@min      Min amount of type
//    .@max      Max amount of type (optional)

#### SC_Bonus2(delay, SC1, val1, val2)
Same as SC_Bonus, but when the SC takes two values.

### commands/kami

### filters

Filters for array_filter and other callbacks.

#### filter_always( id )
Always return true.

#### filter_onlyme( id )
Returns true if id is your account id.

#### filter_notme( id )
Returns true if id is not your account id.

#### filter_sameguild( id )
Returns true if id is in the same guild as you, incl. yourself.

#### filter_sameguildnotyou( id )
Returns true if id is in the same guild as you, excl. yourself.

#### filter_sameparty( id )
Returns true if id is in the same party as you, incl. yourself.

#### filter_sameguildorparty( id )
Returns true if id is in the same guild or party as you, incl. yourself.

#### filter_sameguildorpartynotyou( id )
See above. Excludes yourself.

#### filter_hostile( id )
Returns true if id is:
- An hostile player in a PvP map, honoring noparty and noguild subrules
- A monster
- An hostile homunculus
- A hostile pet
- A hostile mercenary
- A hostile elemental
- A player/slave not in same guild or party.

Always return false for npcs.

#### filter_friendly( id )
Returns true if id is not hostile (See above)

#### filter_notboss( id )
Returns true if id is not a boss monster.

### quests

## Main Functions
These are functions and scripts used largely by NPCs.

### alchemy
Handles **all** alchemy tables in the world.

#### AlchemySystem ( )
Invokes Alchemy system, even without a table.
Returns `true` if concatenation was successful.

### banker

#### Banking ( )
Handles GP operations

#### Banker ( )
Handles a Bank - Complete: GP, storage, mail, quests if any.

### barber

#### BarberSayStyle ( {what} )
// what: 1 = Style; 2 = Color; 3 = Style + Color in dialog

#### BarberChangeStyle ( )
Private function

#### BarberChangeColor ( )
Private function

#### BarberChangeBodyType ( )
Private function

#### BarberChangeRace ( )
Private function

#### Barber ( {intro=True} )
A barber NPC. If intro is not set, can be used by dialogs.

### dailyquest

:warn: Deprecated.
Requires a full rewrite.
DO NOT REUSE.

### ferry

Configures ferries.

### travelers

### game_rules

#### GameRules ( )
Show the rules for the player.

### inn

#### Inn ({price})

And old function for inns; Should not be used.

### magic

Contains the old functions for magic NPCs.

### mob_points

### process_equip

### slot_machine

### soul_menhir

### water_bottle

### evil_obelisk

:warn: Deprecated.
Used solely for Hurnscald Evil Obelisk.
Requires hidden, undocumented PC variables.
DO NOT USE.

### lockpicking

#### LockPicking ( )
This is the original Iilia's lockpicking function, not Moubootaur Legends version.
Therefore, it is not flexible and not fit for reuse.

### default_npc_checks

#### PCtoNPCRange ( {distance=4} )
Same as setting `.distance` OnInit, but warn players they need to move closer.

#### CheckInventory

:warn: Deprecated.
Used solely for Trick'n'Treat.
DO NOT USE.

### undead_debug

### headstyles

Creates a few variables:
- `setarray $@hairstyle$`
- `setarray $@haircolor$`
- `setarray $@REFEXP`

### stat_reset

### quiz

### dynamic_menu

:warn: Deprecated.
Use menuint and rif instead.
DO NOT REUSE.

### DyeConfig

Creates a few variables:
- `setarray $@DYE_color_names$`
- `setarray $@DYE_colors$`
- `setarray $@DYE_items$`
- `setarray $@DYE_item_names$`

### motd

### motdconfig

### miriam

Private functions

### ghost

Private functions

### location

Coordinates location system, including respawns.
Sets a few arrays:
- `$@LOCMASTER_TP`
- `$@LOCMASTER_LOC$`
- `$@LOCMASTER_MAP$`
- `$@LOCMASTER_X`
- `$@LOCMASTER_Y`

#### ResaveRespawn ( )
Resaves your respawn point

#### ReturnTown ( )
Warps you to the town saved in `LOCATION$`

#### LocToMap ( LocName )
Retrieves map name from location name

#### MapToLoc ( MapName )
Retrieves location name from map name

#### TPToLoc ( TPCode )
Retrieves map name from TP constant

#### POL_LocToTP ( TOWNCODE )
Actually, a manual conversion from location name to its TP code.

#### EnterTown( LocName )
Updates `LOCATION$` variable

#### teleporthome ( )
Warps home and updates LOCATION$

### weather

### marriage

## Items Functions
used with callfunc(), when it was quite too much script code to be added on
item_db.conf directly. One file per item, and should be used only for the item.

## Magic Functions
The post-loader (`global_event_handler`) will load magic spells from here.
Each file is a magic spell of its own, with a couple exceptions:

### magic/config
Loaded before all magic spells.

### magic/final
Loaded after all magic spells.

## Commands
These define GM Commands.

## Events
These define annual and repeatable events. Mostly.

## Post-Loading Functions
These are mostly NPCs responsible for cleaning up the whole script and functions
interface so NPCs can be loaded after.

### Scoreboards

### Global Event Handler

Handles login events, logout events, death, assassinate, server init, clear logs,
and also handles the backbone of die() function.