Classic:TmwAthena Scripting Reference: Difference between revisions

From The Mana World
← Older edit
O11c (talk | contribs)
477 edits
→deletearray: note it is broken
mNo edit summary
 
(63 intermediate revisions by 11 users not shown)
Line 1: Line 1:
This page is a reference for commands believed to work in the eAthena scripting language still used by tmwAthena.
<metakey>Script Language, Code, Source, eAthena Script, AST</metakey> <metadesc>The Mana World Scripting Language Reference</metadesc>
<div style="background-color: #f6ebc1; text-align: center; border: 1px solid #e0b713; margin-bottom: 10px;">
'''TMWA's scripting wiki pages:'''
 
[[Legacy:Scripting Basics]] - [[Legacy:Scripting Standards]] - [[Legacy:Scripting Reference]]
 
For questions feel free to contact us on [https://web.libera.chat/?channels=#themanaworld-dev IRC] and/or on our [https://forums.themanaworld.org forum].
</div>
{{Category:Outdated}}
 
 
This page is a reference for commands ''believed'' to work in the eAthena scripting language still used by tmwAthena.
 
'''Note:''' A number of problematic commands have been removed from this list, but not all commands have been tested.


A number of problematic commands have been removed from this list, but not all commands have been tested.


== Language Commands ==
== Language Commands ==
Line 14: Line 26:
=== callsub ===
=== callsub ===
<pre>
<pre>
     callsub S_labelname, arguments...;
     callsub S_labelname;
</pre>
</pre>
Jump to the given label. When the "return" statement is executed, continue on the next line.
Jump to the given label. When the "return" statement is executed, continue on the next line.
It is not known whether "arguments..." works, we use temporary variables instead.


It might also be possible to use this as a function, if the form of return with a value is used, but we use temporary variables instead.
It might also be possible to use this as a function, if the form of return with a value is used, but we use temporary variables instead.
Line 24: Line 34:
=== callfunc ===
=== callfunc ===
<pre>
<pre>
     callfunc "function_name", arguments. "s*"
     callfunc "function_name";
</pre>
</pre>
Jump to the given function script. When the "return" statement is executed, continue on the next line of this script.
Jump to the given function script. When the "return" statement is executed, continue on the next line of this script.


It is not known whether "arguments..." works, we use temporary variables instead.
It might also be possible to use this as a function, if the form of return with a value is used, but we use temporary variables instead.


It might also be possible to use this as a function, if the form of return with a value is used, but we use temporary variables instead.
"return" is broken if this is used from within an if(). If you need a conditional callfunc, first goto a label.


=== return ===
=== return ===
<pre>
<pre>
     return;
     return;
    return expr;
</pre>
</pre>
Return from this script or sublabel to the calling function.
Return from this script or sublabel to the calling function.


It is unknown what happens if this is used from the top-level script, use "close" or "end" instead.
It is unknown what happens if this is used from the top-level script, use "close" or "end" instead.
We use temporary variables instead of the form that returns an expression.
=== getarg ===
<pre>
    getarg(index)
</pre>
Return (by reference?) an argument of "callsub" or "callfunc". Aborts the script if used at toplevel of if out of range.
We use temporary variables instead.


=== set ===
=== set ===
Line 72: Line 71:
</pre>
</pre>
Fill an array with "count" copies of "value".
Fill an array with "count" copies of "value".
=== copyarray ===
<pre>
    copyarray dest_var, src_var, count;
</pre>
Copy elements of an array.
This function looks broken to me.


=== getarraysize ===
=== getarraysize ===
Line 85: Line 76:
     getarraysize variable;
     getarraysize variable;
</pre>
</pre>
Get the size of an array.
Get the size of an array. Returns 1 even when empty.


The size of an array is simply one more than the index of the last nonzero integer or nonempty string.
The size of an array is simply one more than the index of the last nonzero integer or nonempty string.


WARNING: most functions that set an array do not bother to clear out high indices. You should almost always use an explicitly-provided size instead.
WARNING: most functions that set an array do not bother to clear out high indices. You should almost always use an explicitly-provided size instead.
=== deletearray ===
<pre>
    deletearray variable[, count = 1];
</pre>
Remove count elements from an array.
If there are elements beyond count, they will be shifted into lower indices.
After that, all remaining elements will be set to 0 or "".
This function is currently broken, instead use cleararray variable, 0, count;


=== getelementofarray ===
=== getelementofarray ===
<pre>
<pre>
     getelementofarray(arrayname, index_expr)
     arrayname[index_expr]
</pre>
</pre>
This function is invoked internally by the arrayname[index_expr] syntax.
returns index_expr of that array.


=== if ===
=== if ===
Line 116: Line 95:


The only thing special about the if command is the lack of commas during parsing (from my reading this is only a warning?). During execution it is perfectly normal.
The only thing special about the if command is the lack of commas during parsing (from my reading this is only a warning?). During execution it is perfectly normal.
Note: you must not use a callsub or callfunc as conditional_command.


=== end ===
=== end ===
Line 131: Line 112:
Print a message to stdout.
Print a message to stdout.


 
== Message Commands ==
 
These are commands for dialog or one-way chat with players.
 
== Unsorted Commands ==
These are commands that still need sorting, please edit this page, see talk page for category (and subcategory?) suggestions.


=== mes ===
=== mes ===
Line 144: Line 122:


It is unknown if the client properly supports dialog with multiple NPCs simultaneously. Note that the server only allows each account one paused script at a time, so it probably wouldn't work anyway.
It is unknown if the client properly supports dialog with multiple NPCs simultaneously. Note that the server only allows each account one paused script at a time, so it probably wouldn't work anyway.
If you need to include the '''"''' character inside the message, (especially for dialogs) insert it as '''\"'''.
When doing several messages without a next; in between, there should be only a single \" at the beginning and the end each.
'''Example''':
mes "[Me Myself]";
mes "";
mes "(I clear my throat)"
mes "";
mes "\"I start talking here, and don't close the quotation marks, because I'm not yet done talking.";
mes "And start a new line, but without new quotation marks.";
mes "Here I stop talking, so I close the quotation marks.\"";
gives:
[Me Myself]
(I clear my throat)
"I start talking here, and don't close the quotation marks, because I'm not yet done talking.<br>
And start a new line, but without new quotation marks.<br>
Here I stop talking, so I close the quotation marks."


=== next ===
=== next ===
Line 161: Line 159:
     close2;
     close2;
</pre>
</pre>
Stop the script until the user presses the "Close" button in the dialog, then keep executing the script
Stop the script until the user presses the "Close" button in the dialog, then keep executing the script.
 
WARNING: unlike close, this command is a blocking command, the usual caveats apply.


=== menu ===
=== menu ===
Line 167: Line 167:
     menu
     menu
         "option 1", L_1,
         "option 1", L_1,
         "option 2", L_2,
         "option 2", L_2;
        "default", -;
</pre>
</pre>
Display a list of choices to the player, then branch to the specified label. The special label "-" means don't branch, just continue with the next statement.
Display a list of choices to the player, then branch to the specified label.


Additionally, the temporary variable "@menu" is set to the 1-based index of the choice.
Additionally, the temporary variable "@menu" is set to the 1-based index of the choice.
Line 184: Line 183:
The implementation allows variable_name to be omitted if input is an integer, in case l14 is used. Don't use this.
The implementation allows variable_name to be omitted if input is an integer, in case l14 is used. Don't use this.


=== warp ===
=== announce ===
<pre>
<pre>
     warp "mapname", x, y;
     announce "message", flag;
</pre>
</pre>
Warp the attached player to the given location. "mapname" may have the special values "Random", "SavePoint", and "Save" (case-sensitive), but x and y are still required.
Do a GM message.


=== isat ===
If flag & 0xF == 0 forward it to all map servers.
<pre>
If flag & 0x8, message is from the OID (NPC? usually?) rather than the RID (player).
    isat("mapname", x, y)
</pre>
Return 1 if the attached player is at the given location, 0 otherwise.


=== areawarp ===
If (flag & 0x7) == 1, send to all on map.
<pre>
If (flag & 0x7) == 2, send to all in line of sight.
    areawarp "src_map", x0, y0, x1, y1, "dst_map", x, y;
If (flag & 0x7) == 3, send to self only.
</pre>
If (flag & 0x7) == anything else, send to all clients.
Warp all players in the given area to the given location.


=== setlook ===
=== mapannounce ===
<pre>
<pre>
     setlook type, value;
     mapannounce "mapname", "message", flag;
</pre>
</pre>
Set an aspect of a character's appearance. Used e.g. by the barber.
Send an announcement to all players in map.


TODO provide constants for type (and maybe value). 1 is style, 6 is color.
Only flag & 0x10 is interpreted, which does not work with the Mana client. So, flag must be 0.


=== getitem ===
=== message ===
<pre>
<pre>
     getitem "itemname", count[, unused_argument[, playerid]];
     message "player", "message";
    getitem itemid, count[, unused_argument[, playerid]];
"ii**"
</pre>
</pre>
Grant the attached player (or the given player) "count" copies of an item.
Display (in chat) a message from the server to a single user.


If itemname is unrecognized you get an iten (727) instead.
=== npctalk ===
 
=== makeitem ===
<pre>
<pre>
     makeitem "itemname", count, "mapname", x, y;
     npctalk "message";
    makeitem itemid, count, "mapname", x, y;
</pre>
</pre>
Drop items on the ground.
Make an NPC say something publicly.
 
Note: in many cases areaannounce is a better choice.


The special "mapname" value "this" means the map of the attached player.
== Character Commands ==
These have to do with attributes of the player.


=== delitem ===
=== setlook ===
<pre>
<pre>
     delitem "itemname", count;
     setlook type, value;
    delitem itemid, count;
</pre>
</pre>
Remove items from the attached player's inventory.
Set an aspect of a character's appearance. Used e.g. by the barber.


This command is buggy if the player does not have enough of the item.
There are constant provided for the LOOK type, and for hair color and hair style.


=== heal ===
=== heal ===
<pre>
<pre>
     heal hp, sp
     heal hp, sp[, boolean];
</pre>
Increase or decrease the player's hp and sp.
 
=== itemheal ===
<pre>
    itemheal "ii"
</pre>
Increase or decrease the player's hp and sp, for use in item scripts.
 
=== percentheal ===
<pre>
    percentheal "ii"
</pre>
Increase or decrease the player's hp and sp, by percentage of max HP.
 
This is probably the best way to instakill the player.
 
=== rand ===
<pre>
    rand(range)
    rand(min, max)
</pre>
In the first form, return a random number between 0 (inclusive) and range (exclusive). Return 0 if range is not positive.
In the second form, return a random number between min and max, inclusive. Min and max may be swapped.
 
=== pow ===
<pre>
    pow(a, b)
</pre>
return <math>(a \times .001) ^ b</math>
 
=== countitem ===
<pre>
    countitem("itemname")
    countitem(itemid)
</pre>
Return the number of the given item in the player's inventory.
 
=== checkweight ===
<pre>
    checkweight("itemname", count)
    checkweight(itemid, count)
</pre>
</pre>
Return 0 if adding "count" of the item would put player above max weight, 1 if it would still be less than max weight.
Increase or decrease the player's hp and sp. Add ,1 at the end to make it heal gradually.
Also returns 0 if item does not exist.


=== readparam ===
=== readparam ===
Line 307: Line 256:
3: account id
3: account id


 
You usually want 3.
=== getpartyname ===
<pre>
    getpartyname(partyid)
</pre>
Return the name of the party with the given id, or "null".
 
=== getpartymember ===
<pre>
    getpartymember partyid
</pre>
Fills in the array $@partymembername$


=== strcharinfo ===
=== strcharinfo ===
Line 329: Line 267:
num==2: guild name (deprecated)
num==2: guild name (deprecated)


=== getequipid ===
=== sc_start ===
<pre>
<pre>
     getequipid(equip_point)
     sc_start type, tick, val1[, beingid];
</pre>
</pre>
Return the ID of the item in the given equip slot.
Apply a status effect to a player (or monster?).


equip_point is one of the equip_* constants
type is one of the sc_* constants.


=== getequipname ===
=== sc_end ===
<pre>
<pre>
     getequipname(equip_point)
     sc_end type;
</pre>
</pre>
Return the name of the item in the given equip slot.
Immediately end status effect on current player.


equip_point is one of the equip_* constants
=== sc_check ===
 
=== getequipisequiped ===
<pre>
<pre>
     getequipisequiped(num)
     sc_check(type)
</pre>
</pre>
Return 1 if the player currently has an item equipped in the slot.
Whether a status effect is currently active.


=== statusup ===
=== resetstatus ===
<pre>
<pre>
     statusup bType;
     resetstatus;
</pre>
</pre>
Permanently increase a stat by one point.


=== statusup2 ===
=== changesex ===
<pre>
<pre>
     statusup2 bType, delta;
     changesex;
</pre>
</pre>
Permanently increase or decrease a stat.
Ask the login server (via the char server) to toggle this account's sex, then kick the player.


=== bonus ===
=== attachrid ===
<pre>
<pre>
     bonus bType, delta
     attachrid(id)
</pre>
</pre>
Temporarily increase a stat. For use in item scripts only.
Change the being associated with this script.


=== skill ===
Return true if such a player is logged in.
<pre>
    skill id, level[, flag = 1];
</pre>
Grant a skill.


flag==0: permanent skill
=== detachrid ===
flag==1: temporary skill (item scripts only)
 
(Untested)
 
=== setskill ===
<pre>
<pre>
     setskill id, level;
     detachrid;
</pre>
</pre>
Grant a skill permanently.
Detach the player associated with this script.


=== getskilllv ===
=== isloggedin ===
<pre>
<pre>
     getskilllv(skill)
     isloggedin(id)
</pre>
</pre>
Return the player's level of the given skill.
Return true if the given ID is logged in.


=== getgmlevel ===
Often you shouldn't use this, but attachrid(id) instead
<pre>
    getgmlevel()
</pre>
Return the player's GM level.


=== getopt2 ===
=== marriage ===
<pre>
<pre>
     getopt2()
     marriage("otherplayer")
</pre>
</pre>
Return the player's opt2 flags.
Marry the attached player to the other player.


=== setopt2 ===
Return 1 on success and 0 on failure.
<pre>
    setopt2 flags;
</pre>
Set the player's opt2 flags.


=== checkoption ===
=== divorce ===
<pre>
<pre>
     checkoption(type)
     divorce()
</pre>
</pre>
Return 1 if the player has any of the given (XOR'ed) option bits. Usually only one is given.
Divorce the attached player from their partner


=== setoption ===
Return 1 on success and 0 on failure.
<pre>
    setoption type
</pre>
Set the player's option flags exactly (not OR'ing).


=== savepoint ===
=== getpartnerid2 ===
<pre>
<pre>
     savepoint "mapname", x, y;
     getpartnerid2()
</pre>
</pre>
Set the player's save point. Used e.g. by Soul Menhirs, and during the time travel quest.<!-- Don't remove this just because you can't figure out how to start it from this end. -->
Return the ID of the attached player's partner (0 is none).


=== gettimetick ===
=== getexp ===
<pre>
<pre>
     gettimetick(type)
     getexp base, job;
</pre>
</pre>
Return one of the ticks
Increase the types of experience.


type==0 (or other): milliseconds since some point in time, wraps every 50 days.
=== getinventorylist ===
type==1: time since midnight, UTC.
type==2: seconds since the epoch.
 
You should almost always use type 2.
 
=== gettime ===
<pre>
<pre>
     gettime(type)
     getinventorylist;
</pre>
</pre>
Get a component of the time (UTC).
Fill in some arrays of useful information: "@inventorylist_id", "@inventorylist_amount", "@inventorylist_equip".


1: second (0-59)
The arrays are not cleared between calls, use "@inventory_count".
2: minute (0-59)
3: hour (0-23)
4: day of week (0-6)
5: day of month (1-31)
6: month (1-12)
7: year (1902-2038)


=== gettimestr ===
=== getactivatedpoolskilllist ===
<pre>
<pre>
     gettimestr("format", length)
     getactivatedpoolskilllist;
</pre>
</pre>
Frontend for strftime(3).
Same, but only activated pool skills.


This function may be removed for technical reasons, please construct the string manually using gettime()
=== getunactivatedpoolskilllist ===
 
=== openstorage ===
<pre>
<pre>
     openstorage;
     getunactivatedpoolskilllist;
</pre>
</pre>
Open the player's storage.
Same, but only unactivated pool skills.
=== monster ===
<pre>
    monster "mapname", x, y, "string", class, count[, "event"];
</pre>
Spawn monsters at a point.


=== areamonster ===
=== poolskill ===
<pre>
<pre>
     areamonster "mapname", x0, y0, x1, y1, "string", class, count[, "event"];
     poolskill skill_id;
</pre>
</pre>
Spawn monsters in an area.
Activate a poolable skill.


=== killmonster ===
=== unpoolskill ===
<pre>
<pre>
     killmonster "mapname", "event";
     unpoolskill skill_id;
</pre>
</pre>
Kill monsters on a map.
Deactivate a poolable skill.


Unless it is "All", "event" must match the one used at spawn time.
=== misceffect ===
 
If "All" is given, this function properly preserves permanently respawning monsters.
 
=== killmonsterall ===
<pre>
<pre>
     killmonsterall "mapname";
     misceffect type, "player_name";
    misceffect type, being_id;
    misceffect type;
</pre>
</pre>
Kill all monsters unconditionally.
Display a miscellaneous effect on a being.


This command might prevent monsters from respawning. Instead use "killmonster" with "event" == "All".
In the third form, it will use the OID if possible, and fallback to the RID.


=== doevent ===
=== getlook ===
<pre>
<pre>
     doevent "event";
     getlook(type)
</pre>
</pre>
Manually invoke an NPC event.
Return part of the player's appearance:
val==1: hair
val==2: weapon
val==3: bottom
val==4: middle
val==5: top
val==6: hair color
val==8: shield
val==9: shoes


=== donpcevent ===
On failure, return -1.
<pre>
    donpcevent "event";
</pre>
Manually invoke an NPC event.


=== addtimer ===
=== getsavepoint ===
<pre>
<pre>
     addtimer tick, "event";
     getsavepoint(type)
</pre>
</pre>
This command is untested and might freeze the server.
type==0: Return savepoint map
type==1: Return savepoint x
type==2: Return savepoint y


=== deltimer ===
This is believed to be the only function (other than callfunc and callsub of course) that returns a different type depending on its arguments.
<pre>
    deltimer "event";
</pre>
This command is untested and might freeze the server.


=== initnpctimer ===
=== shop ===
<pre>
<pre>
     initnpctimer;
     shop "npcname";
</pre>
</pre>
Set the NPC's attached timer to tick 0 and start it.
Close the script and open the given NPC's shop.


=== stopnpctimer ===
=== isdead ===
<pre>
<pre>
     stopnpctimer;
     isdead()
</pre>
</pre>
Stop the NPC's attached timer.
Return 1 if the attached player is dead, else 0.


=== startnpctimer ===
=== fakenpcname ===
<pre>
<pre>
     startnpctimer;
     fakenpcname "name", "newname", new_sprite_id;
</pre>
</pre>
Start the NPC's attached timer, without setting the tick.
Change the appearance of an NPC.


=== setnpctimer ===
== Location Commands ==
<pre>
These are commands that have to do with the location of players
    setnpctimer tick;
</pre>
Set the NPC's timer to a specific tick.


=== getnpctimer ===
=== warp ===
<pre>
<pre>
     getnpctimer(type)
     warp "mapname", x, y;
</pre>
</pre>
Get the current tick of an NPC's timer.
Warp the attached player to the given location. "mapname" may have the special values "Random", "SavePoint", and "Save" (case-sensitive), but x and y are still required.


type==0: timer event tick (like setnpctimer)
=== isat ===
type==1: bool if it has a next timer.
type==2: timer amount
 
=== announce ===
<pre>
<pre>
     announce "message", flag;
     isat("mapname", x, y)
</pre>
</pre>
Do a GM message.
Return 1 if the attached player is at the given location, 0 otherwise.


If flag & 0xF == 0 forward it to all map servers.
=== areawarp ===
If flag & 0x8, message is from the OID (NPC? usually?) rather than the RID (player).
 
If (flag & 0x7) == 1, send to all on map.
If (flag & 0x7) == 2, send to all in line of sight.
If (flag & 0x7) == 3, send to self only.
If (flag & 0x7) == anything else, send to all clients.
 
=== mapannounce ===
<pre>
<pre>
     mapannounce "mapname", "message", flag;
     areawarp "src_map", x0, y0, x1, y1, "dst_map", x, y;
</pre>
Send an announcement to all players in map.
 
Only flag & 0x10 is interpreted, which does not work with the Mana client. So, flag must be 0.
 
=== areaannounce ===
<pre>
    areaannounce "mapname", x0, y0, x1, y1, "message", flag;
</pre>
</pre>
Send an announcement to all players in area.
Warp all players in the given area to the given location. The area is of square shape which has the diagonals x0,y0 and x1,y1.
 
Only flag & 0x10 is interpreted, which does not work with the Mana client. So, flag must be 0.


=== getusers ===
=== getusers ===
Line 603: Line 473:
=== getareausers ===
=== getareausers ===
<pre>
<pre>
     getareausers("mapname", x0, y0, x1, y1)
     getareausers("mapname", x0, y0, x1, y1, z)
</pre>
</pre>
Count users in an area.
Count users in an area.
z can be set to 1 or be left out to check for players who are alive.


=== getareadropitem ===
=== mapwarp ===
<pre>
<pre>
     getareadropitem("mapname", x0, y0, x1, y1, "itemname"[, delitems = 0]);
     mapwarp "src_map", "dst_map", x, y;
    getareadropitem("mapname", x0, y0, x1, y1, itemid[, delitems = 0]);
</pre>
</pre>
Count items on the floor in an area. If delitems, the items will be deleted as well.
Warp all players from source map to destination location.


=== enablenpc ===
=== npcwarp ===
<pre>
<pre>
     enablenpc "name";
     npcwarp x, y, "npcname";
</pre>
</pre>
Enable an NPC.
Move an NPC to a different location on the same map.


=== disablenpc ===
=== isin ===
<pre>
<pre>
     disablenpc "name";
     isin("mapname", x0, y0, x1, y1)
</pre>
</pre>
Disable an NPC.
Check if the player is in the area.


=== hideoffnpc ===
=== getx ===
<pre>
<pre>
     hideoffnpc "name";
     getx()
</pre>
</pre>
What does this do?
Return attached player's x coordinate.


=== hideonnpc ===
=== gety ===
<pre>
<pre>
     hideonnpc "name";
     gety()
</pre>
</pre>
What does this do?
Return attached player's y coordinate.


=== sc_start ===
=== getmap ===
<pre>
<pre>
     sc_start type, tick, val1[, beingid];
     getmap()
</pre>
</pre>
Apply a status effect to a player (or monster?).
Return attached player's current map.


type is one of the sc_* constants.
== Item Commands ==
These have to do with items or inventory.


=== sc_start2 ===
=== getitem ===
<pre>
<pre>
     sc_start2 type, tick, val1, chance[, beingid];
     getitem "itemname", count[, unused_argument[, playerid]];
    getitem itemid, count[, unused_argument[, playerid]];
"ii**"
</pre>
</pre>
Chance of applying a status effect, out of 10000.
Grant the attached player (or the given player) "count" copies of an item.
 
If itemname is unrecognized you get an iten (727) instead.


=== sc_end ===
;Warning:
<pre>
<pre>
     sc_end type;
     delitem: only deletes one item if applied to not-stackable item (equipment)
</pre>
    getitem: gives item stacked, even if it's equipment
Immediately end status effect on current player.
    fix: use a loop and only delete/give one item at a time</pre>


=== sc_check ===
=== makeitem ===
<pre>
<pre>
     sc_check(type)
     makeitem "itemname", count, "mapname", x, y;
    makeitem itemid, count, "mapname", x, y;
</pre>
</pre>
Whether a status effect is currently active.
Drop items on the ground.
 
The special "mapname" value "this" means the map of the attached player.


=== getscrate ===
=== delitem ===
<pre>
<pre>
     getscrate(type, rate[, being_id])
     delitem "itemname", count;
    delitem itemid, count;
</pre>
</pre>
If the sc is poison, modify rate by (3 + vit + luk/3) percent.
Remove items from the attached player's inventory.


=== resetlvl ===
This command is buggy if the player does not have enough of the item. And if the item is not stackable, the command will delete only one of them, even if a higher number is specified.
;Warning:
<pre>
<pre>
     resetlvl type;
     delitem: only deletes one item if applied to not-stackable item (equipment)
</pre>
    getitem: gives item stacked, even if it's equipment
    fix: use a loop and only delete/give one item at a time</pre>


=== resetstatus ===
=== countitem ===
<pre>
<pre>
     resetstatus;
     countitem("itemname")
    countitem(itemid)
</pre>
</pre>
Return the number of the given item in the player's inventory.


=== resetskill ===
=== checkweight ===
<pre>
<pre>
     resetskill;
     checkweight("itemname", count)
    checkweight(itemid, count)
</pre>
</pre>
Return 0 if adding "count" of the item would put player above max weight, 1 if it would still be less than max weight.
Also returns 0 if item does not exist.


=== changesex ===
=== getequipid ===
<pre>
<pre>
     changesex;
     getequipid(equip_point)
</pre>
</pre>
Ask the login server (via the char server) to toggle this account's sex, then kick the player.
Return the ID of the item in the given equip slot.
 
equip_point is one of the equip_* constants


=== attachrid ===
=== getequipname ===
<pre>
<pre>
     attachrid(id)
     getequipname(equip_point)
</pre>
</pre>
Change the being associated with this script.
Return the name of the item in the given equip slot.


Return true if such a player is logged in.
equip_point is one of the equip_* constants


=== detachrid ===
=== statusup2 ===
<pre>
<pre>
     detachrid;
     statusup2 bType, delta;
</pre>
</pre>
Detach the player associated with this script.
Permanently increase or decrease a stat.


=== isloggedin ===
=== bonus ===
<pre>
<pre>
     isloggedin(id)
     bonus bType, delta
</pre>
</pre>
Return true if the given ID is logged in.
Temporarily increase a stat. For use in item scripts only.


=== setmapflagnosave ===
=== skill ===
<pre>
<pre>
     setmapflagnosave "mapname", "savemap", x, y;
     skill id, level[, flag = 1];
</pre>
</pre>
Set the nosave flag and respawn location.
Grant a skill.
 
flag==0: permanent skill
flag==1: temporary skill (item scripts only)
 
(Untested)


=== setmapflag ===
=== setskill ===
<pre>
<pre>
     setmapflag "mapname", flag;
     setskill id, level;
</pre>
</pre>
Set an arbitrary mapflag.
Grant a skill permanently.


This function may be problematic in the stable version.
=== getskilllv ===
 
=== removemapflag ===
<pre>
<pre>
     removemapflag "mapname", flag;
     getskilllv(skill)
</pre>
</pre>
Unset an arbitrary mapflag.
Return the player's level of the given skill.


This function may be problematic in the stable version.
=== getgmlevel ===
 
=== pvpon ===
<pre>
<pre>
     pvpon "mapname";
     getgmlevel()
</pre>
</pre>
Allow PvP on a map.
Return the player's GM level.


=== pvpoff ===
=== getopt2 ===
<pre>
<pre>
     pvpoff "mapname";
     getopt2()
</pre>
</pre>
Deny PvP on a map.
Return the player's opt2 flags.


=== emotion ===
=== setopt2 ===
<pre>
<pre>
     emotion "i"
     setopt2 flags;
</pre>
</pre>
Show a smiley above the OID.
Set the player's opt2 flags.


=== marriage ===
=== savepoint ===
<pre>
<pre>
     marriage("otherplayer")
     savepoint "mapname", x, y;
</pre>
</pre>
Marry the attached player to the other player.
Set the player's save point. Used e.g. by Soul Menhirs, and during the time travel quest.<!-- Don't remove this just because you can't figure out how to start it from this end. -->


Return 1 on success and 0 on failure.
=== openstorage ===
 
=== divorce ===
<pre>
<pre>
     divorce()
     openstorage;
</pre>
</pre>
Divorce the attached player from their partner
Open the player's storage.
 
Return 1 on success and 0 on failure.


=== getitemname ===
=== getitemname ===
Line 774: Line 659:
Return the name of the item, or "Unknown Item".
Return the name of the item, or "Unknown Item".


=== getspellinvocation ===
=== nude ===
<pre>
<pre>
     getspellinvocation("spell-identifier")
     nude;
</pre>
</pre>
Return the #invocation used for a spell, or "...".
Unequip all items.


=== getanchorinvocation ===
=== unequipbyid ===
<pre>
<pre>
     getanchorinvocation "anchor-identifier"
     unequipbyid slot_id;
</pre>
</pre>
Return the invocation used for a teleport anchor (?)
Unequip whatever is in the slot


=== getpartnerid2 ===
=== getareadropitem ===
<pre>
<pre>
     getpartnerid2()
     getareadropitem("mapname", x0, y0, x1, y1, "itemname"[, delitems = 0]);
    getareadropitem("mapname", x0, y0, x1, y1, itemid[, delitems = 0]);
</pre>
</pre>
Return the ID of the attached player's partner (0 is none).
Count items on the floor in an area. If delitems, the items will be deleted as well.
 
== Common Functions ==
These are not mostly not related to the RPG or the scripting language.


=== getexp ===
=== rand ===
<pre>
<pre>
     getexp base, job;
     rand(range)
    rand(min, max)
</pre>
</pre>
Increase the types of experience.
In the first form, return a random number between 0 (inclusive) and range (exclusive). Return 0 if range is not positive.
In the second form, return a random number between min and max, inclusive. Min and max may be swapped.


=== getinventorylist ===
=== gettimetick ===
<pre>
<pre>
     getinventorylist;
     gettimetick(type)
</pre>
</pre>
Fill in some arrays of useful information: "@inventorylist_id", "@inventorylist_amount", "@inventorylist_equip".
Return one of the ticks
 
type==0 (or other): milliseconds since some point in time, wraps every 50 days.
type==1: time since midnight, UTC.
type==2: seconds since the epoch.


The arrays are not cleared between calls, use "@inventory_count".
You should almost always use type 2.


=== getskilllist ===
=== gettime ===
<pre>
<pre>
     getskilllist;
     gettime(type)
</pre>
</pre>
Fill in some arrays of useful information: "@skilllist_id", "@skilllist_lv", "@skilllist_flag".
Get a component of the time (UTC).


The arrays are not cleared between calls, use "@skill_count".
1: second (0-59)
2: minute (0-59)
3: hour (0-23)
4: day of week (0-6)
5: day of month (1-31)
6: month (1-12)
7: year (1902-2038)
 
== Timers and Events ==
These have to do with transfering control in ways that are not immediately obvious.
 
The most common ones are initnpctimer or startnpctimer, stopnpctimer, and setnpctimer.


=== getpoolskilllist ===
=== donpcevent ===
<pre>
<pre>
     getpoolskilllist;
     donpcevent "NpcName::Event";
</pre>
</pre>
Same, but only poolable skills.
Manually invoke an NPC event.


=== getactivatedpoolskilllist ===
=== addtimer ===
<pre>
<pre>
     getactivatedpoolskilllist;
     addtimer tick, "event";
</pre>
</pre>
Same, but only activated pool skills.
Invoke an NPC event after a delay, for the attached NPC.
 
This command does the same thing as areatimer, but for only the attached player.


=== getunactivatedpoolskilllist ===
=== initnpctimer ===
<pre>
<pre>
     getunactivatedpoolskilllist;
     initnpctimer;
</pre>
</pre>
Same, but only unactivated pool skills.
Set the NPC's attached timer to tick 0 and start it.
 
This is equivalent to setnpctimer, 0; startnpctimer;


=== poolskill ===
=== stopnpctimer ===
<pre>
<pre>
     poolskill skill_id;
     stopnpctimer;
</pre>
</pre>
Activate a poolable skill.
Stop the NPC's attached timer.
 
This DOES NOT do anything about the tick. But that's okay, you should normally be starting it with initnpctimer.


=== unpoolskill ===
=== startnpctimer ===
<pre>
<pre>
     unpoolskill skill_id;
     startnpctimer;
</pre>
</pre>
Deactivate a poolable skill.
Start the NPC's attached timer, without setting the tick.


=== checkpoolskill ===
=== setnpctimer ===
<pre>
<pre>
     checkpoolskill(skill_id)
     setnpctimer tick;
</pre>
</pre>
Check if a pool skill is activated
Set the NPC's timer to a specific tick. Generally, this is only useful for tick 0.


=== clearitem ===
=== getnpctimer ===
<pre>
<pre>
     clearitem;
     getnpctimer(type)
</pre>
</pre>
Remove all items from a player's inventory.
Get the current tick of an NPC's timer.


=== misceffect ===
type==0: timer event tick (like setnpctimer)
type==1: bool if it has a next timer.
type==2: timer amount
 
=== mobcount ===
<pre>
    mobcount("mapname", "event")
</pre>
Count the remaining mobs from the spawn with the given event. Has an offset of -1.
 
=== areatimer ===
<pre>
<pre>
     misceffect type, "player_name";
     areatimer "mapname", x0, y0, x1, y1, tick, "event";
    misceffect type, being_id;
    misceffect type;
</pre>
</pre>
Display a miscellaneous effect on a being.
Add a PC event timer to all players in the area.
 
After "tick" milliseconds, the given NPC event will fire with each player as the RID.


In the third form, it will use the OID if possible, and fallback to the RID.
== Unsorted Commands ==
These are commands that still need sorting, please edit this page, see talk page for category (and subcategory?) suggestions.


=== strmobinfo ===
=== strnpcinfo ===
<pre>
<pre>
     strmobinfo(num, class)
     strnpcinfo(number[, "npc"])
</pre>
</pre>
Info about a type of mob:
Returns information about the current npc or specified npc. '''0''' => full name. '''1''' => anything that comes before # in the name. '''2''' => anything that comes after the # in the name. '''3''' => map name.
num==1: name
num==2: jname
num==3: lv
num==4: maxhp
num==5: maxsp
num==6: base_exp
num==7: job_exp


=== specialeffect ===
=== getnpcx ===
<pre>
<pre>
     specialeffect type;
     getnpcx(["npc"])
</pre>
</pre>
Display a special effect on the OID.
Returns the X location of the current or specified npc.


Same as "misceffect", but does not fallback when there is no OID.
=== getnpcy ===
<pre>
    getnpcy(["npc"])
</pre>
Returns the Y location of the current or specified npc.


=== specialeffect2 ===
=== monster ===
<pre>
<pre>
     specialeffect2 type;
     monster "mapname", x, y, "string", class, count[, "event"];
</pre>
</pre>
Same as "misceffect", but works when there is an OID.
Spawn monsters at a point. If you define an OnDead event using a trigger area then the event is shot only inside that area, hence the event is ignored when the monster is killed outside the trigger area.


=== nude ===
=== areamonster ===
<pre>
<pre>
     nude;
     areamonster "mapname", x0, y0, x1, y1, "string", class, count[, "event"];
</pre>
</pre>
Unequip all items.
Spawn monsters in an area. If you define an OnDead event using a trigger area then the event is shot only inside that area, hence the event is ignored when the monster is killed outside the trigger area.


=== mapwarp ===
=== killmonster ===
<pre>
<pre>
     mapwarp "src_map", "dst_map", x, y;
     killmonster "mapname", "event";
</pre>
</pre>
Warp all players from source map to destination location.
Kill monsters on a map.
 
Unless it is "All", "event" must match the one used at spawn time.
 
If "All" is given, this function properly preserves permanently respawning monsters.


=== inittimer ===
=== enablenpc ===
<pre>
<pre>
     inittimer;
     enablenpc "name";
</pre>
</pre>
Setup an NPC's event timers.
Enable an NPC.


=== stoptimer ===
=== disablenpc ===
<pre>
<pre>
     stoptimer;
     disablenpc "name";
</pre>
</pre>
Unload an NPC's event timers.
Disable an NPC.


=== cmdothernpc ===
=== setmapflag ===
<pre>
<pre>
     cmdothernpc "npc", "Foo";
     setmapflag "mapname", flag;
</pre>
</pre>
Invoke ::OnCommandFoo
Set an arbitrary mapflag.


=== gmcommand ===
=== removemapflag ===
<pre>
<pre>
     gmcommand "@command maybe with arguments";
     removemapflag "mapname", flag;
</pre>
</pre>
Run a GM command, at level 99.
Unset an arbitrary mapflag.


=== npcwarp ===
=== getmapflag ===
<pre>
<pre>
     npcwarp x, y, "npcname";
     getmapflag("mapname", flag);
</pre>
</pre>
Move an NPC to a different location on the same map.
Check an arbitrary mapflag.


=== message ===
=== pvp ===
<pre>
<pre>
     message "player", "message";
     pvp number;
</pre>
</pre>
Display (in chat?) a message from the server.
Changes the pvp channel of the attached user to the specified channel. Please only use channels above 19 as 0-19 are reserved as special channels. To remove a user from the channel simply do pvp 0;


=== npctalk ===
=== getpvpflag ===
<pre>
<pre>
     npctalk "message"
     getpvpflag(number)
</pre>
</pre>
Make an NPC say something publicly.
Gets pvp information for the attached user. 0 returns the pvp channel of the user. 1 returns true if the user is on @hide or else false.


Note: in many cases areaannounce is a better choice.


=== hasitems ===
=== pvpon ===
<pre>
<pre>
     hasitems()
     pvpon "mapname";
</pre>
</pre>
Return 1 if the player has any inventory, 0 otherwise.
Allow PvP on a map.


=== mobcount ===
=== pvpoff ===
<pre>
<pre>
     mobcount("mapname", "event")
     pvpoff "mapname";
</pre>
</pre>
Count the remaining mobs from the spawn with the given event.
Deny PvP on a map.


=== getlook ===
=== emotion ===
<pre>
<pre>
     getlook(type)
     emotion emote_index;
</pre>
</pre>
Return part of the player's appearance:
Show a smiley above the OID.
val==1: hair
val==2: weapon
val==3: bottom
val==4: middle
val==5: top
val==6: hair color
val==8: shield
val==9: shoes


On failure, return -1.
=== getspellinvocation ===
<pre>
    getspellinvocation("spell-identifier")
</pre>
Return the #invocation used for a spell, or "...".


=== getsavepoint ===
=== specialeffect ===
<pre>
<pre>
     getsavepoint(type)
     specialeffect type;
</pre>
</pre>
type==0: Return savepoint map
Display a special effect on the OID.
type==1: Return savepoint x
type==2: Return savepoint y


This is believed to be the only function (other than callfunc and callsub of course) that returns a different type depending on its arguments.
Same as "misceffect", but does not fallback when there is no OID.


=== areatimer ===
=== specialeffect2 ===
<pre>
<pre>
     areatimer "mapname", x0, y0, x1, y1, tick, "event";
     specialeffect2 type;
</pre>
</pre>
Add a PC event timer to all players in the area.
Same as "misceffect", but works when there is an OID.


This function is untested.
=== mapexit ===
<pre>
    mapexit;
</pre>
Exits the map server.


=== isin ===
=== bonus2 ===
<pre>
<pre>
     isin("mapname", x0, y0, x1, y1)
     bonus2 player, type, Amount, Tick;
</pre>
</pre>
Check if the player is in the area.
Currently the only type is bHPDrainRate. This takes Amount per Tick in HPs from player.


=== shop ===
=== getitemlink ===
<pre>
<pre>
     shop "npcname"
     getitemlink("ItemName");
</pre>
</pre>
Close the script and open the given NPC's shop.
Returns the Manaplus link for use in scripts [@@ID|JName@@]


=== isdead ===
=== npcareawarp ===
<pre>
<pre>
     isdead()
     npcareawarp x0, y0, x1, y1, CollisionBool, "NPC Name";
</pre>
</pre>
Return 1 if the attached player is dead, else 0.
Warps a NPC to somewhere within the area. If Collision Bool is set to 1 it will spawn on collision, else 0 is not on collision.


=== fakenpcname ===
=== iscollision ===
<pre>
<pre>
     fakenpcname "name", "newname", new_sprite_id;
     iscollision map.gat, x, y, type;
</pre>
</pre>
Change the appearance of an NPC.
Checks if collision is of a type. (Types will be cast as CONST in the const.txt file)
 
== Deprecated ==


=== unequipbyid ===
=== itemheal ===
This command has been merged into [[Dev:TmwAthena_Scripting_Reference#heal|heal]]. The equivalent is :
<pre>
<pre>
     unequipbyid slot_id
     heal Hp, Sp, true;
</pre>
</pre>
Unequip whatever is in the slot


=== getx ===
=== percentheal ===
This command has been completely removed. Please use inline math instead. For example to remove 30% hp you would do:
<pre>
<pre>
     getx()
     heal ((MaxHp/10) * -3), 0;
</pre>
</pre>
Return attached player's x coordinate.


=== gety ===
=== killmonsterall ===
This command has been deprecated and [[Dev:TmwAthena_Scripting_Reference#killmonster|killmonster]] should be used instead:
<pre>
<pre>
     gety()
     killmonster "mapname", "All";
</pre>
</pre>
Return attached player's y coordinate.
 
=== cmdothernpc ===
This command has been deprecated in favor of [[Dev:TmwAthena_Scripting_Reference#donpcevent|donpcevent]].
 
[[Category:Development]]

Latest revision as of 19:25, 23 January 2022

<metakey>Script Language, Code, Source, eAthena Script, AST</metakey> <metadesc>The Mana World Scripting Language Reference</metadesc>

TMWA's scripting wiki pages:

Legacy:Scripting Basics - Legacy:Scripting Standards - Legacy:Scripting Reference

For questions feel free to contact us on IRC and/or on our forum.

These are articles that require updating, moving to archive or deletion (see also Template:Delete).


This page is a reference for commands believed to work in the eAthena scripting language still used by tmwAthena.

Note: A number of problematic commands have been removed from this list, but not all commands have been tested.


Language Commands[edit]

These are command that are closely tied to the language itself.

goto[edit]

    goto L_1;

Unconditionally jump to a label. Often used in an "if" body.

callsub[edit]

    callsub S_labelname;

Jump to the given label. When the "return" statement is executed, continue on the next line.

It might also be possible to use this as a function, if the form of return with a value is used, but we use temporary variables instead.

callfunc[edit]

    callfunc "function_name";

Jump to the given function script. When the "return" statement is executed, continue on the next line of this script.

It might also be possible to use this as a function, if the form of return with a value is used, but we use temporary variables instead.

"return" is broken if this is used from within an if(). If you need a conditional callfunc, first goto a label.

return[edit]

    return;

Return from this script or sublabel to the calling function.

It is unknown what happens if this is used from the top-level script, use "close" or "end" instead.

set[edit]

    set variable, expression;

Very common command, to set variables.

setarray[edit]

    setarray arrayvariable, val1, val2, ...;

Set elements of an array. Previous elements are not cleared. At most 128 elements can be assigned.

It is currently possible, but deprecated, to specify a (zero-based) array index to start at the given part of an array. It's pretty amazing that that code works anyway.

Remember that there are no permanent arrays, only temporary.

cleararray[edit]

    cleararray variable, value, count;

Fill an array with "count" copies of "value".

getarraysize[edit]

    getarraysize variable;

Get the size of an array. Returns 1 even when empty.

The size of an array is simply one more than the index of the last nonzero integer or nonempty string.

WARNING: most functions that set an array do not bother to clear out high indices. You should almost always use an explicitly-provided size instead.

getelementofarray[edit]

    arrayname[index_expr]

returns index_expr of that array.

if[edit]

    if (condition) condition_command [conditional_command_args, ...];

If condition is zero, do nothing. Else, evaluate the conditional command.

The only thing special about the if command is the lack of commas during parsing (from my reading this is only a warning?). During execution it is perfectly normal.

Note: you must not use a callsub or callfunc as conditional_command.

end[edit]

    end;

Stop executing the script.

Don't use this if you have opened a dialog to the player, use "close" instead. Or, use "close2" and *then* "end".

debugmes[edit]

    debugmes "string"

Print a message to stdout.

Message Commands[edit]

These are commands for dialog or one-way chat with players.

mes[edit]

    mes "string";

Display a line of text to the player. If a dialog box is not already open for the attached NPC, one will be created.

It is unknown if the client properly supports dialog with multiple NPCs simultaneously. Note that the server only allows each account one paused script at a time, so it probably wouldn't work anyway.

If you need to include the " character inside the message, (especially for dialogs) insert it as \". When doing several messages without a next; in between, there should be only a single \" at the beginning and the end each.

Example: 

mes "[Me Myself]";
mes "";
mes "(I clear my throat)"
mes "";
mes "\"I start talking here, and don't close the quotation marks, because I'm not yet done talking.";
mes "And start a new line, but without new quotation marks.";
mes "Here I stop talking, so I close the quotation marks.\"";

gives: [Me Myself]

(I clear my throat)

"I start talking here, and don't close the quotation marks, because I'm not yet done talking.
And start a new line, but without new quotation marks.
Here I stop talking, so I close the quotation marks."

next[edit]

    next;

Stop the script until the user presses "Next" in the dialog.

close[edit]

    close;

Stop executing the script and give the user a "Close" button in the dialog.

close2[edit]

    close2;

Stop the script until the user presses the "Close" button in the dialog, then keep executing the script.

WARNING: unlike close, this command is a blocking command, the usual caveats apply.

menu[edit]

    menu
        "option 1", L_1,
        "option 2", L_2;

Display a list of choices to the player, then branch to the specified label.

Additionally, the temporary variable "@menu" is set to the 1-based index of the choice.

The options must not contain the character ":", as the protocol uses it as a separator.

input[edit]

    input variable_name;

Input an integer or string to the given variable, depending on whether has the '$' string postfix.

The implementation allows variable_name to be omitted if input is an integer, in case l14 is used. Don't use this.

announce[edit]

    announce "message", flag;

Do a GM message.

If flag & 0xF == 0 forward it to all map servers. If flag & 0x8, message is from the OID (NPC? usually?) rather than the RID (player).

If (flag & 0x7) == 1, send to all on map. If (flag & 0x7) == 2, send to all in line of sight. If (flag & 0x7) == 3, send to self only. If (flag & 0x7) == anything else, send to all clients.

mapannounce[edit]

    mapannounce "mapname", "message", flag;

Send an announcement to all players in map.

Only flag & 0x10 is interpreted, which does not work with the Mana client. So, flag must be 0.

message[edit]

    message "player", "message";

Display (in chat) a message from the server to a single user.

npctalk[edit]

    npctalk "message";

Make an NPC say something publicly.

Note: in many cases areaannounce is a better choice.

Character Commands[edit]

These have to do with attributes of the player.

setlook[edit]

    setlook type, value;

Set an aspect of a character's appearance. Used e.g. by the barber.

There are constant provided for the LOOK type, and for hair color and hair style.

heal[edit]

    heal hp, sp[, boolean];

Increase or decrease the player's hp and sp. Add ,1 at the end to make it heal gradually.

readparam[edit]

    readparam(type[, "playername"])

Return one of the core parameters of a player.

type is one of the bCamelCase constants, see db/const.txt

getcharid[edit]

    getcharid(type[ "playername"])

Get an id of the attached (or given) player.

Type is: 0: char id 1: party id 2: guild id (deprecated) 3: account id

You usually want 3.

strcharinfo[edit]

    strcharinfo(num)

Return string information about an account: num==0: name num==1: party name num==2: guild name (deprecated)

sc_start[edit]

    sc_start type, tick, val1[, beingid];

Apply a status effect to a player (or monster?).

type is one of the sc_* constants.

sc_end[edit]

    sc_end type;

Immediately end status effect on current player.

sc_check[edit]

    sc_check(type)

Whether a status effect is currently active.

resetstatus[edit]

    resetstatus;

changesex[edit]

    changesex;

Ask the login server (via the char server) to toggle this account's sex, then kick the player.

attachrid[edit]

    attachrid(id)

Change the being associated with this script.

Return true if such a player is logged in.

detachrid[edit]

    detachrid;

Detach the player associated with this script.

isloggedin[edit]

    isloggedin(id)

Return true if the given ID is logged in.

Often you shouldn't use this, but attachrid(id) instead

marriage[edit]

    marriage("otherplayer")

Marry the attached player to the other player.

Return 1 on success and 0 on failure.

divorce[edit]

    divorce()

Divorce the attached player from their partner

Return 1 on success and 0 on failure.

getpartnerid2[edit]

    getpartnerid2()

Return the ID of the attached player's partner (0 is none).

getexp[edit]

    getexp base, job;

Increase the types of experience.

getinventorylist[edit]

    getinventorylist;

Fill in some arrays of useful information: "@inventorylist_id", "@inventorylist_amount", "@inventorylist_equip".

The arrays are not cleared between calls, use "@inventory_count".

getactivatedpoolskilllist[edit]

    getactivatedpoolskilllist;

Same, but only activated pool skills.

getunactivatedpoolskilllist[edit]

    getunactivatedpoolskilllist;

Same, but only unactivated pool skills.

poolskill[edit]

    poolskill skill_id;

Activate a poolable skill.

unpoolskill[edit]

    unpoolskill skill_id;

Deactivate a poolable skill.

misceffect[edit]

    misceffect type, "player_name";
    misceffect type, being_id;
    misceffect type;

Display a miscellaneous effect on a being.

In the third form, it will use the OID if possible, and fallback to the RID.

getlook[edit]

    getlook(type)

Return part of the player's appearance: val==1: hair val==2: weapon val==3: bottom val==4: middle val==5: top val==6: hair color val==8: shield val==9: shoes

On failure, return -1.

getsavepoint[edit]

    getsavepoint(type)

type==0: Return savepoint map type==1: Return savepoint x type==2: Return savepoint y

This is believed to be the only function (other than callfunc and callsub of course) that returns a different type depending on its arguments.

shop[edit]

    shop "npcname";

Close the script and open the given NPC's shop.

isdead[edit]

    isdead()

Return 1 if the attached player is dead, else 0.

fakenpcname[edit]

    fakenpcname "name", "newname", new_sprite_id;

Change the appearance of an NPC.

Location Commands[edit]

These are commands that have to do with the location of players

warp[edit]

    warp "mapname", x, y;

Warp the attached player to the given location. "mapname" may have the special values "Random", "SavePoint", and "Save" (case-sensitive), but x and y are still required.

isat[edit]

    isat("mapname", x, y)

Return 1 if the attached player is at the given location, 0 otherwise.

areawarp[edit]

    areawarp "src_map", x0, y0, x1, y1, "dst_map", x, y;

Warp all players in the given area to the given location. The area is of square shape which has the diagonals x0,y0 and x1,y1.

getusers[edit]

    getusers(type)

Count users.

If flag & 0x8, base on OID instead of RID. If (flag & 0x7) == 0, return users on the map. If (flag & 0x7) == 1, return users on the server.

getmapusers[edit]

    getmapusers("mapname")

Count users on a given map.

getareausers[edit]

    getareausers("mapname", x0, y0, x1, y1, z)

Count users in an area. z can be set to 1 or be left out to check for players who are alive.

mapwarp[edit]

    mapwarp "src_map", "dst_map", x, y;

Warp all players from source map to destination location.

npcwarp[edit]

    npcwarp x, y, "npcname";

Move an NPC to a different location on the same map.

isin[edit]

    isin("mapname", x0, y0, x1, y1)

Check if the player is in the area.

getx[edit]

    getx()

Return attached player's x coordinate.

gety[edit]

    gety()

Return attached player's y coordinate.

getmap[edit]

    getmap()

Return attached player's current map.

Item Commands[edit]

These have to do with items or inventory.

getitem[edit]

    getitem "itemname", count[, unused_argument[, playerid]];
    getitem itemid, count[, unused_argument[, playerid]];
"ii**"

Grant the attached player (or the given player) "count" copies of an item.

If itemname is unrecognized you get an iten (727) instead.

Warning
    delitem: only deletes one item if applied to not-stackable item (equipment)
    getitem: gives item stacked, even if it's equipment
    fix: use a loop and only delete/give one item at a time

makeitem[edit]

    makeitem "itemname", count, "mapname", x, y;
    makeitem itemid, count, "mapname", x, y;

Drop items on the ground.

The special "mapname" value "this" means the map of the attached player.

delitem[edit]

    delitem "itemname", count;
    delitem itemid, count;

Remove items from the attached player's inventory.

This command is buggy if the player does not have enough of the item. And if the item is not stackable, the command will delete only one of them, even if a higher number is specified.

Warning
    delitem: only deletes one item if applied to not-stackable item (equipment)
    getitem: gives item stacked, even if it's equipment
    fix: use a loop and only delete/give one item at a time

countitem[edit]

    countitem("itemname")
    countitem(itemid)

Return the number of the given item in the player's inventory.

checkweight[edit]

    checkweight("itemname", count)
    checkweight(itemid, count)

Return 0 if adding "count" of the item would put player above max weight, 1 if it would still be less than max weight. Also returns 0 if item does not exist.

getequipid[edit]

    getequipid(equip_point)

Return the ID of the item in the given equip slot.

equip_point is one of the equip_* constants

getequipname[edit]

    getequipname(equip_point)

Return the name of the item in the given equip slot.

equip_point is one of the equip_* constants

statusup2[edit]

    statusup2 bType, delta;

Permanently increase or decrease a stat.

bonus[edit]

    bonus bType, delta

Temporarily increase a stat. For use in item scripts only.

skill[edit]

    skill id, level[, flag = 1];

Grant a skill.

flag==0: permanent skill flag==1: temporary skill (item scripts only)

(Untested)

setskill[edit]

    setskill id, level;

Grant a skill permanently.

getskilllv[edit]

    getskilllv(skill)

Return the player's level of the given skill.

getgmlevel[edit]

    getgmlevel()

Return the player's GM level.

getopt2[edit]

    getopt2()

Return the player's opt2 flags.

setopt2[edit]

    setopt2 flags;

Set the player's opt2 flags.

savepoint[edit]

    savepoint "mapname", x, y;

Set the player's save point. Used e.g. by Soul Menhirs, and during the time travel quest.

openstorage[edit]

    openstorage;

Open the player's storage.

getitemname[edit]

    getitemname("itemname")
    getitemname(itemid)

Return the name of the item, or "Unknown Item".

nude[edit]

    nude;

Unequip all items.

unequipbyid[edit]

    unequipbyid slot_id;

Unequip whatever is in the slot

getareadropitem[edit]

    getareadropitem("mapname", x0, y0, x1, y1, "itemname"[, delitems = 0]);
    getareadropitem("mapname", x0, y0, x1, y1, itemid[, delitems = 0]);

Count items on the floor in an area. If delitems, the items will be deleted as well.

Common Functions[edit]

These are not mostly not related to the RPG or the scripting language.

rand[edit]

    rand(range)
    rand(min, max)

In the first form, return a random number between 0 (inclusive) and range (exclusive). Return 0 if range is not positive. In the second form, return a random number between min and max, inclusive. Min and max may be swapped.

gettimetick[edit]

    gettimetick(type)

Return one of the ticks

type==0 (or other): milliseconds since some point in time, wraps every 50 days. type==1: time since midnight, UTC. type==2: seconds since the epoch.

You should almost always use type 2.

gettime[edit]

    gettime(type)

Get a component of the time (UTC).

1: second (0-59) 2: minute (0-59) 3: hour (0-23) 4: day of week (0-6) 5: day of month (1-31) 6: month (1-12) 7: year (1902-2038)

Timers and Events[edit]

These have to do with transfering control in ways that are not immediately obvious.

The most common ones are initnpctimer or startnpctimer, stopnpctimer, and setnpctimer.

donpcevent[edit]

    donpcevent "NpcName::Event";

Manually invoke an NPC event.

addtimer[edit]

    addtimer tick, "event";

Invoke an NPC event after a delay, for the attached NPC.

This command does the same thing as areatimer, but for only the attached player.

initnpctimer[edit]

    initnpctimer;

Set the NPC's attached timer to tick 0 and start it.

This is equivalent to setnpctimer, 0; startnpctimer;

stopnpctimer[edit]

    stopnpctimer;

Stop the NPC's attached timer.

This DOES NOT do anything about the tick. But that's okay, you should normally be starting it with initnpctimer.

startnpctimer[edit]

    startnpctimer;

Start the NPC's attached timer, without setting the tick.

setnpctimer[edit]

    setnpctimer tick;

Set the NPC's timer to a specific tick. Generally, this is only useful for tick 0.

getnpctimer[edit]

    getnpctimer(type)

Get the current tick of an NPC's timer.

type==0: timer event tick (like setnpctimer) type==1: bool if it has a next timer. type==2: timer amount

mobcount[edit]

    mobcount("mapname", "event")

Count the remaining mobs from the spawn with the given event. Has an offset of -1.

areatimer[edit]

    areatimer "mapname", x0, y0, x1, y1, tick, "event";

Add a PC event timer to all players in the area.

After "tick" milliseconds, the given NPC event will fire with each player as the RID.

Unsorted Commands[edit]

These are commands that still need sorting, please edit this page, see talk page for category (and subcategory?) suggestions.

strnpcinfo[edit]

    strnpcinfo(number[, "npc"])

Returns information about the current npc or specified npc. 0 => full name. 1 => anything that comes before # in the name. 2 => anything that comes after the # in the name. 3 => map name.

getnpcx[edit]

    getnpcx(["npc"])

Returns the X location of the current or specified npc.

getnpcy[edit]

    getnpcy(["npc"])

Returns the Y location of the current or specified npc.

monster[edit]

    monster "mapname", x, y, "string", class, count[, "event"];

Spawn monsters at a point. If you define an OnDead event using a trigger area then the event is shot only inside that area, hence the event is ignored when the monster is killed outside the trigger area.

areamonster[edit]

    areamonster "mapname", x0, y0, x1, y1, "string", class, count[, "event"];

Spawn monsters in an area. If you define an OnDead event using a trigger area then the event is shot only inside that area, hence the event is ignored when the monster is killed outside the trigger area.

killmonster[edit]

    killmonster "mapname", "event";

Kill monsters on a map.

Unless it is "All", "event" must match the one used at spawn time.

If "All" is given, this function properly preserves permanently respawning monsters.

enablenpc[edit]

    enablenpc "name";

Enable an NPC.

disablenpc[edit]

    disablenpc "name";

Disable an NPC.

setmapflag[edit]

    setmapflag "mapname", flag;

Set an arbitrary mapflag.

removemapflag[edit]

    removemapflag "mapname", flag;

Unset an arbitrary mapflag.

getmapflag[edit]

    getmapflag("mapname", flag);

Check an arbitrary mapflag.

pvp[edit]

    pvp number;

Changes the pvp channel of the attached user to the specified channel. Please only use channels above 19 as 0-19 are reserved as special channels. To remove a user from the channel simply do pvp 0;

getpvpflag[edit]

    getpvpflag(number)

Gets pvp information for the attached user. 0 returns the pvp channel of the user. 1 returns true if the user is on @hide or else false.


pvpon[edit]

    pvpon "mapname";

Allow PvP on a map.

pvpoff[edit]

    pvpoff "mapname";

Deny PvP on a map.

emotion[edit]

    emotion emote_index;

Show a smiley above the OID.

getspellinvocation[edit]

    getspellinvocation("spell-identifier")

Return the #invocation used for a spell, or "...".

specialeffect[edit]

    specialeffect type;

Display a special effect on the OID.

Same as "misceffect", but does not fallback when there is no OID.

specialeffect2[edit]

    specialeffect2 type;

Same as "misceffect", but works when there is an OID.

mapexit[edit]

    mapexit;

Exits the map server.

bonus2[edit]

    bonus2 player, type, Amount, Tick;

Currently the only type is bHPDrainRate. This takes Amount per Tick in HPs from player.

getitemlink[edit]

    getitemlink("ItemName");

Returns the Manaplus link for use in scripts [@@ID|JName@@]

npcareawarp[edit]

    npcareawarp x0, y0, x1, y1, CollisionBool, "NPC Name";

Warps a NPC to somewhere within the area. If Collision Bool is set to 1 it will spawn on collision, else 0 is not on collision.

iscollision[edit]

    iscollision map.gat, x, y, type;

Checks if collision is of a type. (Types will be cast as CONST in the const.txt file)

Deprecated[edit]

itemheal[edit]

This command has been merged into heal. The equivalent is : 

    heal Hp, Sp, true;

percentheal[edit]

This command has been completely removed. Please use inline math instead. For example to remove 30% hp you would do: 

    heal ((MaxHp/10) * -3), 0;

killmonsterall[edit]

This command has been deprecated and killmonster should be used instead: 

    killmonster "mapname", "All";

cmdothernpc[edit]

This command has been deprecated in favor of donpcevent.

Retrieved from "https://oldwiki.devbox.themanaworld.org/index.php?title=Classic:TmwAthena_Scripting_Reference&oldid=55256"