We give here the list of Lua functions that are called by the C++ engine (such functions are called events), and the list of C++ functions that may be called by Lua scripts. This documentation page is intented to Lua programers who want to know the functions available. For the point of view of the engine, see the documentation of the C++ class Script.

For now, the following types of scripts exist:

The script of a map (maps/mapXXXX.lua): controls the map XXXX.
The script of an enemy (enemies/XXXX.lua): controls an enemy whose breed is "XXXX". Each instance of enemy has its own Lua state (in particular its own global values), even if several enemies of the same breed exist at the same time on the current map.
The script of an item (items/XXXX.lua): controls the item named "XXXX" in items.dat. For each item, only one Lua state is created for the whole game and it persists across map changes.

Other types such as scriptable menus will come eventually.

A Lua script can call C++ functions through a global table called sol. The functions are organized into several APIs. The APIs that are available to your script depend on the type of script. For now, the following APIs are implemented:

sol.main: functions available to all types of scripts, even outside a game.
sol.game: this module represents the current game. It provides functions to manage game information such as the savegame and the equipment.
sol.map: this module respresents the current map. It provides functions to manage the entities placed on the map, including the hero.
sol.item: this module represents a particular type of equipment item, and possibly, depending on the current context, an instance of pickable item present on the map or an instance of inventory item currently being used by the hero.
sol.enemy: this module represents the current instance of an enemy.

The C++ code can also call Lua functions to notify the scripts that an event happened.

Calling C++ from Lua

We describe here all functions provided to Lua scripts through the sol object.

The sol.main module is available to any type of Lua script, even when no game is running. It contains functions to play sounds or musics, set timers, and manage sprites and movements.

Your script can create a sprite or get a handle to an existing sprite (e.g. a sprite attached to an NPC). In both cases, you can then call all sprite-related functions and give the sprite handle as first paramater.

sol.main.include(script_name): includes another script into this one

sol.main.play_sound(sound_id): plays a sound

sol.main.play_music(music_id): plays a music

sol.main.timer_start(function, duration, with_sound): starts a timer which will calls a function once finished (with_sound is optional, default is false)

sol.main.timer_stop_all(): stops all timers started by your script

sol.main.sprite_create(sprite_name): Creates a sprite given its name (i.e. its animation set) and returns a handle to it.

sol.main.sprite_get_animation(sprite): returns the name of the current animation of a sprite

sol.main.sprite_set_animation(sprite, animation_name): sets the current animation of a sprite

sol.main.sprite_get_direction(sprite): returns the current direction of a sprite (0 to nb_directions-1)

sol.main.sprite_set_direction(sprite, direction): sets the current direction of a sprite (0 to nb_directions-1)

sol.main.sprite_get_frame(sprite): returns the index of the current frame of a sprite (0 to nb_frames-1)

sol.main.sprite_set_frame(sprite, frame): sets the current frame of a sprite (0 to nb_frames-1)

sol.main.sprite_get_frame_delay(sprite): returns the delay between two frames of a sprite, in milliseconds

sol.main.sprite_set_frame_delay(sprite, delay): sets the delay between two frames of a sprite, in milliseconds

sol.main.sprite_is_paused(sprite): returns whether a sprite is paused

sol.main.sprite_set_paused(sprite, paused): pauses or resumes the animation of a sprite

sol.main.sprite_set_animation_ignore_suspend(sprite, ignore): sets whether the animation should continue even when the sprite is suspended

sol.main.sprite_fade(sprite, direction): shows a fade effect on a sprite (0: fade-in, 1: fade-out)

sol.main.sprite_synchronize(sprite, reference_sprite): Synchronizes the frames of a sprite with the frames of a reference sprite when their animation name match. Stops any previous synchronization if reference_sprite is nil.

sol.main.pixel_movement_create(trajectory, delay): creates a movement of type PixelMovement that will be accessible from this script

sol.main.random_movement_create(speed): creates a movement of type RandomMovement that will be accessible from this script

sol.main.path_movement_create(path, speed): creates a movement of type PathMovement that will be accessible from this script

sol.main.random_path_movement_create(speed): creates a movement of type RandomPathMovement that will be accessible from this script

sol.main.path_finding_movement_create(speed): creates a movement of type PathFindingMovement (targeting the hero) and that will be accessible from this script

sol.main.target_movement_create(speed, target_x, target_y): creates a movement of type TargetMovement that will be accessible from this script; target_x and target_y are optional, the default behavior is to track the hero

sol.main.straight_movement_create(speed, angle): creates a movement of type StraightMovement that will be accessible from this script

sol.main.circle_movement_create(center_type, center_name, radius): creates a movement of type CircleMovement that will be accessible from this script

sol.main.jump_movement_create(direction, length): creates a movement of type JumpMovement that will be accessible from this script

sol.main.movement_get_property(movement, key): returns a string property from a movement (warning: it always returns a string!)

sol.main.movement_set_property(movement, key, value): sets a property of a movement (the value may be a string, an integer or a boolean)

sol.main.movement_test_obstacles(movement, dx, dy): Returns whether there would be a collision if the entity controlled by a movement object was translated with the given parameters.

sol.main.get_angle(x1, y1, x2, y2): Returns the angle in radians between the specified vector and the x axis.

The sol.game module is available to scripts running into a game. sol.game can be seen as an object that represents the current game. It provides functions to manage the game data.

sol.game.save(): saves the game

sol.game.reset(): resets the game (comes back to the title screen)

sol.game.restart(): restarts the game, continuing on the same savegame even if it is not saved

sol.game.savegame_get_string(index): returns a string saved

sol.game.savegame_get_integer(index): returns an integer saved

sol.game.savegame_get_boolean(index): returns a boolean saved

sol.game.savegame_set_string(index, value): sets a string in the savegame

sol.game.savegame_set_integer(index, value): sets an integer in the savegame

sol.game.savegame_set_boolean(index, value): sets a boolean in the savegame

sol.game.savegame_get_name(): returns the name of the hero (cannot exceed 5 characters)

sol.game.get_life(): returns the current level of life of the player

sol.game.add_life(life): adds some life to the player

sol.game.remove_life(life): removes some life from the player

sol.game.get_max_life(): returns the maximum level of life of the player

sol.game.add_max_life(life): increases the maximum level of life of the player

sol.game.get_money(): returns the amount of money of the player

sol.game.add_money(money): adds some money to the player

sol.game.remove_money(money): removes some money from the player

sol.game.get_magic(): returns the current number of magic points

sol.game.add_magic(magic): adds some magic points

sol.game.remove_magic(magic): removes some magic points

sol.game.start_decreasing_magic(delay): starts removing magic points continuously

sol.game.stop_decreasing_magic(): stops removing magic points continuously

sol.game.get_max_magic(): returns the maximum number of magic points

sol.game.set_max_magic(magic): sets the maximum number of magic points

sol.game.has_ability(ability_name): Returns whether the player has an ability. Equivalent to sol.game.get_ability(ability_name) > 0.

sol.game.get_ability(ability_name): returns the level of an ability

sol.game.set_ability(ability_name, level): sets the level of an ability

sol.game.has_item(item_name): Returns whether the player has an item. Equivalent to sol.game.get_item(item_name) > 0.

sol.game.get_item(item_name): returns the possession state of an item

sol.game.set_item(item_name, variant): sets the possession state of an item

sol.game.has_item_amount(item_name, amount): Returns whether the player has at least the specified amount of an item (the item must have a counter). Equivalent to sol.game.get_item_amount(item_name) > 0.

sol.game.get_item_amount(item_name): Returns the amount the player has for an item (the item must have a counter).

sol.game.add_item_amount(item_name, amount): Adds an amount of the specified item (the item must have a counter).

sol.game.remove_item_amount(item_name, amount): Removes an amount of the specified item (the item must have a counter).

sol.game.is_dungeon_finished(dungeon): returns whether the specified dungeon is finished

sol.game.set_dungeon_finished(dungeon): sets the specified dungeon as finished

The sol.map module is available to scripts attached to a map. sol.map can be seen as an object that represents the current map and the elements displayed with it. Most of the functions provided here apply to an entity of the map (possibly the hero) and are prefixed by the type of entity.

sol.map.dialog_start(dialog_id): Show a dialog box.

sol.map.dialog_set_variable(dialog_id, value): Specifies a value to display inside a dialog (for example the player's name). In this dialog, the sequence $v will be substituted by this value.

sol.map.dialog_set_style(style): Sets the style of the dialog box for subsequent dialogs (0: usual dialog box, 1: no dialog box, only display the text)

sol.map.hud_set_pause_enabled(bool enabled): Allows or disallows to pause the game (and thus to save the game).

sol.map.hud_set_enabled(enabled): Hides or restores the HUD (the player can still use his items and pause the game).

sol.map.light_get(): returns the current light level of the map

sol.map.light_set(light_level): sets the light level of the map (0: no light, positive values: full light)

sol.map.camera_move(x, y, speed, function, delay_before, delay_after): moves the camera to a target point (a usual speed value is 250), waits a delay in milliseconds (default is 1000), calls a function, waits another delay (default is 1000) and restores the camera; the game is suspended during the whole sequence

sol.map.tileset_get(): returns the id of the tileset of this map

sol.map.tileset_set(tileset_id): Changes the tileset used to draw the map. The new tileset must be compatible with the previous one, i.e. every tile of the previous tileset must exist in the new one and have the same properties. This function keeps the tiles of the previous tileset and loads the image of the new tileset.

sol.map.sprite_display(sprite, x, y): Displays a sprite at the given position (relative to the the map top-left corner). The origin point of the sprite will be displayed at this location.

sol.map.treasure_give(item_name, variant, savegame_variable): gives a treasure to the player (without using a chest)

sol.map.hero_freeze(): prevents the hero from moving until you call sol.map.hero_unfreeze()

sol.map.hero_unfreeze(): restores the control to the hero, typically after a call to sol.map.hero_freeze()

sol.map.hero_set_map(map_id, destination_point, transition): Sends the hero on a map (possibly the same one), see Transition::Style for the values of transition.

sol.map.hero_set_visible(visible): Hides or unhides the hero. The player can continue to control him even if he is invisible.

sol.map.hero_get_direction(): Returns the direction of the hero's sprites (0 to 3).

sol.map.hero_set_direction(direction4): Sets the direction of the hero's sprites (0 to 3).

sol.map.hero_get_position(): Returns the coordinates and the layer of the hero (3 return values).

sol.map.hero_set_position(x, y, layer): Sets the coordinates and the layer of the hero. The layer is optional: by default, it is unchanged.

sol.map.hero_align_on_sensor(sensor_name): places the hero's bounding box exactly on the rectangle of a sensor

sol.map.hero_save_solid_ground(x, y, layer): Memorizes a position to go back to if the hero falls into a hole or other bad ground. This replaces the usual behavior which is going back to the previous solid position just before falling. The arguments are optional: by default, they correspond to the current position of the hero. But if you provide them, you must set all three of them, otherwise they are ignored.

sol.map.hero_reset_solid_ground(): Forgets a position that was previously memorized by sol.map.hero_set_solid_ground() (if any). The usual behavior is restored: the hero will now just get back to where he was just before falling, instead going to of a memorized position.

sol.map.hero_walk(path, loop, ignore_obstacles): Makes the hero move with the specified path and a walking animation. The player cannot control him during the movement.

sol.map.hero_start_jumping(direction8, length, ignore_obstacles): makes the hero jump towards the specified direction (0 to 7)

sol.map.hero_start_victory_sequence(): Makes the hero brandish his sword for a victory. When the animation finishes, event_hero_victory_sequence_finished will be called in the map script.

sol.map.hero_start_boomerang(max_distance, speed, tunic_preparing_animation, sprite_name): Makes the hero throw a boomerang. tunic_preparing_animation is the name of the animation that the hero's tunic sprite should take while preparing the boomerang. sprite_name is the animation set id to use to draw the boomerang then.

sol.map.hero_start_bow(): makes the hero shoot an arrow

sol.map.hero_start_running(): makes the hero run

sol.map.hero_start_hurt(source_x, source_y, life_points, magic_points): Hurts the hero. The number of life points will be reduced with the tunic level.

sol.map.npc_is_enabled(npc_name): returns whether an NPC is enabled

sol.map.npc_set_enabled(npc_name, enable): enables or disables an NPC

sol.map.npc_set_group_enabled(npc_prefix, enable): enables or disables all NPCs having a common prefix

sol.map.npc_get_position(npc): Returns the position of an NPC (x, y and layer).

sol.map.npc_set_position(npc, x, y, layer): Sets the position of an NPC. The layer is optional (by default, it is unchanged).

sol.map.npc_start_movement(npc, movement): starts a movement on an NPC

sol.map.npc_stop_movement(npc, movement): stops the movement of an NPC

sol.map.npc_get_sprite(npc): Returns the sprite of an NPC. Your script can then use the sol.main.sprite_* functions on it.

sol.map.npc_remove(npc): removes an NPC from the map

sol.map.npc_exists(npc): checks the existence of an NPC

sol.map.chest_is_open(chest_name): returns the state of a chest

sol.map.chest_set_open(chest_name, open): sets the state of a chest (without giving or reseting its content)

sol.map.chest_is_enabled(chest_name): returns whether a chest is enabled

sol.map.chest_set_enabled(chest_name, enable): enables or disables a chest

sol.map.chest_set_group_enabled(chests_prefix, enable): enables or disables all chests having a common prefix

sol.map.tile_is_enabled(tile_name): returns whether a dynamic tile is enabled

sol.map.tile_set_enabled(tile_name, enable): enables or disables a dynamic tile

sol.map.tile_set_group_enabled(tiles_prefix, enable): enables or disables all dynamic tiles having a common prefix

sol.map.stairs_is_enabled(stairs_name): returns whether some stairs are enabled

sol.map.stairs_set_enabled(stairs_name, enable): enables or disables some stairs

sol.map.stairs_set_group_enabled(stairs_prefix, enable): enables or disables all stairs having a common prefix

sol.map.obstacle_is_enabled(custom_obstacle_name): returns whether a custom obstacle is enabled

sol.map.obstacle_set_enabled(custom_obstacle_name, enable): enables or disables a custom obstacle

sol.map.obstacle_set_group_enabled(custom_obstacles_prefix, enable): enables or disables all custom obstacles having a common prefix

sol.map.sensor_is_enabled(sensor_name): returns whether a sensor is enabled

sol.map.sensor_set_enabled(sensor_name, enable): enables or disables a sensor

sol.map.sensor_set_group_enabled(sensors_prefix, enable): enables or disables all sensors having a common prefix

sol.map.jumper_is_enabled(jumper_name): returns whether a jumper is enabled

sol.map.jumper_set_enabled(jumper_name, enable): enables or disables a jumper

sol.map.jumper_set_group_enabled(jumpers_prefix, enable): enables or disables all jumpers having a common prefix

sol.map.crystal_is_enabled(crystal_name): returns whether a crystal is enabled (i.e. whether it is visible)

sol.map.crystal_set_enabled(crystal_name, enable): enables or disables a crystal

sol.map.crystal_set_group_enabled(crystals_prefix, enable): enables or disables all crystals having a common prefix

sol.map.crystal_get_state() returns the state of crystal blocks (false: initial, true: modified)

sol.map.crystal_set_state(state) sets the state of crystal blocks (false: initial, true: modified)

sol.map.crystal_change_state() inverts the state of crystal blocks

sol.map.teletransporter_is_enabled(teletransporter_name): returns whether a teletransporter is enabled

sol.map.teletransporter_set_enabled(teletransporter_name, enable): enables or disables a teletransporter

sol.map.teletransporter_set_group_enabled(teletransporters_prefix, enable): enables or disables all teletransporters having a common prefix

sol.map.block_is_enabled(block_name): returns whether a block is enabled

sol.map.block_set_enabled(block_name, enable): enables or disables a block

sol.map.block_set_group_enabled(blocks_prefix, enable): enables or disables all blocks having a common prefix

sol.map.block_reset(block_name): places a block where it was when the map started

sol.map.block_reset_all(): resets all blocks of the map

sol.map.block_get_position(block_name): Returns the position of a block (3 return values: x, y, layer).

sol.map.block_set_position(block_name, x, y, layer): Sets the position of a block. The layer is optional (by default, it is unchanged).

sol.map.shop_item_exists(shop_item_name): Returns whether a shop item exists on the map.

sol.map.shop_item_remove(shop_item_name): Removes a shop item from the map if it exists.

sol.map.switch_is_activated(switch_name): returns whether a switch is activated

sol.map.switch_set_activated(switch_name, activated): activates or inactivates a switch

sol.map.switch_set_locked(switch_name, locked): locks a switch in its current state or unlocks it

sol.map.switch_is_enabled(switch_name): returns whether a switch is enabled (i.e. visible)

sol.map.switch_set_enabled(switch_name, enable): enables or disables a switch

sol.map.switch_set_group_enabled(switches_prefix, enable): enables or disables all switches having a common prefix

sol.map.door_open(door_prefix): Opens one or several doors, playing their animation and sound. If some doors with this prefix are already open, nothing happens for them.

sol.map.door_close(door_prefix): Closes one or several doors, playing their animation and sound. Nothing happens if some doors with this prefix are already closed.

sol.map.door_is_open(door_name): returns whether a door is open

sol.map.door_set_open(door_name, open): changes immediately the state of a door (without playing animation and sound)

sol.map.pickable_item_create(item_name, variant, savegame_variable, x, y, layer): creates a pickable item and places it on the map

sol.map.destructible_item_create(subtype, x, y, layer, properties): Creates a destructible item and places it on the map. subtype can be "pot", "bush", "white_stone", "black_stone", "grass" or "bomb_flower". properties is optional. If provided, it is a table whose key-value pairs can be:
- treasure_name (string, default "_random"): treasure under the destructible item, can also be "_none" or "_random",
- treasure_variant (integer, default 1): variant of this treasure,
- treasure_savegame_variable (integer, default -1): savegame variable of this treasure (-1 means not saved),
- destruction_callback (function, default nil): a function that will be called when the destructible item is destroyed.

sol.map.block_create(x, y, layer, name, properties): Creates a block and places it on the map. properties is optional. If provided, it is a table whose key-value pairs can be:
- direction (integer, 0 to 3 or -1 to allow the block to move in any direction (default is -1)),
- sprite_name (string, default "entities/block"),
- can_be_pushed (boolean, default true),
- can_be_pulled (boolean, default false),
- maximum_moves (integer: 0 for no move, 1 for one move only (default), 2 for infinite moves)

sol.map.bomb_create(x, y, layer): creates a bomb and places it on the map

sol.map.explosion_create(x, y, layer): creates an explosion on the map

sol.map.fire_create(x, y, layer): creates some fire on the map

sol.map.arrow_remove() removes any arrow currently thrown on the map

sol.map.enemy_create(enemy_name, breed, layer, x, y): Creates an enemy on the map.

sol.map.enemy_remove(enemy_name): Removes an enemy from the map.

sol.map.enemy_remove_group(enemies_name_prefix): Removes a group of enemies from the map.

sol.map.enemy_is_enabled(enemy_name): returns whether an enemy is enabled

sol.map.enemy_set_enabled(enemy_name, enable): enables or disables an enemy

sol.map.enemy_set_group_enabled(enemies_prefix, enable): enables or disables all enemies having a common prefix

sol.map.enemy_is_dead(enemy_name): returns whether an enemy is dead

sol.map.enemy_is_group_dead(enemies_name_prefix): returns whether all enemies having a common prefix are dead

sol.map.enemy_get_group_count(enemies_name_prefix): Returns the number of living enemies of the map whose name starts with the specified prefix.

sol.map.enemy_get_position(enemy_name): Returns the current position of an enemy on the map. Three values are returned: x, y and the layer (0 to 2).

sol.map.enemy_set_position(enemy_name, x, y, layer): Sets the positions of an enemy on the map. The layer is optional: by default, it is unchanged.

sol.map.enemy_set_treasure(enemy_name, item_name, variant, savegame_variable): Sets the treasure of an enemy.

sol.map.enemy_set_no_treasure(enemy_name): Sets no treasure for an enemy.

sol.map.enemy_set_random_treasure(enemy_name): Sets a random treasure for an enemy.

sol.map.enemy_get_sprite(enemy_name): Returns the sprite of an enemy (if the enemy has several sprites, the first one created is returned)

The sol.item module is available to scripts attached to an item defined in the items.dat file. sol.item can be seen as an object that represents a particular item of the equipment. Depending on the current context, sol.item may additionally represent an instance of pickable item present on the map or an instance of inventory item currently being used by the hero.

sol.item.get_variant(): returns the possession state of the item controlled by this script (0: not possessed, 1: first variant, 2: second variant, etc.)

sol.item.set_variant(variant): sets the possession state of the item controlled by this script (0: not possessed, 1: first variant, 2: second variant, etc.)

sol.item.get_amount(): returns the amount of the item controlled by this script (only for an item with amount)

sol.item.set_amount(amount): sets the amount of the item controlled by this script (only for an item with a counter)

sol.item.add_amount(amount): increases the amount of the item controlled by this script (only for an item with a counter)

sol.item.remove_amount(amount): decreases the amount of the item controlled by this script (only for an item with a counter)

sol.item.get_sprite(): returns the sprite representing the current pickable item (can be called only when there is a current pickable item in the context)

sol.item.get_movement(): returns the movement of the current pickable item (can be called only when there is a current pickable item in the context)

sol.item.start_movement(movement): gives another movement to the current pickable item instead of the default one (can be called only when there is a current pickable item in the context)

sol.item.get_position(): Returns the position of the current pickable item (returns x, y and the layer). Can be called only when there is a current pickable item in the context.

sol.item.set_position(x, y, layer): Sets the position of the current pickable item. The layer is optional: by default, it is unchanged. Can be called only when there is a current pickable item in the context.

sol.item.set_layer_independent_collisions(independent): sets whether the collisions with the current pickable item should be detected from every layer (can be called only when there is a current pickable item in the context)

sol.item.set_finished(): notifies the hero that he has finished using the current inventory item and can get back to a normal state (can be called only when the hero is currently using the inventory item controlled by this script)

The sol.enemy module is available to scripts attached to an enemy. sol.enemy represents a particular instance of enemy. Each breed of enemy is controlled by a Lua script. If several enemies of the same breed exist on the map, they all have their own Lua world, which means they don't share global values.

sol.enemy.get_name(): returns the name of the current enemy

sol.enemy.get_life(): returns the current level of life of the enemy

sol.enemy.set_life(life): sets the level of life of the enemy (default is 1 when the enemy is created)

sol.enemy.add_life(life): adds some life to the enemy

sol.enemy.remove_life(life): remove some life from the enemy

sol.enemy.get_damage(): returns the number of life points that the enemy removes from the hero when touching him (when the hero's defense level is minimal)

sol.enemy.set_damage(damage): sets the number of life points that the enemy removes from the hero when touching him (when the hero's defense level is minimal) (default is 1)

sol.enemy.get_magic_damage(): returns the number of magic points that the enemy removes from the hero when touching him

sol.enemy.set_magic_damage(magic_damage): sets the number of magic points that the enemy removes from the hero when touching him (default is 0)

sol.enemy.is_pushed_back_when_hurt(): returns whether the enemy is pushed away when it is hurt

sol.enemy.set_pushed_back_when_hurt(pushed_back_when_hurt): sets whether the enemy is pushed away when it is hurt (default is true)

sol.enemy.get_push_hero_on_sword(): returns whether the hero is pushed away when he strikes the enemy with the sword

sol.enemy.set_push_hero_on_sword(push_hero_on_sword): sets whether the hero is pushed away when he strikes the enemy with the sword (default is false)

sol.enemy.get_can_hurt_hero_running(can_hurt_hero_running): returns whether the enemy can hurt the hero even when the hero is running

sol.enemy.set_can_hurt_hero_running(can_hurt_hero_running): sets whether the enemy can hurt the hero even when the hero is running (default is false)

sol.enemy.get_hurt_style(): returns the style of sounds and animations to play when the enemy is hurt: "normal", "monster" or "boss"

sol.enemy.set_hurt_style(style): sets the style of sounds and animations to play when the enemy is hurt: "normal", "monster" or "boss" (default is "normal" for usual enemies and "boss" for bosses and minibosses)

sol.enemy.get_can_attack(): returns whether the enemy can currently attack the hero

sol.enemy.set_can_attack(can_attack): Sets whether the enemy can currently attack the hero (default is true). When the enemy restarts after being hurt, can_attack is always reset to true.

sol.enemy.get_minimum_shield_needed(): returns the minimum hero's level of shield that allows him to stop attacks from this enemy (0 means that he cannot stop the attacks)

sol.enemy.set_minimum_shield_needed(shield_level): returns the minimum hero's level of shield that allows him to stop attacks from this enemy (0 means that he cannot stop the attacks and is the default)

sol.enemy.set_attack_consequence(attack, consequence): Sets how the enemy reacts when it receives an attack. attack can be "sword", "thrown_item", "explosion", "arrow", "hookshot", "boomerang", or "fire". consequence can be an integer that indicates the number of life points to remove, or the string "ignored", "protected", "immobilize" or "custom". This reaction will be applied unless the sprite that receives the attack has a specific reaction (see sol.enemy.set_attack_consequence_sprite).

sol.enemy.set_attack_consequence_sprite(sprite, attack, consequence): Sets how the enemy reacts when a particular sprite receives an attack. attack and consequence can have the same values as sol.enemy.set_attack_consequence.

sol.enemy.set_default_attack_consequences(): Sets the default attack consequences for the enemy.

sol.enemy.set_default_attack_consequences_sprite(sprite): Sets the default attack consequences for a particular sprite of the enemy.

sol.enemy.set_invincible(): Makes the enemy ignore all attacks. Equivalent to calling sol.enemy.set_attack_consequence(attack, "ignored") for each attack.

sol.enemy.set_invincible_sprite(sprite): Makes a particular sprite of the enemy ignore all attacks. Equivalent to calling sol.enemy.set_attack_consequence_sprite(sprite, attack, "ignored") for each attack.

sol.enemy.set_layer_independent_collisions(independent): Sets whether the collisions with the enemy should be detected from every layer (default is false).

sol.enemy.set_treasure(item_name, variant, savegame_variable): Sets the treasure of the enemy. item_name can be the name of a valid item, "_none" or "_random". savegame_variable can be -1 if you don't want the item to be saved.

sol.enemy.set_no_treasure(): Sets no treasure of the enemy. Equivalent to sol.enemy.set_treasure("_none", 1, -1).

sol.enemy.set_random_treasure(): Sets a random treasure for the enemy (this is the default behavior). Equivalent to sol.enemy.set_treasure("_random", 1, -1).

sol.enemy.get_obstacle_behavior(): Returns how the enemy behaves with obstacles: "normal", "flying" or "swimming".

sol.enemy.set_obstacle_behavior(behavior): Sets how the enemy behaves with obstacles: "normal", "flying" or "swimming". "flying" will ignore obstacles like holes, water or lava. "swimming" will ignore water.

sol.enemy.get_size(): Returns the size of the enemy's bounding box (two return values: width and height in pixels).

sol.enemy.set_size(width, height): Sets the size of the enemy's bounding box (default: 16, 16). This is the effective size used to detect obstacles when moving, but the sprite of the enemy may be larger, especially for a boss.

sol.enemy.get_origin(): Returns the coordinates of the origin point of the enemy, relative to its bounding box top-left corner (two returns values: x and y).

sol.enemy.set_origin(x, y): Sets the coordinates of the origin point of the enemy, relative to its bounding box top-left corner (default: 0, 0).

sol.enemy.get_position(): Returns the current position of the enemy on the map (i.e. the position of its origin point relative to the map's top-left corner). Three values are returned: x, y and the layer.

sol.enemy.set_position(x, y, layer): Sets the position of the enemy on the map (i.e. the position of its origin point relative to the map's top-left corner). The layer is optional: by default, is is unchanged.

sol.enemy.get_distance_to_hero(): Returns the distance in pixels between the enemy and the hero.

sol.enemy.get_angle_to_hero(): Returns the angle in radians of the vector from the enemy to the hero.

sol.enemy.test_obstacles(dx, dy): Returns whether there would be a collision if the enemy was translated with the given parameters.

sol.enemy.snap_to_grid(): Makes sure the enemy's top-left corner is aligned with the 8*8 grid of the map. Be careful: this function does not check collisions with obstacles.

sol.enemy.get_movement(): Returns the current movement of the enemy.

sol.enemy.start_movement(movement): Sets a movement to the enemy (any previous movement is destroyed).

sol.enemy.stop_movement(): Stops and destroys the current movement of the enemy (if any).

sol.enemy.restart(): Restarts the enemy. This plays animation "walking" on its sprites and triggers event_restart().

sol.enemy.hurt(life_points): Hurts the enemy.

sol.enemy.create_sprite(animation_set): Creates a sprite attached to the enemy and returns it.

sol.enemy.remove_sprite(sprite): Removes and destroys a sprite of this enemy. If sprite is not specified, the first sprite that was created is removed.

sol.enemy.get_sprite(): Returns the sprite of the enemy. If the enemy has several sprites, the first one that was created is returned. If you have created several sprites, this function is probably not for you: you should memorize the return value of each call to sol.enemy.create_sprite instead.

sol.enemy.create_son(enemy_name, breed, x, y, layer): Creates another enemy, specifying its coordinates as relative to the current enemy. The layer is optional: by default, the enemy is created on the same layer as the current one.

sol.enemy.get_father(): Returns the name of the father of the enemy (if any). The father is the enemy that created the current one by calling sol.enemy.create_son, Returns an empty string if the current enemy has no father.

sol.enemy.send_message(dst_enemy, message): Sends a string message to another enemy. His function event_message_received() will be called, and then sol.enemy.send_message will return.

Calling Lua from C++

The C++ engine sometimes notifies a script that an event just happened. The corresponding event function of the script is called if it exists. An event function is a Lua function prefixed by event_. We give here the list of event functions that the engine will call if you define them in your script. Each event may be called in one or several types of script.

Map scripts

event_update(): called at each cycle (so take care of the performances)

event_set_suspended(suspended): called when the game is suspended or resumed

event_dialog_started(dialog_id): Called when a dialog box starts, even if the dialog was started by another script.

event_dialog_finished(dialog_id, answer): Called when a dialog finishes (i.e. once its last group of 3 lines is finished), even if the dialog was started by another script. If there was a question, answer is 0 if the first answer was chosen, or 1 if the second one was chosen. If there was no question, answer is -1.

event_camera_back(): Called when the camera (previously sent by sol.map.camera_move()) is back to the hero.

event_treasure_obtaining(item_name, variant, savegame_variable): Called when the player is obtaining a treasure (coming from a chest or not), just before the dialog starts.

event_treasure_obtained(item_name, variant, savegame_variable): Called when the player has finished obtaining a treasure, just after the dialog.

event_map_started(destination_point_name): called when the map starts, before the opening transition

event_map_opening_transition_finished(destination_point_name): called after the opening transition of the map

event_switch_activated(switch_name): Called when a switch has just been activated.

event_switch_inactivated(switch_name): Called when a switch has just been inactivated.

event_switch_left(switch_name): called when an entity placed on a switch (the hero or a block) has just left the switch, no matter if the switch was activated or not

event_hero_victory_sequence_finished(): Called when the victory animation of the hero (started with sol.map.hero_start_victory_sequence()) is finished.

event_hero_on_sensor(sensor_name): Called when the hero arrives on a sensor. The bounding box of the hero must be entirely inside the sensor's bounding box.

event_hero_still_on_sensor(sensor_name): Called continuously while the hero is on a sensor.

event_npc_interaction(npc_name) (triggered only if the NPC has the property to call the map script): called when the hero interacts with an NPC by pressing the action key

event_npc_interaction_finished(npc_name): (triggered only if the NPC has the property to call the map script): called when the hero has just interacted with an NPC by pressing the action key

event_npc_interaction_item(npc_name, item_name, variant) (triggered only if the NPC has the property to call the map script): called when the hero interacts with an NPC by using ANY inventory item; returns true if an interaction actually happened

event_npc_interaction_item_finished(npc_name, item_name, variant): called when the hero has just interacted with an NPC by using ANY inventory item

event_npc_movement_finished(npc_name): called when an NPC has finished its movement

event_npc_collision_fire(npc_name) (triggered only if the NPC has the property to call the map script): called when some fire touches an NPC

event_sensor_collision_explosion(sensor_name): called when an explosion overlaps a sensor

event_chest_empty(chest_name): Called when the hero opens an empty chest. The hero remains freezed. Your script has to define what happens (for example giving a treasure or show an error message). If you don't give a treasure, you have to unblock the hero explicitely by calling sol.map.hero_unfreeze().

event_shop_item_buying(shop_item_name): Called when the player wants to buy an item in a shop and has enough money: if you return false, the player cannot buy it.

event_shop_item_bought(shop_item_name): called when the player has just bought an item in a shop

event_door_open(door_name): called when a door has just been open

event_door_closed(door_name): called when a door has just been closed

event_block_moved(block_name): called when a block has just been pushed or pulled by the hero on a section of 16 pixels (or less if there was an obstacle)

event_enemy_dying(enemy_name): Called when an enemy of this map is dying (its kill animation starts).

event_enemy_dead(enemy_name): Called when an enemy of this map is dead (and its kill animation is finished).

Item scripts

event_update(): called at each cycle (so take care of the performances)

event_set_suspended(suspended): called when the game is suspended or resumed

event_map_changed(new_map_id): called when a map becomes the current map

event_dialog_started(dialog_id): (triggered only if this item script started the dialog): called when a dialog box starts

event_dialog_finished(dialog_id, answer): (triggered only if this item script started the dialog): called when a dialog finishes (i.e. once its last group of 3 lines is finished)

event_npc_interaction(npc_name): (triggered only if the npc has the property to notify the item controlled by this script): called when the hero interacts with an NPC by pressing the action key

event_npc_interaction_finished(npc_name): (triggered only if the NPC has the property to notify the item controlled by this script): called when the hero has just interacted with an NPC by pressing the action key

event_npc_interaction_item(npc_name, item_name, variant): (triggered only if the NPC has the property to notify the item controlled by this script): called when the hero interacts with an NPC by using ANY inventory item; returns true if an interaction actually happened

event_npc_interaction_item_finished(npc_name, item_name, variant): (triggered only if the NPC has the property to notify the item controlled by this script): called when the hero has just interacted with an NPC by using ANY inventory item

event_npc_collision_fire(npc_name): (triggered only if the NPC has the property to notify the item controlled by this script): called when some fire touches an NPC

event_appear(variant, savegame_variable, falling_height): Called when a pickable item whose type is controlled by this script has just appeared on the map.

event_movement_changed(): called when something changes in the movement of a pickable item whose type is controlled by this script

event_obtaining(variant, savegame_variable): called when the player is obtaining a treasure corresponding to the item controlled by this script

event_obtained(variant, savegame_variable): called when the player has finished brandishing a treasure corresponding to the item controlled by this script

event_variant_changed(variant): called when the saved possession state of the item controlled by this script has just changed

event_amount_changed(amount): called when the amount of the item controlled by this script has just changed

event_use(): called when the hero starts using the item controlled by this script from his inventory

Enemy scripts

event_update(): called at each cycle (so take care of the performances)

event_set_suspended(suspended): called when the game is suspended or resumed

event_dialog_started(dialog_id): (triggered only if this enemy script started the dialog): called when a dialog starts

event_dialog_finished(dialog_id, answer): (triggered only if this enemy script started the dialog): called when a dialog finishes (i.e. once its last group of 3 lines is finished)

event_appear(): called when an instance of the enemy controlled by this script has just been created on the map

event_enabled(): called when the enemy has just been enabled

event_disabled(): called when the enemy has just been disabled

event_restart(): Called when the enemy is restarting its movement because something happended (for example the enemy has just been created, or it was just hurt). If your enemy moves, it is usual to create its movement in this function.

event_pre_display(): called just before the enemy is displayed (you may display additional things below the enemy)

event_post_display(): called just after the enemy is displayed (you may display additional things above the enemy)

event_position_changed(x, y): called when the enemy has moved

event_layer_changed(layer): called when the layer of the enemy has changed

event_obstacle_reached(): called when the movement of the enemy was stopped because of an obstacle.

event_movement_changed(movement): called when something changes in the movement of the enemy

event_movement_finished(movement): called when the movement of the enemy is finished

event_sprite_frame_changed(sprite, animation, frame): called when the current frame of a sprite of the enemy has changed

event_sprite_animation_finished(sprite, animation): called when the animation of a sprite of the enemy has just finished

event_collision_enemy(other_name, other_sprite, my_sprite): called when the enemy detects a collision with another enemy

event_custom_attack_received(attack, sprite): Called when the enemy receives an attack with a custom effect. attack can be "sword", "thrown_item", "explosion", "arrow", "hookshot", "boomerang", or "fire". You have to define what happens, for example hurting the enemy, making a special reaction, etc. If the attacks comes from a pixel-precise collision test, the sprite that receives the attack is passed as a parameter.

event_hurt(attack, life_lost): Called when the enemy is hurt. attack can be "sword", "thrown_item", "explosion", "arrow", "hookshot", "boomerang", or "fire". This function is called after removing life_lost life points.

event_dead(): called when the enemy is killed and has finished to die

event_immobilized(): called when the enemy is immobilized

event_message_received(src_enemy, message): Called when the enemy receives a string message from another enemy.