Scripting Reference
The Mana server 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.
Also, if you want to look at actual working samples, you can have a look at the
example/scripts
folder in the
Mana server source
which has always the latest working set.
Available script bindings
Ability info class
See the abilities Documentation for a script example
abilityinfo:name
abilityinfo:name()
Return value: The name of the abilityinfo object.
Note: See get_ability_info for getting a abilityinfo object.
abilityinfo:on_recharged
abilityinfo:on_recharged(function callback)
Assigns the callback
as callback for the recharged event. This function
will be called everytime when the ability is fully recharged.
Note: See get_ability_info for getting a abilityinfo object.
abilityinfo:on_use
abilityinfo:on_use(function callback)
Assigns the callback
as callback for the use event. This function will
be called everytime a character uses a ability.
Note: See get_ability_info for getting a abilityinfo object.
get_ability_info
get_ability_info(int abilityId)
get_ability_info(string abilityName)
Return value: This function returns a object of the abilityinfo class. See below for usage of that object.
Note: When passing the abilityName
as parameter make sure that it is
formatted in this way: <setname>/<abilityname> (for eg. "Magic_Healingspell").
Area of Effect
In order to easily use area of effects in your items or in your scripts, the following functions are available:
get_beings_in_circle
get_beings_in_circle(int x, int y, int radius)
get_beings_in_circle(handle actor, int radius)
Return value: This function returns a lua table of all beings in a
circle of radius (in pixels) radius
centered either at the pixel at
(x
, y
) or at the position of being
.
get_beings_in_rectangle
get_beings_in_rectangle(int x, int y, int width, int height)
Return value: An table of being entities within the rectangle. All parameters have to be passed as pixels.
get_distance
get_distance(handle being1, handle being2)
get_distance(int x1, int y1, int x2, int y2)
Return value: The distance between the two beings or the two points in pixels.
AttributeInfo class
attributeinfo:name
local name = attributeinfo:name()
Return value: The name of the attributeinfo
.
get_attribute_info
local attributeinfo = get_attribute_info(string name)
local attributeinfo = get_attribute_info(int id)
Return value: The attribute info of the passed attribute.
Callbacks
Note: You can only assign a single function as callback. When setting a new function the old one will not be called anymore. Some of this callbacks are already used for the libmana.lua. Be careful when using those since they will most likely break your code in other places.
on_being_death
on_being_death(function ref)
Will make sure that the function ref
gets called with the being
as argument as soon a being dies.
on_character_death
on_character_death(function ref)
Sets a listener function to the character death event.
on_character_death_accept
on_character_death_accept(function ref)
Will make sure that the function ref
gets called with the character
as argument as soon a character either pressed the ok dialouge in the death
message or left the game while being dead.
on_character_login
on_character_login(function ref)
Will make sure that function ref
gets called with the character
as argument as soon a character logged in.
on_craft
on_craft(function ref)
Will make sure that the function ref
gets called with the crafting
character and a table with the recipes {(id, amount}) when a character
performs crafting.
on_create_npc_delayed
on_create_npc_delayed(function ref)
Will make sure that the function ref
gets called with the
name, id, gender, x and y values as arguments of the npc when a npc should
be created at map init (Npcs defined directly in the map files use this).
on_entity_remove
on_entity_remove(function ref)
Will make sure that the function ref
gets called with the being
as argument as soon a being gets removed from a map.
on_map_initialize
on_map_initialize(function ref)
Will make sure that the function ref
gets called with the initialized
map as current map when the map is initialized.
on_mapupdate
on_mapupdate(function ref)
Will make sure that the function ref
gets called with the map id
as argument for each game tick and map.
on_recalculate_base_attribute
on_recalculate_base_attribute(function ref)
Will call the function ref
when an attribute base needs to be recalculated.
The function is expected to do this recalculation then. The engine only
triggers this for characters. However you can use the same function for
recalculating derived attributes in the
on_update_derived_attribute callback.
See: attributes.xml for more info.
on_update
on_update(function ref)
Will make sure that the function ref
gets called every game tick.
on_update_derived_attribute
on_update_derived_attribute(function ref)
Will call the function ref
when an attribute changed and other attributes
need recalculation. The function is expected to recalculate those then.
See: attributes.xml for more info.
Character and being interaction
chr_get_post
chr_get_post(handle character)
Gets the post for the character.
chr_get_quest
chr_get_quest(handle character, string name)
Return value: The quest variable named name
for the given character.
Warning: May only be called from an NPC talk function.
chr_request_quest
chr_request_quest(handle character, string questvariable, Ref function)
Requests the questvar from the account server. This will make it available in the quest cache after some time. The passed function will be called back as soon the quest var is available.
chr_set_quest
chr_set_quest(handle character, string name, string value)
Sets the quest variable named name
for the given character to the value
value
.
chr_try_get_quest
chr_try_get_quest(handle character, string questvariable)
Callback for checking if a quest variable is available in cache.
Return value: It will return the variable if it is or nil if it is not in cache.
entity:ability_mana
entity:ability_mana(int abilityid)
entity:ability_mana(string abilityname)
Return value: The remaining time of the ability cooldown.
Note: When passing the abilityname
as parameter make sure that it is
formatted in this way: <setname>/<abilityname> (for eg. "Magic_Healingspell").
entity:action
entity:action()
Valid only for being entities.
Return value: Current action of the being. These action constants are defined in libmana-constants.lua:
| 0 | ACTION_STAND | | 1 | ACTION_WALK | | 2 | ACTION_SIT | | 3 | ACTION_DEAD | | 4 | ACTION_HURT |
entity:add_hit_taken
add_hit_taken(int damage)
Adds a damage value to the taken hits of a being. This list will be send to all clients in the view range in order to allow to display the hit particles.
entity:apply_attribute_modifier
entity:apply_attribute_modifier(int attribute_id, double value,
unsigned int layer, [unsigned short duration,
[unsigned int effect_id]])
Valid only for being entities.
Parameters description: \ * value (double): The modifier value (can be negative). * layer (unsigned int): The layer or level of the modifier. As modifiers are stacked on an attribute, the layer determines where the modifier will be inserted. Also, when adding a modifier, all the modifiers with an higher ayer value will also be recalculated. * duration (unsigned short): The modifier duration in ticks((A tick is equal to 100ms.)). If set to 0, the modifier is permanent. * effect_id (unsigned int): Set and keep that parameter when you want to retrieve the exact layer later. (FIXME: Check this.)
entity:attribute_points
entity:attribute_points()
Valid only for character entities.
Returns: Returns the amount of available attribute points.
entity:base_attribute
entity:base_attribute(int attribute_id)
Valid only for being entities.
Return value: Returns the value of the being's base attribute
.
entity:correction_points
entity:correction_points()
Valid only for character entities.
Returns: Returns the amount of available correction points.
entity:destination
local x, y = entity:destination()
Valid only for being entities.
Return value: The x and y coordinates of the destination.
entity:direction
entity:direction()
Valid only for being entities.
Return value: Current direction of the being. These direction constants are defined in libmana-constants.lua:
| 0 | DIRECTION_DEFAULT | | 1 | DIRECTION_UP | | 2 | DIRECTION_DOWN | | 3 | DIRECTION_LEFT | | 4 | DIRECTION_RIGHT | | 5 | DIRECTION_INVALID |
entity:entity_look_at
local x, y = entity:entity_look_at(entity other)
local x, y = entity:entity_look_at(int x, int y)
Valid only for being entities.
Makes the being looking at another being or a point.
entity:gender
entity:gender()
Valid only for being entities.
Return value: The gender of the being. These gender constants are defined in libmana-constants.lua:
| 0 | GENDER_MALE | | 1 | GENDER_FEMALE | | 2 | GENDER_UNSPECIFIED |
entity:give_ability
entity:give_ability(int ability)
Valid only for character and monster entities.
Enables an ability for a character.
entity:global_ability_cooldown
entity:global_ability_cooldown()
Valid only for character entities.
Gets the amount of ticks before any other ability can be used again
entity:hair_color
entity:hair_color()
Valid only for character entities.
Return value: The hair color ID of the character.
entity:hair_style
entity:hair_style()
Valid only for character entities.
Return value: The hair style ID of the character.
entity:has_ability
entity:has_ability(int ability)
Valid only for character and monster entities.
Return value: True if the character has the ability, false otherwise.
entity:heal
entity:heal([int value])
Valid only for being entities.
Restores value
lost hit points to the being. Value can be omitted to
restore the being to full hit points.
While you can (ab)use this function to hurt a being by using a negative value you should rather use entity:damage for this purpose.
entity:increment_kill_count
entity:increment_kill_count(int monsterId)
entity:increment_kill_count(string monsterName)
entity:increment_kill_count(MonsterClass monsterClass)
Valid only for character entities.
Increments the kill count by one.
entity:kick
entity:kick()
Valid only for character entities.
Kicks the character.
entity:kill_count
entity:kill_count(int monsterId)
entity:kill_count(string monsterName)
entity:kill_count(MonsterClass monsterClass)
Valid only for character entities.
Return value: The total number of monsters of the specy (passed either as monster id, monster name or monster class) the character has killed during its career.
entity:mapid
entity:mapid()
Return value: the id of the map where the entity is located or nil if there is none.
entity:name
entity:name()
Valid only for being entities.
Return value: Name of the being.
entity:position
entity:position()
Valid only for actor entities.
Return value: The x and y position of the actor in pixels, measured from the top-left corner of the map it is currently on.
entity:register
entity:register()
Makes the server call the on_being_death and on_entity_remove callbacks when the being dies or the entity is removed from the map.
Note: You should never need to call this in most situations. It is handeled by the libmana.lua
entity:remove_attribute_modifier
entity:remove_attribute_modifier(int attribute_id,
double value, unsigned int layer)
Valid only for being entities.
Permits to remove an attribute modifier by giving its value and its layer.
entity:rights
entity:rights()
Valid only for character entities.
Return value: The access level of the account of the character.
entity:set_ability_mana
entity:set_ability_cooldown(int abilityid, int ticks)
entity:set_ability_cooldown(string abilityname, int ticks)
Valid only for character entities.
Sets the amout of ticks that a ability needs to cooldown.
Note: When passing the abilitynam
as parameter make sure that it is
formatted in this way: <setname>/<abilityname> (for eg. "Magic_Healingspell").
entity:set_action
entity:set_action(int action)
Valid only for being entities.
Sets the current action for the being.
entity:set_attribute_points
entity:set_attribute_points(int amount)
Valid only for character entities.
Sets the amount of attribute points for the entity
entity:set_base_attribute
entity:set_base_attribute(int attribute_id, double new_value)
Valid only for being entities.
Set the value of the being's base attribute
to the 'new_value' parameter
given. (It can be negative).
entity:set_correction_points
entity:set_correction_points(int amount)
Valid only for character entities.
Sets the amount of correction points for the entity
entity:set_direction
entity:set_direction(int direction)
Valid only for being entities.
Sets the current direction of the given being. Directions are same as in
entity:direction
.
entity:set_gender
entity:set_gender(int gender)
Valid only for being entities.
Sets the gender of the being.
The gender constants are defined in libmana-constants.lua:
| 0 | GENDER_MALE | | 1 | GENDER_FEMALE | | 2 | GENDER_UNSPECIFIED |
entity:set_global_ability_cooldown
entity:set_global_ability_cooldown(int ticks)
Valid only for character entities.
Sets the amount of ticks before any other ability can be used again
entity:set_hair_color
entity:set_hair_color(int color)
Valid only for character entities.
Sets the hair color ID of the character to color
.
entity:set_hair_style
entity:set_hair_style(int style)
Valid only for character entities.
Sets the hair style ID of the character to style
.
entity:set_walkmask
entity:set_walkmask(string mask)
Valid only for actor entities.
Sets the walkmasks of an actor. The mask is a set of characters which stand for different collision types.
| w | Wall | | c | Character | | m | Monster |
This means entity:set_walkmask("wm") will prevent the being from walking over walls and monsters.
entity:shake_screen
entity:shake_screen(int x, int y[, float strength, int radius])
Valid only for character entities.
Shakes the screen for a given character.
entity:show_text_particle
entity:show_text_particle(string text)
Valid only for character entities.
Shows a text particle on a client. This effect is only visible for the character.
entity:take_ability
entity:take_ability(int ability)
Valid only for character and monster entities.
Removes a ability from a entity.
Return value: True if removal was successful, false otherwise (in case the character did not have the ability).
entity:type
entity:type()
Return value: Type of the given entity. These type constants are defined in libmana-constants.lua:
| 0 | TYPE_ITEM | | 1 | TYPE_ACTOR | | 2 | TYPE_NPC | | 3 | TYPE_MONSTER | | 4 | TYPE_CHARACTER | | 5 | TYPE_EFFECT | | 6 | TYPE_OTHER |
entity:use_ability
entity:use_ability(int ability)
entity:use_ability(string ability)
Valid only for character and monster entities.
Makes the entity using the given ability if it is available and recharged.
Return value: True if the ability was used successfully. False otherwise (if the ability is not available for the entity or was not recharged).
entity:walk
entity:walk(int pixelX, int pixelY [, int walkSpeed])
Valid only for being entities.
Set the desired destination in pixels for the being.
The optional 'WalkSpeed' is to be given in tiles per second. The average speed is 6.0 tiles per second. If no speed is given the default speed of the being is used.
entity:walkmask
entity:walkmask()
Valid only for actor entities.
Return value: The walkmask of the actor formatted as string. (See entity:set_walkmask)
entity:warp
entity:warp(int mapID, int posX, int posY)
entity:warp(string mapName, int posX, int posY)
Valid only for character entities.
Teleports the character to the position posX
:posY
on the map
with the ID number mapID
or name mapName
. The mapID
can be
substituted by nil
to warp the character to a new position on the
current map.
entity:x
entity:x()
Valid only for actor entities.
Return value: The x position of the actor in pixels, measured from the left border of the map it is currently on.
entity:y
entity:y()
Valid only for actor entities.
Return value: The y position of the actor in pixels, measured from the top border of the map it is currently on.
get_character_by_name
get_character_by_name(string name)
Tries to find an online character by name.
Return value the character handle or nil if there is none.
set_questlog
entity:set_questlog(int id, int state, string name,
string description[, bool notify = true])
Sets the questlog status.
Valid only for character entities.
For state you can use one of the following:
* QUEST_OPEN
* QUEST_FINISHED
* QUEST_FAILED
set_questlog_description
entity:set_questlog_description(int id, string description[, bool notify = true])
Sets the questlog description.
Valid only for character entities.
set_questlog_state
entity:set_questlog_state(int id, int state[, bool notify = true])
Sets the questlog state.
Valid only for character entities.
For state you can use one of the following:
* QUEST_OPEN
* QUEST_FINISHED
* QUEST_FAILED
set_questlog_title
entity:set_questlog_title(int id, string title[, bool notify = true])
Sets the questlog title.
Valid only for character entities.
Creation and removal of stuff
drop_item
drop_item(int x, int y, int id [, int number])
drop_item(int x, int y, string name[, int number])
Creates an item stack on the floor.
effect_create
effect_create(int id, int x, int y)
effect_create(int id, being b)
Triggers the effect id
from the clients effects.xml
(particle and/or sound) at map location x
:y
or on being b
.
This has no effect on gameplay.
Warning: Remember that clients might switch off particle effects for performance reasons. Thus you should not use this for important visual input.
entity:remove
entity:remove()
Removes the entity from its current map.
monster_create
monster_create(int monsterID, int x, int y)
monster_create(string monstername, int x, int y)
Return value: A handle to the created monster.
Spawns a new monster of type monsterID
or monstername
on the current
map on the pixel coordinates x
:y
.
npc_create
npc_create(string name, int spriteID, int gender, 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
and the gender gender
. 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.
For setting the gender you can use the constants defined in the libmana-constants.lua:
| 0 | GENDER_MALE | | 1 | GENDER_FEMALE | | 2 | GENDER_UNSPECIFIED |
npc_disable
npc_disable(handle npc)
Disable an NPC.
npc_enable
npc_disable(handle npc)
Re-enables an NPC that got disabled before.
trigger_create
trigger_create(int x, int y, int width, int height,
function trigger_function, 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 trigger_function
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.
Input and output
announce
announce(string message [, string sender])
Sends a global announce with the given message
and sender
. If no
sender
is passed "Server" will be used as sender.
ask
ask(item1, item2, ... itemN)
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 "cancel".
Items are either strings or tables of strings (indices are ignored,
but presumed to be taken in order). So,
ask("A", {"B", "C", "D"}, "E")
is the same as
ask("A", "B", "C", "D", "E")
.
ask_number
ask_number(min_num, max_num, [default_num])
Return value: The number the player entered into the field.
Warning: May only be called from an NPC talk function.
Shows a dialog box to the user which allows him to choose a number between
min_num
and max_num
. If default_num
is set this number will be
uses as default. Otherwise min_num
will be the default.
ask_string
ask_string()
Return value: The string the player entered.
Warning: May only be called from an NPC talk function.
Shows a dialog box to a user which allows him to enter a text.
entity:message
entity:message(string message)
Delivers the string message
to this entity (which needs to be a
character). It will appear in the chatlog as a private message from
"Server".
entity:say
entity:say(string message)
Makes this entity (which can be a character, monster or NPC), speak the
string message
as if it was entered by a player in the chat bar.
npc_post
npc_post()
Starts retrieving post. Better not try to use it so far.
say
say(string message)
Warning: May only be called from an NPC talk function.
Shows an NPC dialog box on the screen of displaying the string message
.
Idles the current thread until the user click "OK".
Inventory interaction
entity:change_money
entity:change_money(int amount)
Valid only for character entities.
Changes the money currently owned by this character by ''amount''.
Warning: Before reducing the money make sure to check if the character owns enough money using entity:money.
entity:equip_item
entity:equip_item(int item_id)
entity:equip_item(string item_name)
Valid only for character entities.
Makes the character equip the item id when it exists in the player's inventory.
Return value: true if equipping suceeded. false otherwise.
entity:equip_slot
entity:equip_slot(int slot)
Valid only for character entities.
Makes the character equip the item in the given inventory slot.
entity:equipment
entity:equipment(): table[](slot, item id, name)}
Valid only for character entities.
Used to get a full view of a character's equipment. This is not the preferred way to know whether an item is equipped: Use entity:inv_count for simple cases.
Return value: A table containing all the info about the character's equipment. Empty slots are not listed.
Example of use: {% highlight lua %} local equipment_table = ch:equipment() for i = 1, #equipment_table do item_message = item_message.."\n"..equipment_table[i].slot..", " ..equipment_table[i].id..", "..equipment_table[i].name end {% endhighlight %}
entity:inv_change
entity:inv_change(int id1, int number1, ..., int idN, numberN)
entity:inv_change(string name1, int number1, ..., string nameN, numberN)
Valid only for character entities.
Changes the number of items with the item ID id
or name
owned by
this character by number
. You can change any number of items with this
function by passing multiple id
or name
and number
pairs.
A failure can be caused by trying to take items the character doesn't possess.
Return value: Boolean true on success, boolean false on failure.
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 entity:inv_count.
entity:inv_count
entity:inv_count(int id1, ..., int idN)
entity:inv_count(string name1, ..., string nameN)
Valid only for character entities.
Return values: A number of integers with the amount of items id
or
name
carried or equipped by the character.
entity:inventory
entity:inventory(): table[]{slot, item id, name, amount, equipped}
Valid only for character entities.
Used to get a full view of a character's inventory. This is not the preferred way to know whether an item is in the character's inventory: Use entity:inv_count for simple cases.
Return value: A table containing all the info about the character's inventory. Empty slots are not listed.
Example of use: {% highlight lua %} local inventory_table = ch:inventory() for i = 1, #inventory_table do item_message = item_message.."\n"..inventory_table[i].slot..", " ..inventory_table[i].id..", "..inventory_table[i].name..", " ..inventory_table[i].amount end {% endhighlight %}
entity:money
entity:money()
Valid only for character entities.
Returns the money currently owned by this character.
entity:unequip_item
entity:unequip_item(int item_id)
entity:unequip_item(string item_name)
Valid only for character entities.
Makes the character unequip the item(s) corresponding to the id when it exists in the player's equipment.
Return value: true when every item were unequipped from equipment.
entity:unequip_slot
entity:unequip_slot(int slot)
Valid only for character entities.
Makes the character unequip the item in the given equipment slot.
Return value: true upon success. false otherwise.
trade
trade(bool mode,
{ int item1id, int item1amount, int item1cost }, ...,
{ int itemNid, int itemNamount, int itemNcost })
trade(bool mode,
{ string item1name, int item1amount, int item1cost }, ...,
{ string itemNname, int itemNamount, int itemNcost })
FIXME: Move into a seperate file
Opens a trade window from an NPC conversation. 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 {}.
Note: If the fourth parameters (table type) is omitted or invalid, and the mode set to sell (true), the whole player inventory is then sellable.
N.B.: Be sure to put a value
(item cost) parameter in your items.xml
to permit the player to sell it when using this option.
Return values: * 0 when a trade has been started * 1 when there is no buy/sellable items * 2 in case of errors.
Examples: {% highlight lua %} -- "A buy sample." local buycase = trade(false, { {"Sword", 10, 20}, {"Bow", 10, 30}, {"Dagger", 10, 50} }) if buycase == 0 then say("What do you want to buy?") elseif buycase == 1 then say("I've got no items to sell.") else say("Hmm, something went wrong... Ask a scripter to fix the buying mode!") end
-- ...
-- "Example: Let the player sell only pre-determined items." local sellcase = trade(true, { {"Sword", 10, 20}, {"Bow", 10, 30}, {"Dagger", 10, 200}, {"Knife", 10, 300}, {"Arrow", 10, 500}, {"Cactus Drink", 10, 25} }) if sellcase == 0 then say("Here we go:") elseif sellcase == 1 then say("I'm not interested by your items.") else say("Hmm, something went wrong...") say("Ask a scripter to fix me!") end
-- ...
-- "Example: Let the player sell every item with a 'value' parameter in
the server's items.xml file
local sellcase = trade(true)
if sellcase == 0 then
say("Ok, what do you want to sell:")
elseif sellcase == 1 then
say("I'm not interested by any of your items.")
else
say("Hmm, something went wrong...")
say("Ask a scripter to fix me!")
end
{% endhighlight %}
Item class
get_item_class
get_item_class(int itemid)
get_item_class(string itemname)
Return value: This function returns a object of the item class. See below for usage of that object.
itemclass:name
itemclass:name()
Return value: The name of the item class.
itemclass:on
itemclass:on(string event, function callback)
Assigns callback
as callback for the event
event.
Note: See get_item_class for getting a itemclass object.
Logging
DEBUG
DEBUG(string message)
Will log the ''message'' using the log level LOG_DEBUG.
Note: When passing multiple arguments these arguments will get connected using a " ".
ERROR
ERROR(string message)
Will log the ''message'' using the log level LOG_ERROR.
Note: When passing multiple arguments these arguments will get connected using a " ".
INFO
INFO(string message)
Will log the ''message'' using the log level LOG_INFO.
Note: When passing multiple arguments these arguments will get connected using a " ".
WARN
WARN(string message)
Will log the ''message'' using the log level LOG_WARNING.
Note: When passing multiple arguments these arguments will get connected using a " ".
log
log(int log_level, string message)
Log something at the specified log level. The available log levels are: | 0 | LOG_FATAL | | 1 | LOG_ERROR | | 2 | LOG_WARNING | | 3 | LOG_INFO | | 4 | LOG_DEBUG |
Map information
get_map_id
get_map_id()
Return value: The ID number of the map the script runs on.
get_map_property
get_map_property(string key)
Return value: The value of the property key
of the current map. The
string is empty if the property key
does not exist.
get_path_length
get_path_lenght(int startX, int startY, int destX, int destY, int maxRange)
get_path_lenght(int startX, int startY, int destX, int destY, int maxRange,
string walkmask)
Tries to find a path from the start coordinates to the target ones with a maximum of ''maxRange'' steps (in tiles).
If no ''walkmask'' is passed '''w''' is used.
Return value: The number of steps (in tiles) are required to reach the target or 0 if no path was found.
is_walkable
is_walkable(int x, int y)
Return value: True if x
:y
is a walkable pixel
on the current map.
map_get_pvp
map_get_pvp()
Return value: The pvp situation of the map.
There are constants for the different pvp situations in the libmana-constants.lua:
| 0 | PVP_NONE | | 1 | PVP_FREE |
Map object class
map_get_objects
map_get_objects()
map_get_objects(string type)
Return value: A table of all objects or a table of all objects of the
given type
. See below for usage of these objects.
mapobject:bounds
mapobject:bounds()
Return value: x, y position and height, width of the mapobject
.
Example use: {% highlight lua %} local x, y, width, height = my_mapobject:bounds() {% endhighlight %}
Note: See map_get_objects for getting a mapobject object.
mapobject:name
mapobject:name()
Return value: Name as set in the mapeditor of the mapobject
.
Note: See map_get_objects for getting a mapobject object.
mapobject:property
mapobject:property(string key)
Return value: The value of the property of the key key
or nil if
the property does not exists.
Note: See map_get_objects for getting a monsterclass object.
mapobject:type
mapobject:type()
Return value: Type as set in the mapeditor of the mapobject
.
Note: See map_get_objects for getting a mapobject object.
Monster
entity:monster_id
entity:monster_id()
Valid only for monster entities.
Return value: The id of the monster class.
Monster class
get_monster_class
get_monster_class(int monsterid)
get_monster_class(string monstername)
Return value: This function returns a object of the monster class. See below for usage of that object.
get_monster_classes
get_monster_classes()
Return value: A Table with all monster classes. The id of the monster is the key. The monster class itself the value. See below for the usage of this object.
monsterclass:name
monsterclass:name()
Return value: The name of the monster class.
monsterclass:on_update
monsterclass:on_update(function callback)
Assigns the callback
as callback for the monster update event. This
callback will be called every tick for each monster of that class.
Note: See get_monster_class for getting a monsterclass object.
Persistent variables
getvar_map
getvar_map(string variablename)
Return value: the value of a persistent map variable.
See: map[] for an easier way to get a map variable.
getvar_world
getvar_world(string variablename)
Gets the value of a persistent global variable.
See: world[] for an easier way to get a map variable.
map
local value = map[string key]
map[string key] = value
Sets or gets a persistent map variable. The scope of the variable is the map the script runs on. The value is stored in the database and thus will survive a server reboot.
Example: {% highlight lua %} local value = map["a key"] if value == "some value" then map["a key"] = "other value" end {% endhighlight %}
on_mapvar_changed
on_mapvar_changed(string key, function func)
Registers a callback to the key. This callback will be called with the key and value of the changed variable.
Example: {% highlight lua %} on_mapvar_changed(key, function(key, value) log(LOG_DEBUG, "mapvar " .. key .. " has new value " .. value) end) {% endhighlight %}
on_worldvar_changed
on_worldvar_changed(string key, function func)
Registers a callback to the key. This callback will be called with the key and value of the changed variable.
Example: {% highlight lua %} on_worldvar_changed(key, function(key, value) log(LOG_DEBUG, "worldvar " .. key .. " has new value " .. value) end) {% endhighlight %}
remove_mapvar_listener
remove_mapvar_listener(string key, function func)
Unassigns a function from getting notified from mapvar changes.
remove_worldvar_listener
remove_worldvar_listener(string key, function func)
Unassigns a function from getting notified from worldvar changes.
setvar_map
setvar_map(string variablename, string value)
Sets the value of a persistent map variable.
See: map[] for an easier way to get a map variable.
setvar_world
setvar_world(string variablename, string value)
Sets the value of a persistent global variable.
See: world[] for an easier way to get a map variable.
world
local value = world[string key]
world[string key] = value
Sets or gets a persistent world variable. The value is stored in the database and thus will survive a server reboot.
Important: When you are using this function, be aware of race conditions: It is impossible to prevent that another map changes the value of a variable between you requesting to old value and setting a new value.
Example: {% highlight lua %} local value = world["a key"] if value == "some value" then world["a key"] = "other value" end {% endhighlight %}
Scheduling
atinit
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.
on_death
on_death(handle being, function() [function body] end)
Executes the ''function body'' when ''being'' is killed. Note that this doesn't happen anymore after the being left the map.
on_remove
on_remove(handle being, function() [function body] end)
Executes the ''function body'' when ''being'' is no longer on the map for some reason (leaves the map voluntarily, is warped away, logs out, cleaned up after getting killed or whatever). The removed ''being'' will be passed as an argument of the function
schedule_every
schedule_every(seconds, function() [function body] end)
Executes the ''function body'' every ''seconds'' seconds from now on.
schedule_in
schedule_in(seconds, function() [function body] end)
Executes the ''function body'' in ''seconds'' seconds.
schedule_per_date
schedule_per_date(year, month, day, hour, minute, function() [function body] end)
Executes the ''function body'' at the given date and time.
Status effect class
get_status_effect
get_status_effect(string name)
Return value: This function returns a object of the statuseffect class. See below for usage of that object.
statuseffect:on_tick
statuseffect:on_tick(function callback)
Sets the callback that gets called for every tick when the status effect is active.
Note: See get_status_effect for getting a statuseffect object.
Status effects
entity:apply_status
entity:apply_status(int status_id, int time)
Valid only for being entities.
Gives a being a status effect status_id
, status effects don't work on
NPCs. time
is in game ticks.
entity:has_status
entity:has_status(int status_id)
Valid only for being entities.
Return value: True if the being has a given status effect.
entity:remove_status
entity:remove_status(int status_id)
Valid only for being entities.
Removes a given status effect from a being.
entity:set_status_time
entity:set_status_time(int status_id, int time)
Valid only for being entities.
Sets the time on a status effect a target being already has.
entity:status_time
entity:status_time(int status_id)
Valid only for being entities.
Return Value: Number of ticks remaining on a status effect.
Needed script bindings
Area of Effect
Possible missing area of effect functions:
- get_beings_in_cone
- get_beings_in_line