Development:TmwAthena Scripting Reference/unstable/magic-v3

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

TMW's scripting wiki pages:

Scripting Basics - Scripting Standards - Scripting Reference

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

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

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;

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

    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

    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

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

getarraysize

    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

    arrayname[index_expr]

returns index_expr of that array.

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.

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

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.

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

    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;

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

    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.

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[, boolean];

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

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.

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_end

    sc_end type;

Immediately end status effect on current player.

sc_check

    sc_check(type)

Whether a status effect is currently active.

resetstatus

    resetstatus;

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

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.

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. The area is of square shape which has the diagonals x0,y0 and x1,y1.

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, z)

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

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.

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

    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.

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

    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

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.

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

nude

    nude;

Unequip all items.

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)

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.

donpcevent

    donpcevent "NpcName::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.

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

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.

magic-v3

commands introduced in magic-v3. please move those to unsorted or into the appropriate categories when magic-v3 is stable.

registercmd

    registercmd "command", "npc[::event]";

Fires the event when the specified command is typed into chat. If you only put the npc name (no event) it does the same as clicking the npc so you can use menus and other things that require user input.

target

    target(source id, target id, flag)

Allows to check multiple things about the target at once. The source and target can by anything (player, npc, mob). The return value is a bitmasking of the tests that succeeded. The flag is a bitmasking of those bits:

• 0x01 the target is in the visible range of the source (which is source position plus and minus AREA_SIZE). This means that the source can see the target on their computer screen (providing the screen is big enough)
• 0x02 the target is in the attack range of the source (based on the calculated attack range, not the base attack range)
• 0x04 the target is walkable, the source has a clear path to target
• 0x08 not yet implemented
• 0x10 the source can attack the target. note: 0x10 in hexadecimal is 16 in decimal, not 10
• 0x20 the target is in the line of sight of the source. note: 0x20 in hexadecimal is 32 in decimal, not 20

get

    get(variable or param, being id or name)

Allows to get a variable or param from another player, a mob or a npc. Useful to do things like get(Hp, @mobID)

min

    min(number, number)

returns the smallest number of the two

max

    max(number, number)

returns the biggest number of the two

pow

    pow(number, exponent)

returns the number at the power of exponent.

sqrt

    sqrt(number)

returns the square root of number.

cbrt

    cbrt(number)

returns the cubic root of number.

elttype

    elttype(being id)

returns the element type of the being

eltlvl

    eltlvl(being id)

returns the element level of the being

Unsorted Commands

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

strnpcinfo

    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

    getnpcx(["npc"])

Returns the X location of the current or specified npc.

getnpcy

    getnpcy(["npc"])

Returns the Y location of the current or specified npc.

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.

enablenpc

    enablenpc "name";

Enable an NPC.

disablenpc

    disablenpc "name";

Disable an NPC.

setmapflag

    setmapflag "mapname", flag;

Set an arbitrary mapflag.

removemapflag

    removemapflag "mapname", flag;

Unset an arbitrary mapflag.

getmapflag

    getmapflag("mapname", flag);

Check an arbitrary mapflag.

pvp

    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

    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

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

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

mapexit

    mapexit;

Exits the map server.

bonus2

    bonus2 player, type, Amount, Tick;

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

getitemlink

    getitemlink("ItemName");

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

npcareawarp

    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

    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

itemheal

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

    heal Hp, Sp, true;

percentheal

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

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

    killmonster "mapname", "All";

cmdothernpc

This command has been deprecated in favor of donpcevent.