From 2d9de8b026d6002367434a2185d8c77b090d5be7 Mon Sep 17 00:00:00 2001 From: Jesusaves Date: Thu, 29 Jul 2021 21:21:38 -0300 Subject: Document TMW Evolved script commands. Or well, most of them. --- server/scripts/tmw_evolved.md | 449 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 431 insertions(+), 18 deletions(-) diff --git a/server/scripts/tmw_evolved.md b/server/scripts/tmw_evolved.md index 8e6ef3f..3f57819 100644 --- a/server/scripts/tmw_evolved.md +++ b/server/scripts/tmw_evolved.md @@ -82,6 +82,7 @@ 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 : @@ -89,6 +90,7 @@ Came with Moubootaur Legends and is unused. // 0x2 -- blank line at the end // 0x4 -- use last "next;" // 0x8 -- don't use first "mesn;" +``` Came with Evol and is unused. @@ -108,6 +110,7 @@ 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: @@ -118,6 +121,7 @@ Returns true if it updated the quest. // 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. @@ -204,10 +208,10 @@ Returns the merc link in M+ Returns the homun link in M+ #### mapexit ( ) -Does nothing. It won't even print a sensible error message in console. +:warning: Deprecated. Does nothing. Error message in console won't be decent. #### destroy ( ) -Disable the current NPC. +:warning: Deprecated. Disable the current NPC. #### npcaction Compatibility layer, do not use. @@ -237,10 +241,10 @@ Alias for `setcamnpc` (if argument provided) or `restorecam` (otherwise) Alias for `sendmapmask` #### getmask -Always return 1 +:warning: Deprecated. Always return 1 #### if_then_else -Alias for `(if ? then : else)` unary +:warning: Deprecated. Alias for `(if ? then : else)` unary #### misceffect ( eff{, target} ) Shows effect for everyone in area, centered in NPC or target if provided. @@ -295,6 +299,47 @@ Creates a dummy monster for cutscenes. Returns the GID. Functions for ServerUpdate(). ### String +Safe string manipulation functions. Does not require PCRE. + +#### str() +// returns whatever is passed, converted to string + +#### startswith("", "") +// returns true if begins with + +#### endswith("", "") +// returns true if ends with + +#### capitalize("") +// returns with its first letter capitalized + +#### titlecase("" {, "" {, }}) +returns with the first letter of each word capitalized. +if is true, the string is joined in a camelCase fashion + +#### camelcase(""}) +Alias for `titlecase` with camel set to True. + +#### zfill("" {, {, ""}}) +// returns padded to the left with up to width + +#### format_number( {, ""}) +// formats a number properly + +#### fnum +Alias for format_number + +#### strip("") +// removes spaces at the start and end + +#### reverse("") +// returns reversed + +#### repeat("", ) +// repeats many times and returns it + +#### shuffle("") +// returns shuffled ### Array Deals with arrays. @@ -312,8 +357,8 @@ return the index of the first occurence of in if not found it returns -1 #### array_rfind(, {, }) -// return the index of the last occurence of in -// if not found it returns -1 +return the index of the last occurence of in +if not found it returns -1 #### array_exists(, {, }) // return true or false accordingly if is found in @@ -340,15 +385,15 @@ if not found it returns -1 // returns the first element of the array and removes it, while shifting left #### array_unshift(, ) -// adds to the start of the array, while shifting right -// returns the new size +adds to the start of the array, while shifting right +returns the new size #### array_pop() // returns the last element of the array and removes it #### array_push(, ) -// adds to the end of the array -// returns the new size +adds to the end of the array +returns the new size #### array_shuffle() // shuffles the array @@ -357,24 +402,49 @@ if not found it returns -1 // allows entries to appear up to in the array #### array_diff(, {, ...}, ) +``` // 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(, "") // filters the array using a callback function #### array_highest() -// Returns the index of the highest value in -// NOTE: Array must be an INT array! +Returns the index of the highest value in \ +NOTE: Array must be an INT array! #### relative_array_random() +``` // 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 +#### abs() +// returns the absolute value of the passed integer + +#### lognbaselvl({{, }}) +// returns BaseLevel * logn (BaseLevel * alpha). + +#### log2() +// returns the log base 2 of the passed integer, up to 20 (2**20=1.048.576) (round down always) + +#### is_between ( lower, higher, target) +// result is: `lower < target <= higher` + +#### limit ( lower, target, higher) +:warning: Deprecated. Use `cap_value` instead. + +// forces the equation: `lower <= target <= higher`. +// Note it still works if higher and target values are swapped. + +#### ponderate_avg ( arg1, sub1, arg2, sub2) +// result is the ponderate average. + ### Bitwise #### bitwise_get ( variable, mask, {shift} ) @@ -414,6 +484,21 @@ Returns bitwise_set ### Permissions +#### is_admin ( {account ID} ) +Returns true if is an admin, with all permissions + +#### is_trusted ( {account ID} ) +Returns true if is a staff member and receives ClientVersion + +#### is_dev ( {account ID} ) +Returns true if is a dev, and can listen to `@wgm` + +#### is_evtc ( {account ID} ) +Returns true if is an event coordinator, and can spawn + +#### is_gm ( {account ID} ) +Returns true if is a game master, and can jail + ## General Purpose Framework Functions These are tools used by NPCs and scripts; But generally not by other functions @@ -431,8 +516,77 @@ Same as menuint, but arguments are strings. Uses `@menuret$`. Same as menuint but takes a single array and then extrapolates it. ### Time +Contains utilites related to time management + +#### now ( ) +Same as `gettimetick(2)` + +#### santime ( ) +Same as `gettimetick(2)`. Unused, from Moubootaur Legends. + +#### time_from_ms ( ) +Undocumented + +#### time_from_seconds ( ) +Undocumented + +#### time_from_minutes ( ) +Undocumented + +#### time_from_hours ( ) +Undocumented + +#### time_from_days ( ) +Undocumented + +#### FuzzyTime({, options=3{, precision=2}}) +``` +// gives time in a human-readable format +// +// is bitmasked: +// 1 do not show "ago" when in past +// 2 do not show "in" when in the future +// 4 show "from now" instead of "in" when in the future +// +// is the number of units to show, +// by default uses two (eg. 2m30s or 1h20m). +// Use '99' for max precision +``` + +#### time_stamp ( ) +Undocumented + +#### HumanTime +:warning: Deprecated. +The old version of FuzzyTime. +DO NOT REUSE. ### Timer +Expands the powers of `addtimer` + +#### areatimer("", , , , , , "::") +`addtimer` in area + +#### areadeltimer("", , , , , "::") +`deltimer` in area + +#### areatimer2 +Same as `areatimer` but cancels running timers of same event + +#### addtimer2 +Same as addtimer but deletes any existing timer with same event + +#### maptimer("", , "::") +`addtimer` in whole map + +#### maptimer2 +Same as `maptimer` but cancels running timers of same event + +#### mapdeltimer("", "::") +Cancels a timer event in the whole map + +#### partytimer("", , "::", partyid) +A map timer, but filters the party ### Goodbye @@ -460,11 +614,31 @@ Closes the dialog, then opens storage. // 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 +Contains the core functions for the Vault. + +#### getvaultid ( ) +Returns your Vault ID, or zero, if not a Vault user. + +#### getvaultexp ( exp ) +Grants Mirror Lake EXP points if you have a Vault ID. + +#### vaultOnLogin ( ) +Handles login for players using the Mirror Lake. + +#### vaultOnLogout ( ) +Flushes mirror lake data to TMW Vault. + +#### MirrorLakeSendTo ( World, Lake ) +Sends a signal to the Mana Launcher to move you to a different world. + +This signal is sent to ManaPlus and then relayed to the Launcher. ## Pre-Loading Functions Most of these are scripts, with some exceptions. They are pre-loading because they @@ -493,10 +667,24 @@ Checks if player have enough space for the items. Closes dialog if false. ### random-talk +Random dialog for various random NPCs. + +They take no arguments. + +#### Functions: +- hello +- moubootalk +- villagertalk +- sailortalk +- legiontalk +- asleep +- studenttalk + ### 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 @@ -509,6 +697,7 @@ Closes dialog if false. // .@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. @@ -563,6 +752,8 @@ Returns true if id is not a boss monster. ### quests +Contains quest handles, such as `QuestSagatha`; `elanore_exp`; `Valon`; etc. + ## Main Functions These are functions and scripts used largely by NPCs. @@ -603,7 +794,7 @@ A barber NPC. If intro is not set, can be used by dialogs. ### dailyquest -:warn: Deprecated. +:warning: Deprecated. Requires a full rewrite. DO NOT REUSE. @@ -612,6 +803,10 @@ DO NOT REUSE. Configures ferries. ### travelers +Could use a rewrite. + +#### Traveler ( ) +The traveler NPC ### game_rules @@ -622,25 +817,53 @@ Show the rules for the player. #### Inn ({price}) -And old function for inns; Should not be used. +:warning: Deprecated. And old function for inns; Should not be used. +Needs a rewrite. ### magic -Contains the old functions for magic NPCs. +:warning: Deprecated. Contains the old functions for magic NPCs. ### mob_points +#### fix_mobkill(mobID) +Manual fix for scripted mobs + +#### MobPoints ( ) +Core function, for monster points and monster-killing quests where map is ignored. + ### process_equip +:warning: Deprecated. +Documentation does not exist. + +Seems to be a feeble attempt to extract dye colors for Inspector Quest. + ### slot_machine +#### SlotMachine ( ) +A Slot machine + +#### SlotMachineSymbol ( ) +Private. + ### soul_menhir +#### SoulMenhir ( ) +:warning: Deprecated. +A Soul Menhir. Require `@Xs`, `@Ys` and `@map$`. + +It is affected by the weird TMWA mess regarding save positions and is not working +fully. Touching it should set both respawn point as location system of 000-0. + ### water_bottle +#### WaterBottle ( ) +Tool for filling water bottles (wells, water pumps, etc) + ### evil_obelisk -:warn: Deprecated. +:warning: Deprecated. Used solely for Hurnscald Evil Obelisk. Requires hidden, undocumented PC variables. DO NOT USE. @@ -648,6 +871,8 @@ DO NOT USE. ### lockpicking #### LockPicking ( ) + +:warning: Deprecated. This is the original Iilia's lockpicking function, not Moubootaur Legends version. Therefore, it is not flexible and not fit for reuse. @@ -658,11 +883,15 @@ Same as setting `.distance` OnInit, but warn players they need to move closer. #### CheckInventory -:warn: Deprecated. +:warning: Deprecated. Used solely for Trick'n'Treat. DO NOT USE. ### undead_debug +Contains the NPC for Crypt debug. + +#### UndeadDebug ( ) +Function to obtain the items for the crpyt boss fights. ### headstyles @@ -673,11 +902,19 @@ Creates a few variables: ### stat_reset +#### StatReset ( ) +A stat reset NPC + ### quiz +:warning: :x: Deprecated. +The old Riddle System from TMWA. + +Must be replaced. + ### dynamic_menu -:warn: Deprecated. +:warning: Deprecated. Use menuint and rif instead. DO NOT REUSE. @@ -691,8 +928,18 @@ Creates a few variables: ### motd +:warning: :x: Deprecated. +Contains the old MOTD configuration which is not flexible. + +It needs to be replaced. + ### motdconfig +:warning: :x: Deprecated. +Contains the old MOTD configuration which is not flexible. + +It needs to be replaced. + ### miriam Private functions @@ -736,8 +983,161 @@ Updates `LOCATION$` variable Warps home and updates LOCATION$ ### weather +Controls world seasons. But they are disabled in TMW. +Therefore, it controls weather magic. + +A few commands are defined: +- `@wsnow` +- `@wrain` +- `@wsand` +- `@wevil` +- `@wnight` +- `@wclear` +- `@wreset` +- `@wset` + +#### "#WeatherCore"::climate(mapid) +Returns the climate setting + +#### "#WeatherCore"::weather(weather{, mapid}) +Returns true if weather is present in map + +#### "#WeatherCore"::weather_override(weather, duration{, mapid, override=false}) +Modifies the weather on mapid for duration. +If override is set, disregard climate restrictions. ### marriage +Contain private functions for marriage. + +// to use, create a duplicate: +```c +001-1,30,31,0 duplicate(marriage) name#x1,y1,x2,y2 NPCID +001-1,30,31,0 duplicate(marriage) name#range NPCID +``` + +### npcmovegraph +Contains the needed utilities for walking NPCs. + +#### initmovegraph ( ) +Initializes a walking NPC + +#### setmovegraphcmd ( fromPositionLabel, toPositionLabel [,moveChanceWeight [,moveFlags]], postCommand, ...); +``` + * This function manipulates NPC moving graph. Before calling it, make sure + * `initmovegraph' was called. The function accepts 3-5 parameters (many times): + * fromPositionLabel, toPositionLabel -- starting and ending position of NPC move + * moveChanceWeight -- positive integer, represents the chance of moving in given direction. (optional) + * moveFlags -- if .mg_flags & moveFlags != 0, move is possible. (optional) + * postCommand -- either "moveon" (start moving to next location straight after arriving from + * fromPositionLabel to toPositionLabel) or a semicolon-separated set of commands + * ("wait 3", "emote 5" etc, see `execmovecmd') that will be executed after arrival. + * The commands don't have to end with ";moveon", it's executed in the end by default. +``` + +#### execmovecmd +Private? Commands are: +- moveon +- dir +- sit +- stand +- wait +- emote +- class +- warp +- call + - calls a function +- speed +- say +- debugmes +- flags +- flags_0 +- flags_1 + +#### firstmove +``` +// initial actions for npc when using move graphs. +// function can accept 2 arguments: +// 1: action sequence, for example "speed 200; dir 4". Default is "moveon" +// 2: start point label. Default is #0 from move graph labels +``` + +#### dographmovestep +??? + +#### npc_pausemove +Pauses NPC move + +#### npc_resumemove +Resumes NPC move + +#### npc_turntoxy (X, Y) +Turn NPC towards an object at position (X,Y) + +#### getnextmovecmd +Private? + +#### getrandompoint(x1,y1,x2,y2) +Private? +``` +// -- Get a random walkable point within a map rectangle +// x1, y1 -- top-left corner of rectangle +// x2, y2 -- bottom-right corner of rectangle +// Returns 0 on success and -1 on error; +// Since we cannot return multiple values, the random +// coordinates are stored in NPC variables .move__rand_x, .move__rand_y +``` + +#### findmovegraphlabel +Private? + +#### mg_npcwalkto +Private? +``` +// wrapper function for npcwalkto. It can accept 4 parameters. +// If #3 and #4 params are set, the walkto location is chosen +// from rectangle (x1,y1,x2,y2). +// It sets the npc variables .move_target_x, .move_target_y +// that are used to resume NPC walking +// Returns 1 if walking is possible, 0 otherwise; +``` + +#### movetonextpoint +Private? + +### npcmove +Contains the needed utilities for walking NPCs. + +#### initpath +No documentation available + +#### domoveaction +No documentation available +Internal commands exist. + +- move +- dir +- wait +- emote +- class +- warp +- goto +- rmove +- speed +- sit +- stand + +#### movetonextpos +No documentation available + +#### initialmove +No documentation available + +#### getmovecmd +No documentation available + +#### domovestep +No documentation available + ## Items Functions used with callfunc(), when it was quite too much script code to be added on @@ -765,6 +1165,19 @@ interface so NPCs can be loaded after. ### Scoreboards +Contains the Leaderboards and is one of the most expensive components. + +- HallOfGuild +- HallOfFortune +- HallOfLevel +- HallOfJob +- HallOfAcorns (not used) +- HallOfLethality (removed) +- HallOfAlmanach +- HallOfGame + +Command: `@scoreboard` and `@scoreboards` + ### Global Event Handler Handles login events, logout events, death, assassinate, server init, clear logs, -- cgit v1.2.3-60-g2f50