Classic:TmwAthena Scripting Reference

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

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

Language Commands

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

goto

    goto L_1;

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

callsub

    callsub S_labelname, arguments...;

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.

callfunc

    callfunc "function_name", arguments...;

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.

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

return

    return;
    return expr;

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.

We use temporary variables instead of the form that returns an expression.

getarg

    getarg(index)

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 variable, expression;

Very common command, to set variables.

setarray

    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

    cleararray variable, value, count;

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

copyarray

    copyarray dest_var, src_var, count;

Copy elements of an array.

This function looks broken to me.

getarraysize

    getarraysize variable;

Get the size of an array.

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.

deletearray

    deletearray variable[, count = 1];

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(arrayname, index_expr)

This function is invoked internally by the arrayname[index_expr] syntax.

if

    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.

end

    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

    debugmes "string"

Print a message to stdout.

Message Commands

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

mes

    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 1:

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:

"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."

Example 2: Hamlet (Act 3, scene 1)

mes "[King Claudius]"
mes "\"Aside O, 'tis too true!"
mes "How smart a lash that speech doth give my conscience!"
mes "The harlot's cheek, beautied with plastering art,"
mes "Is not more ugly to the thing that helps it"
mes "Than is my deed to my most painted word:"
mes "O heavy burthen!\""
mes ""
mes "[Lord Polonius]"
mes "\"I hear him coming: let's withdraw, my lord.\""
mes ""
mes "Exeunt KING CLAUDIUS and POLONIUS Enter HAMLET"
mes ""
mes "[Hamlet]"
mes "\"To be, or not to be: that is the question:"
mes "Whether 'tis nobler in the mind to suffer"
mes "The slings and arrows of outrageous fortune,"
mes "Or to take arms against a sea of troubles,"
mes "And by opposing end them? To die: to sleep;"
mes "No more; and by a sleep to say we end"
mes "The heart-ache and the thousand natural shocks"
mes "That flesh is heir to, 'tis a consummation"
mes "Devoutly to be wish'd. To die, to sleep;"
mes "To sleep: perchance to dream: ay, there's the rub;"
mes "For in that sleep of death what dreams may come"
mes "When we have shuffled off this mortal coil,"
mes "Must give us pause: there's the respect"
mes "That makes calamity of so long life;"
mes "For who would bear the whips and scorns of time,"
mes "The oppressor's wrong, the proud man's contumely,"
mes "The pangs of despised love, the law's delay,"
mes "The insolence of office and the spurns"
mes "That patient merit of the unworthy takes,"
mes "When he himself might his quietus make"
mes "With a bare bodkin? who would these fardels bear,"
mes "To grunt and sweat under a weary life,"
mes "But that the dread of something after death,"
mes "The undiscover'd country from whose bourn"
mes "No traveller returns, puzzles the will"
mes "And makes us rather bear those ills we have"
mes "Than fly to others that we know not of?"
mes "Thus conscience does make cowards of us all;"
mes "And thus the native hue of resolution"
mes "Is sicklied o'er with the pale cast of thought,"
mes "And enterprises of great pitch and moment"
mes "With this regard their currents turn awry,"
mes "And lose the name of action.--Soft you now!"
mes "The fair Ophelia! Nymph, in thy orisons"
mes "Be all my sins remember'd.\""
mes ""
mes "[Ophelia]"
mes "\"Good my lord,"
mes "How does your honour for this many a day?\""
mes ""
mes "[Hamlet]"
mes "\"I humbly thank you; well, well, well.\""

Will give:

[King Claudius]
"Aside O, 'tis too true!"
How smart a lash that speech doth give my conscience!
The harlot's cheek, beautied with plastering art,
Is not more ugly to the thing that helps it
Than is my deed to my most painted word:
O heavy burthen!"

[Lord Polonius]
"I hear him coming: let's withdraw, my lord."

Exeunt KING CLAUDIUS and POLONIUS Enter HAMLET

[Hamlet]
"To be, or not to be: that is the question:
Whether 'tis nobler in the mind to suffer
The slings and arrows of outrageous fortune,
Or to take arms against a sea of troubles,
And by opposing end them? To die: to sleep;
No more; and by a sleep to say we end
The heart-ache and the thousand natural shocks
That flesh is heir to, 'tis a consummation
Devoutly to be wish'd. To die, to sleep;
To sleep: perchance to dream: ay, there's the rub;
For in that sleep of death what dreams may come
When we have shuffled off this mortal coil,
Must give us pause: there's the respect
That makes calamity of so long life;
For who would bear the whips and scorns of time,
The oppressor's wrong, the proud man's contumely,
The pangs of despised love, the law's delay,
The insolence of office and the spurns
That patient merit of the unworthy takes,
When he himself might his quietus make
With a bare bodkin? who would these fardels bear,
To grunt and sweat under a weary life,
But that the dread of something after death,
The undiscover'd country from whose bourn
No traveller returns, puzzles the will
And makes us rather bear those ills we have
Than fly to others that we know not of?
Thus conscience does make cowards of us all;
And thus the native hue of resolution
Is sicklied o'er with the pale cast of thought,
And enterprises of great pitch and moment
With this regard their currents turn awry,
And lose the name of action.--Soft you now!
The fair Ophelia! Nymph, in thy orisons
Be all my sins remember'd."

[Ophelia]
"Good my lord,
How does your honour for this many a day?"

[Hamlet]
"I humbly thank you; well, well, well."

next

    next;

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

close

    close;

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

close2

    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

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

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.

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

    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

    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

    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.

areaannounce

    areaannounce "mapname", x0, y0, x1, y1, "message", flag;

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.

message

    message "player", "message";

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

npctalk

    npctalk "message";

Make an NPC say something publicly.

Note: in many cases areaannounce is a better choice.

Character Commands

These have to do with attributes of the player.

setlook

    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

    heal hp, sp

Increase or decrease the player's hp and sp.

itemheal

    itemheal "ii"

Increase or decrease the player's hp and sp, for use in item scripts.

percentheal

    percentheal "ii"

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(type[, "playername"])

Return one of the core parameters of a player.

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

getcharid

    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.

getpartyname

    getpartyname(partyid)

Return the name of the party with the given id, or "null".

getpartymember

    getpartymember partyid

Fills in the array $@partymembername$

strcharinfo

    strcharinfo(num)

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

sc_start

    sc_start type, tick, val1[, beingid];

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

type is one of the sc_* constants.

sc_start2

    sc_start2 type, tick, val1, chance[, beingid];

Chance of applying a status effect, out of 10000.

sc_end

    sc_end type;

Immediately end status effect on current player.

sc_check

    sc_check(type)

Whether a status effect is currently active.

getscrate

    getscrate(type, rate[, being_id])

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

    resetlvl type;

resetstatus

    resetstatus;

resetskill

    resetskill;

changesex

    changesex;

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

attachrid

    attachrid(id)

Change the being associated with this script.

Return true if such a player is logged in.

detachrid

    detachrid;

Detach the player associated with this script.

isloggedin

    isloggedin(id)

Return true if the given ID is logged in.

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

marriage

    marriage("otherplayer")

Marry the attached player to the other player.

Return 1 on success and 0 on failure.

divorce

    divorce()

Divorce the attached player from their partner

Return 1 on success and 0 on failure.

getpartnerid2

    getpartnerid2()

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

getexp

    getexp base, job;

Increase the types of experience.

getinventorylist

    getinventorylist;

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

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

getskilllist

    getskilllist;

Fill in some arrays of useful information: "@skilllist_id", "@skilllist_lv", "@skilllist_flag".

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

getpoolskilllist

    getpoolskilllist;

Same, but only poolable skills.

getactivatedpoolskilllist

    getactivatedpoolskilllist;

Same, but only activated pool skills.

getunactivatedpoolskilllist

    getunactivatedpoolskilllist;

Same, but only unactivated pool skills.

poolskill

    poolskill skill_id;

Activate a poolable skill.

unpoolskill

    unpoolskill skill_id;

Deactivate a poolable skill.

checkpoolskill

    checkpoolskill(skill_id)

Check if a pool skill is activated

misceffect

    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

    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

    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

    shop "npcname";

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

isdead

    isdead()

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

fakenpcname

    fakenpcname "name", "newname", new_sprite_id;

Change the appearance of an NPC.

Location Commands

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

warp

    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

    isat("mapname", x, y)

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

areawarp

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

Warp all players in the given area to the given location.

getusers

    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

    getmapusers("mapname")

Count users on a given map.

getareausers

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

Count users in an area.

mapwarp

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

Warp all players from source map to destination location.

npcwarp

    npcwarp x, y, "npcname";

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

isin

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

Check if the player is in the area.

getx

    getx()

Return attached player's x coordinate.

gety

    gety()

Return attached player's y coordinate.

getmap

    getmap()

Return attached player's current map.

Item Commands

These have to do with items or inventory.

getitem

    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.

makeitem

    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

    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.

countitem

    countitem("itemname")
    countitem(itemid)

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

checkweight

    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

    getequipid(equip_point)

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

equip_point is one of the equip_* constants

getequipname

    getequipname(equip_point)

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

equip_point is one of the equip_* constants

getequipisequiped

    getequipisequiped(num)

Return 1 if the player currently has an item equipped in the slot.

statusup

    statusup bType;

Permanently increase a stat by one point.

statusup2

    statusup2 bType, delta;

Permanently increase or decrease a stat.

bonus

    bonus bType, delta

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

skill

    skill id, level[, flag = 1];

Grant a skill.

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

(Untested)

setskill

    setskill id, level;

Grant a skill permanently.

getskilllv

    getskilllv(skill)

Return the player's level of the given skill.

getgmlevel

    getgmlevel()

Return the player's GM level.

getopt2

    getopt2()

Return the player's opt2 flags.

setopt2

    setopt2 flags;

Set the player's opt2 flags.

checkoption

    checkoption(type)

Return 1 if the player has any of the given (XOR'ed) option bits. Usually only one is given.

setoption

    setoption type

Set the player's option flags exactly (not OR'ing).

savepoint

    savepoint "mapname", x, y;

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

openstorage

    openstorage;

Open the player's storage.

getitemname

    getitemname("itemname")
    getitemname(itemid)

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

clearitem

    clearitem;

Remove all items from a player's inventory.

nude

    nude;

Unequip all items.

hasitems

    hasitems()

Return 1 if the player has any inventory, 0 otherwise.

unequipbyid

    unequipbyid slot_id;

Unequip whatever is in the slot

getareadropitem

    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

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

rand

    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

    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

    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)

gettimestr

    gettimestr("format", length)

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

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.

doevent

    doevent "event";

Manually invoke an NPC event.

donpcevent

    donpcevent "event";

Manually invoke an NPC event.

addtimer

    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.

deltimer

    deltimer "event";

This command is untested and might freeze the server.

initnpctimer

    initnpctimer;

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

This is equivalent to setnpctimer, 0; startnpctimer;

stopnpctimer

    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

    startnpctimer;

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

setnpctimer

    setnpctimer tick;

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

getnpctimer

    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

cmdothernpc

    cmdothernpc "npc", "Foo";

Invoke ::OnCommandFoo

mobcount

    mobcount("mapname", "event")

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

areatimer

    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

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

monster

    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

    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

    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.

killmonsterall

    killmonsterall "mapname";

Kill all monsters unconditionally.

This command might prevent monsters from respawning. Instead use "killmonster" with "event" == "All".

enablenpc

    enablenpc "name";

Enable an NPC.

disablenpc

    disablenpc "name";

Disable an NPC.

hideoffnpc

    hideoffnpc "name";

What does this do?

hideonnpc

    hideonnpc "name";

What does this do?

setmapflagnosave

    setmapflagnosave "mapname", "savemap", x, y;

Set the nosave flag and respawn location.

setmapflag

    setmapflag "mapname", flag;

Set an arbitrary mapflag.

removemapflag

    removemapflag "mapname", flag;

Unset an arbitrary mapflag.

getmapflag

    getmapflag("mapname", flag);

Check an arbitrary mapflag.

pvpon

    pvpon "mapname";

Allow PvP on a map.

pvpoff

    pvpoff "mapname";

Deny PvP on a map.

emotion

    emotion emote_index;

Show a smiley above the OID.

getspellinvocation

    getspellinvocation("spell-identifier")

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

getanchorinvocation

    getanchorinvocation "anchor-identifier"

Return the invocation used for a teleport anchor (?)

strmobinfo

    strmobinfo(num, class)

Info about a type of mob: 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

specialeffect

    specialeffect type;

Display a special effect on the OID.

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

specialeffect2

    specialeffect2 type;

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

gmcommand

    gmcommand "@command maybe with arguments";

Run a GM command, at level 99.