Classic:TmwAthena Scripting Reference: Difference between revisions

From The Mana World
← Older edit
Jenalya (talk | contribs)
64 edits
→monster: Add note about behaviour of event monsters in trigger area NPCs.
mNo edit summary
 
(49 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...;
     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.
Line 37: Line 45:
<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 74: 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 87: 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 118: 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 132: Line 111:
</pre>
</pre>
Print a message to stdout.
Print a message to stdout.


== Message Commands ==
== Message Commands ==
Line 146: 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 171: 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 207: Line 202:
</pre>
</pre>
Send an announcement to all players in map.
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>
Send an announcement to all players in area.


Only flag & 0x10 is interpreted, which does not work with the Mana client. So, flag must be 0.
Only flag & 0x10 is interpreted, which does not work with the Mana client. So, flag must be 0.
Line 245: Line 232:
=== 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>
</pre>
Increase or decrease the player's hp and sp, for use in item scripts.
Increase or decrease the player's hp and sp. Add ,1 at the end to make it heal gradually.
 
=== 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.


=== readparam ===
=== readparam ===
Line 284: Line 257:


You usually want 3.
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 313: Line 274:


type is one of the sc_* constants.
type is one of the sc_* constants.
=== sc_start2 ===
<pre>
    sc_start2 type, tick, val1, chance[, beingid];
</pre>
Chance of applying a status effect, out of 10000.


=== sc_end ===
=== sc_end ===
Line 331: Line 286:
</pre>
</pre>
Whether a status effect is currently active.
Whether a status effect is currently active.
=== getscrate ===
<pre>
    getscrate(type, rate[, being_id])
</pre>
If the sc is poison, modify rate by (3 + vit + luk/3) percent.
The form that accepts a being_id is broken in the current stable version of the server.
=== resetlvl ===
<pre>
    resetlvl type;
</pre>


=== resetstatus ===
=== resetstatus ===
<pre>
<pre>
     resetstatus;
     resetstatus;
</pre>
=== resetskill ===
<pre>
    resetskill;
</pre>
</pre>


Line 418: Line 355:


The arrays are not cleared between calls, use "@inventory_count".
The arrays are not cleared between calls, use "@inventory_count".
=== getskilllist ===
<pre>
    getskilllist;
</pre>
Fill in some arrays of useful information: "@skilllist_id", "@skilllist_lv", "@skilllist_flag".
The arrays are not cleared between calls, use "@skill_count".
=== getpoolskilllist ===
<pre>
    getpoolskilllist;
</pre>
Same, but only poolable skills.


=== getactivatedpoolskilllist ===
=== getactivatedpoolskilllist ===
Line 456: Line 379:
</pre>
</pre>
Deactivate a poolable skill.
Deactivate a poolable skill.
=== checkpoolskill ===
<pre>
    checkpoolskill(skill_id)
</pre>
Check if a pool skill is activated


=== misceffect ===
=== misceffect ===
Line 536: Line 453:
     areawarp "src_map", x0, y0, x1, y1, "dst_map", x, y;
     areawarp "src_map", x0, y0, x1, y1, "dst_map", x, y;
</pre>
</pre>
Warp all players in the given area to the given location.
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 ===
=== getusers ===
Line 556: 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.


=== mapwarp ===
=== mapwarp ===
Line 589: Line 507:
</pre>
</pre>
Return attached player's y coordinate.
Return attached player's y coordinate.
=== getmap ===
<pre>
    getmap()
</pre>
Return attached player's current map.


== Item Commands ==
== Item Commands ==
Line 602: Line 526:


If itemname is unrecognized you get an iten (727) instead.
If itemname is unrecognized you get an iten (727) instead.
;Warning:
<pre>
    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</pre>


=== makeitem ===
=== makeitem ===
Line 619: Line 549:
Remove items from the attached player's inventory.
Remove items from the attached player's inventory.


This command is buggy if the player does not have enough of the item.
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>
    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</pre>


=== countitem ===
=== countitem ===
Line 651: Line 586:


equip_point is one of the equip_* constants
equip_point is one of the equip_* constants
=== getequipisequiped ===
<pre>
    getequipisequiped(num)
</pre>
Return 1 if the player currently has an item equipped in the slot.
=== statusup ===
<pre>
    statusup bType;
</pre>
Permanently increase a stat by one point.


=== statusup2 ===
=== statusup2 ===
Line 716: Line 639:
</pre>
</pre>
Set the player's opt2 flags.
Set the player's opt2 flags.
=== checkoption ===
<pre>
    checkoption(type)
</pre>
Return 1 if the player has any of the given (XOR'ed) option bits. Usually only one is given.
=== setoption ===
<pre>
    setoption type
</pre>
Set the player's option flags exactly (not OR'ing).


=== savepoint ===
=== savepoint ===
Line 747: Line 658:
</pre>
</pre>
Return the name of the item, or "Unknown Item".
Return the name of the item, or "Unknown Item".
=== clearitem ===
<pre>
    clearitem;
</pre>
Remove all items from a player's inventory.


=== nude ===
=== nude ===
Line 759: Line 664:
</pre>
</pre>
Unequip all items.
Unequip all items.
=== hasitems ===
<pre>
    hasitems()
</pre>
Return 1 if the player has any inventory, 0 otherwise.


=== unequipbyid ===
=== unequipbyid ===
Line 815: Line 714:
6: month (1-12)
6: month (1-12)
7: year (1902-2038)
7: year (1902-2038)
=== gettimestr ===
<pre>
    gettimestr("format", length)
</pre>
Frontend for strftime(3).
This function may be removed for technical reasons, please construct the string manually using gettime().
There is a script function that does this: callfunct "time_stamp";


== Timers and Events ==
== Timers and Events ==
Line 830: Line 719:


The most common ones are initnpctimer or startnpctimer, stopnpctimer, and setnpctimer.
The most common ones are initnpctimer or startnpctimer, stopnpctimer, and setnpctimer.
=== doevent ===
<pre>
    doevent "event";
</pre>
Manually invoke an NPC event.


=== donpcevent ===
=== donpcevent ===
<pre>
<pre>
     donpcevent "event";
     donpcevent "NpcName::Event";
</pre>
</pre>
Manually invoke an NPC event.
Manually invoke an NPC event.
Line 850: Line 733:


This command does the same thing as areatimer, but for only the attached player.
This command does the same thing as areatimer, but for only the attached player.
=== deltimer ===
<pre>
    deltimer "event";
</pre>
This command is untested and might freeze the server.


=== initnpctimer ===
=== initnpctimer ===
Line 894: Line 771:
type==1: bool if it has a next timer.
type==1: bool if it has a next timer.
type==2: timer amount
type==2: timer amount
=== cmdothernpc ===
<pre>
    cmdothernpc "npc", "Foo";
</pre>
Invoke ::OnCommandFoo


=== mobcount ===
=== mobcount ===
Line 905: Line 776:
     mobcount("mapname", "event")
     mobcount("mapname", "event")
</pre>
</pre>
Count the remaining mobs from the spawn with the given event.
Count the remaining mobs from the spawn with the given event. Has an offset of -1.


=== areatimer ===
=== areatimer ===
Line 917: Line 788:
== Unsorted Commands ==
== Unsorted Commands ==
These are commands that still need sorting, please edit this page, see talk page for category (and subcategory?) suggestions.
These are commands that still need sorting, please edit this page, see talk page for category (and subcategory?) suggestions.
=== strnpcinfo ===
<pre>
    strnpcinfo(number[, "npc"])
</pre>
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 ===
<pre>
    getnpcx(["npc"])
</pre>
Returns the X location of the current or specified npc.
=== getnpcy ===
<pre>
    getnpcy(["npc"])
</pre>
Returns the Y location of the current or specified npc.


=== monster ===
=== monster ===
Line 928: Line 817:
     areamonster "mapname", x0, y0, x1, y1, "string", class, count[, "event"];
     areamonster "mapname", x0, y0, x1, y1, "string", class, count[, "event"];
</pre>
</pre>
Spawn monsters in an area.
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 ===
=== killmonster ===
Line 939: Line 828:


If "All" is given, this function properly preserves permanently respawning monsters.
If "All" is given, this function properly preserves permanently respawning monsters.
=== killmonsterall ===
<pre>
    killmonsterall "mapname";
</pre>
Kill all monsters unconditionally.
This command might prevent monsters from respawning. Instead use "killmonster" with "event" == "All".


=== enablenpc ===
=== enablenpc ===
Line 960: Line 841:
Disable an NPC.
Disable an NPC.


=== hideoffnpc ===
=== setmapflag ===
<pre>
<pre>
     hideoffnpc "name";
     setmapflag "mapname", flag;
</pre>
</pre>
What does this do?
Set an arbitrary mapflag.


=== hideonnpc ===
=== removemapflag ===
<pre>
<pre>
     hideonnpc "name";
     removemapflag "mapname", flag;
</pre>
</pre>
What does this do?
Unset an arbitrary mapflag.


=== setmapflagnosave ===
=== getmapflag ===
<pre>
<pre>
     setmapflagnosave "mapname", "savemap", x, y;
     getmapflag("mapname", flag);
</pre>
</pre>
Set the nosave flag and respawn location.
Check an arbitrary mapflag.


=== setmapflag ===
=== pvp ===
<pre>
<pre>
     setmapflag "mapname", flag;
     pvp number;
</pre>
</pre>
Set an arbitrary mapflag.
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;


This function may be problematic in the stable version.
=== getpvpflag ===
 
=== removemapflag ===
<pre>
<pre>
     removemapflag "mapname", flag;
     getpvpflag(number)
</pre>
</pre>
Unset an arbitrary mapflag.
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.


This function may be problematic in the stable version.


=== pvpon ===
=== pvpon ===
Line 1,018: Line 896:
Return the #invocation used for a spell, or "...".
Return the #invocation used for a spell, or "...".


=== getanchorinvocation ===
=== specialeffect ===
<pre>
    specialeffect type;
</pre>
Display a special effect on the OID.
 
Same as "misceffect", but does not fallback when there is no OID.
 
=== specialeffect2 ===
<pre>
<pre>
     getanchorinvocation "anchor-identifier"
     specialeffect2 type;
</pre>
</pre>
Return the invocation used for a teleport anchor (?)
Same as "misceffect", but works when there is an OID.


=== strmobinfo ===
=== mapexit ===
<pre>
<pre>
     strmobinfo(num, class)
     mapexit;
</pre>
</pre>
Info about a type of mob:
Exits the map server.
num==1: name
num==2: jname
num==3: lv
num==4: maxhp
num==5: maxsp
num==6: base_exp
num==7: job_exp


Note that only types 1 and 2 actually return strings, the rest return integers
=== bonus2 ===
<pre>
    bonus2 player, type, Amount, Tick;
</pre>
Currently the only type is bHPDrainRate. This takes Amount per Tick in HPs from player.


=== specialeffect ===
=== getitemlink ===
<pre>
    getitemlink("ItemName");
</pre>
Returns the Manaplus link for use in scripts [@@ID|JName@@]
 
=== npcareawarp ===
<pre>
    npcareawarp x0, y0, x1, y1, CollisionBool, "NPC Name";
</pre>
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 ===
<pre>
<pre>
     specialeffect type;
     iscollision map.gat, x, y, type;
</pre>
</pre>
Display a special effect on the OID.
Checks if collision is of a type. (Types will be cast as CONST in the const.txt file)
 
== Deprecated ==


Same as "misceffect", but does not fallback when there is no OID.
=== itemheal ===
This command has been merged into [[Dev:TmwAthena_Scripting_Reference#heal|heal]]. The equivalent is :
<pre>
    heal Hp, Sp, true;
</pre>


=== specialeffect2 ===
=== percentheal ===
This command has been completely removed. Please use inline math instead. For example to remove 30% hp you would do:
<pre>
<pre>
     specialeffect2 type;
     heal ((MaxHp/10) * -3), 0;
</pre>
</pre>
Same as "misceffect", but works when there is an OID.


=== gmcommand ===
=== killmonsterall ===
This command has been deprecated and [[Dev:TmwAthena_Scripting_Reference#killmonster|killmonster]] should be used instead:
<pre>
<pre>
     gmcommand "@command maybe with arguments";
     killmonster "mapname", "All";
</pre>
</pre>
Run a GM command, at level 99.
 
=== 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"