Scripting
From TheManaWorld
This article is for reference purpose
The features described in this article are already implemented in the game. The article should describe how a certain aspect of the game currently works. You may of course edit this article to improve the description of the circumstances. Your opinions or improvement suggestions about the described aspects themself are of course appreciated, too. But please put these on the discussion page of this article to keep facts and fiction separated.
TMWServ uses the scripting language LUA for scripting. This is a list of the script commands currently implemented in addition to the standard lua statements and functions.
TODO: Look up arguments of each function and write a descriptions for all functions.
Contents |
Creation of stuff
create_npc
Usage: create_npc(string name, int spriteID, int x, int y, function talkfunct, function updatefunct)
Return value: A handle to the created NPC.
Creates a new NPC with the name name at the coordinates x:y which appears to the players with the appearence listed in their npcs.xml under spriteID. Every game tick the function updatefunct is called with the handle of the npc. When a character talks to the NPC the function talkfunct is called with the npc handle and the character handle.
tmw.monster_create
Usage: tmw.monster_create(int monsterID, int x, int y)
Return value: A handle to the created monster.
Spawns a new monster of type monsterID on the current map on the pixel coordinates x:y.
tmw.trigger_create
Usage: tmw.trigger_create (int x, int y, int width, int height, string functionname, int arg, bool once)
Creates a new trigger area with the given height and width in pixels at the map position x:y in pixels. When a being steps into this area the function with the name functionname is called with the being handle and arg as arguments. When once is false the function is called every game tick the being is inside the area. When once is true it is only called again when the being leaves and reenters the area.
tmw.effect_create
Usage: tmw.effect_create (int id, int x, int y)
Triggers the effect id from the clients effects.xml (particle and/or sound) at map location x:y. This has no effect on gameplay. Remember that clients might switch off particle effects for performance reasons. Thus you should not use this for important visual input.
Input and output
do_message
Usage: do_message(handle npc, handle character, string message)
Warning: May only be called from an NPC talk function.
Shows an NPC dialog box on the screen of character ch displaying the string msg. Idles the current thread until the user clicked "OK".
do_choice
Usage: do_choice(handle npc, handle character, string option1, ... string optionN)
Return value: Number of the option the player selected (starting with 1).
Warning: May only be called from an NPC talk function.
Shows an NPC dialog box on the users screen with a number of dialog options to choose from. Idles the current thread until the user selects one or aborts the current thread when the user clicks "cancle".
tmw.being_say
Usage: tmw.being_say(handle being, string message)
Makes being, which can be a character, monster or NPC, speak the string message as if it was entered by a player in the chat bar.
tmw.chatmessage
Usage: tmw.chatmessage(handle character, string message)
Outputs the string message in the chatlog of character which will appear as a private message from "Server".
Inventory interaction
tmw.npc_trade
Usage: tmw.npc_trade(handle npc, handle character, bool mode, {int item1id, int item1cost, int item1amount}, ..., {int itemNid, int itemNcost, int itemNamount})
Opens a trade window for character while talking with npc. mode is true for selling and false for buying. You have to set each items the NPC is buying/selling, the cost and the maximum amount in {}.
tmw.chr_invcount
Usage: tmw.chr_invcount(handle character, int id1, ..., int idN)
Return values: A number of integers with the amount of items id carried by character.
tmw.chr_invchange
Usage: tmw.chr_invchange(handle character, int id1, int number1, ..., int idN, numberN)
Return value: boolean true on success, boelean false no failure
Changes the number of items with the item id id owned by character by number. You can change any number of items with this function by passing multiple id and ammount pairs. A failure can be caused by trying to take items the character doesn't possess.
Warning: When one of the operations fails the following operations are ignored but these before are executed. For that reason you should always check if the character possesses items you are taking away using tmw.chr_invcount.
tmw.chr_money
Usage: tmw.chr_money(handle character)
Return value: The money currently owned by character
tmw.chr_money_change
Usage: tmw.chr_money_change(handle character, int amount)
Changes the money currently owned by character by amount.
Warning: Before reducing the money make sure to check if the character owns enough money using tmw.chr_money.
Character and Being interaction
- get_quest_var(ch, name)
- tmw.chr_set_quest(ch, name, value)
- tmw.being_walk
- tmw.being_damage
- tmw.get_beings_in_circle
tmw.being_get_attribute
Usage: tmw.being_get_attribute(handle being, int attribute)
Returns the amount of the attribute the being has.
tmw.being_get_name
Usage: tmw.being_get_name(handle being)
Returns the name of the being.
tmw.chr_warp
Usage: tmw.chr_warp(handle character, int mapID, int posX, int posY)
Teleports the character to the position posX:posY on the map with the ID number mapID. The mapID can be substituted by nil to warp the character to a new position on the current map.
tmw.posx
Usage: tmw.posx(handle being)
Return value: The horizontal position of the being in pixels measured from the left border of the map it is currently on.
tmw.posy
Usage: tmw.posy(handle being)
Return value: The vertical position of the being in pixels measured from the upper border of the map it is currently on.
tmw.being_get_attribute
Usage: tmw.being_get_attribute(handle being, int attribute)
Return value: Returns the score in attribute of being. Can also be used to query the skill levels of player characters.
tmw.chr_get_exp
Usage: tmw.chr_get_exp(handle character, int attribute)
Return value: The total exp collected by character in skill attribute.
tmw.chr_give_exp
Usage: tmw.chr_give_exp(handle character, int attribute, int amount)
Gives character amount experience in skill attribute.
tmw.exp_for_level
Usage: tmw.exp_for_level(int level)
Return value: Returns the total exp necessary (counted from level 0) for reaching level in any skill.
Scheduling
atinit
Usage: atinit(function() [function body] end)
Adds a function which is executed when the gameserver loads the map this script belongs to. Usually used for placing NPCs or trigger areas and for setting up cronjobs with schedule_every. Any number of functions can be added this way.
schedule_in
Usage: schedule_in(seconds, function() [function body] end)
Executes the function body in seconds seconds.
schedule_every
Usage: schedule_every(seconds, function() [function body] end)
Executes the function body every seconds seconds from now on.
on_death
Usage: on_death(handle being, function() [function body] end)
Executes the function body when being is killed.
