- Generated on Sat Aug 10 2019 09:47:58 for Solarus quests by
1.8.13
|
Solarus quests
1.6
Quest maker's reference
|
Maps are areas where the game takes place. They may be rooms, houses, entire dungeon floors, parts of the outside world or any place. The active map contains many objects called map entities (or just "entities" to be short). Map entities are everything that has a position on the map, including the hero, the tiles, the enemies, the pickable treasures and even the camera. See the entity API for more details.
A map has a rectangular size in pixels. The width and the height are always multiples of 8 pixels, and most map entities usually stay aligned on a grid of squares of 8x8 pixels (except when they are moving).
Thus, each entity has some coordinates X,Y on the map. But its position is also defined by a third value: its layer. The map has a number of distinct layers that are stacked. Each layer has its own list of entities. Layers are identified by a number. There is always a layer 0, and maps can add additional layers above or below 0.
Layers allow to implement maps with multi-level content, like a bridge between two higher platforms. The hero (as well as enemies and any other map entity) is then able to walk either above or under the bridge, depending on his layer. Entities like stairs and jumpers can change the layer of the hero automatically, but you can also do that from your Lua scripts.
The graphic skin of a map is called a tileset. The tileset defines the small patterns used to draw tiles and also some other entities that may depend on the skin. For example, you can have a forest tileset, a castle tileset, etc. Tilesets have no special size limitation. It is possible to use multiple tilesets in the same map.
A map can contain many types of entities. Map entities can be either declared in the map data file or created dynamically. Thus, a map with id XXXX is managed by two distinct files:
maps/XXXX.dat are declared all entities that initially compose your map (most importantly: the tiles). You normally don't need to edit this file by hand: you can use the quest editor (but if you want to, here is the syntax)."maps/XXXX.lua" (which is optional), you define the dynamic behavior of your map, using the features of the map Lua type described on this page (and the rest of the Solarus API will also be very useful).When the player enters a map, the engine first creates the entities declared in the map data file maps/XXXX.dat, and then it runs your script "maps/XXXX.lua". The Lua map object is passed as parameter of your script (remember that any Lua script is implicitly a function and can have parameters). Use the Lua notation "..." to get this parameter and store it into a regular variable.
Here is a basic example of script for a map that does nothing special except playing a special music and showing an evil welcome dialog when the hero enters it.
-- First, we put the parameter into a variable called "map".
-- (In Lua, the notation "..." refers to the parameter(s) of the script.)
local map = ...
local game = map:get_game()
-- Event called when the player enters the map, at initialization time.
function map:on_started()
-- Play an evil music.
sol.audio.play_music("evil")
end
-- Event called when the player takes control, after the opening transition.
function map:on_opening_transition_finished()
-- Show an evil welcome dialog.
game:start_dialog("welcome_to_darkness")
end
In practice, many maps have short scripts like this or even no script at all. Sometimes, everything that you define in the data file (with the help of the quest editor) is enough. You need a script when there is something dynamic to program on your map: opening a door when a pressure plate is pressed, making a treasure chest appear when some enemies are killed, showing a dialog with an NPC that depends on whether the player has accomplished a particular action before, etc.
At any moment, during the game, only one map is active: the one drawn on the game screen. That map is also the one where the hero is currently located. Only the active map has its entities living in it. Other maps are not loaded. If the player leaves the map and comes back later, your Lua map object will be a new one the second time. Your entities will be reloaded as specified in the map data file and your map script will be executed again.
If you want some data or behavior to persist when the player comes back, like the position of an NPC or whether a puzzle was solved, you can store the information into the savegame. Alternatively, if you don't want these data to be saved, but you want to remember then during the current game session, you can store the information as a field of the game object. The game object persists until the player stops playing and comes back to the title screen or restarts the game.
Like other essential Solarus types (including game, items and map entities), a fundamental property of maps is that even if they are userdata, they can also be used like Lua tables.
This property is actually what allows you to define events on your map. But you can store any data in your map object, including new functions specific to your particular map. Here is an example that uses this feature:
-- Example of a map with 3 switches to activate in the correct order.
-- We assume that 3 switches exist with names "puzzle_switch_1", "puzzle_switch_2" and "puzzle_switch_3".
local map = ...
local game = map:get_game()
function map:on_started()
map.next_switch_index = 1
-- Equivalent to: map["next_switch_index"] = 1
end
-- Called when the player walks on the switch named "puzzle_switch_1".
function puzzle_switch_1:on_activated()
-- Check that puzzle_switch_1 is the correct switch to activate.
map:check_switch(self)
end
function puzzle_switch_2:on_activated()
map:check_switch(self)
end
function puzzle_switch_3:on_activated()
map:check_switch(self)
end
function map:check_switch(switch)
if switch:get_name() == "puzzle_switch_" .. map.next_switch_index then
-- Okay so far.
map.next_switch_index = map.next_switch_index + 1
if map.next_switch_index > 3 then
-- Finished!
sol.audio.play_sound("secret")
game:start_dialog("congratulations")
end
else
-- Wrong switch: reset the puzzle.
sol.audio.play_sound("wrong")
puzzle_switch_1:set_activated(false)
puzzle_switch_2:set_activated(false)
puzzle_switch_3:set_activated(false)
map.next_switch_index = 1
end
end
In this example, you see that we add three values to the map object, like if it was a table: next_switch_index (a number), on_started (a function) and check_switch (a function). Actually, we also use this feature on the three switches as well: we add a value on_activated on them.
puzzle_switch_1, puzzle_switch_2 and puzzle_switch_3 without declaring them. There is a mechanism that makes all named map entities directly accessible in the environment of the map script. See map:get_entity() for more details.But this example has some issues. The three switches are managed by duplicated code. This is error-prone because one day, we will probably want to make a similar puzzle with 50 entities instead of just 3. To make your map easier to maintain, the following and equivalent version is much more preferred:
local map = ...
local game = map:get_game()
function map:on_started()
map.next_switch_index = 1
map.nb_switches = map:get_entities_count("puzzle_switch_")
end
local function puzzle_switch_activated(switch)
map:check_switch(switch)
end
-- Define the same on_activated() method for all entities whose name
-- starts with "puzzle_switch_".
for switch in map:get_entities("puzzle_switch_") do
switch.on_activated = puzzle_switch_activated
end
function map:check_switch(switch)
if switch:get_name() == "puzzle_switch_" .. map.next_switch_index then
-- Okay so far.
map.next_switch_index = map.next_switch_index + 1
if map.next_switch_index > map.nb_switches then
-- Finished!
sol.audio.play_sound("secret")
game:start_dialog("congratulations")
end
else
-- Wrong switch: reset the puzzle.
sol.audio.play_sound("wrong")
for s in map:get_entities("puzzle_switch_") do
s:set_activated(false)
end
map.next_switch_index = 1
end
end
This improved version is more evolutive: it does not even hardcode the number of switches in the puzzle. Thus, if you add a switch called "puzzle_switch_4" from the quest editor one day, you won't even have to change your scripts: it will directly take it into account in the puzzle.
Returns the id of this map.
Returns the current game.
Returns the world name that was set on this map.
The world name is an optional property defined in the map data file. Worlds allow to group maps together. The world can be any arbitrary name. Maps that have the same world name are considered to be part of the same environment. For example, your map can be in a world named "outside_world", "dungeon_1" or "some_scary_cave". A map that has no world is always considered to be alone in its own environment.
The world property is used to decide when to set the starting location of the player (the place where he starts when loading his savegame). By default, the starting location is automatically set by the engine when the world changes (not when the map changes). This can be changed by defining the "Save starting location" property of destinations, from the quest editor or from a script (with destination:set_starting_location_mode()).
Some other features may also rely on the world property, like the state of crystal blocks. Their state persists between all maps of the current world and is reset when entering a map whose world is different.
nil means no world.Changes the world of this map.
The world property remains until the map is destroyed: If you reload the same map again later, the world is reset to the one defined in the map data file.
world (string): The new world name to set, or nil to set no world.Returns the floor of the current map if any.
The floor is an optional property defined in the map data file.
The engine does not do anything particular with this floor property. But you can use it in scripts, for example to show the current floor on the HUD when it changes or to make a minimap menu.
0 is the first floor, 1 is the second floor, -1 is the first basement floor, etc. nil means that this map is not part of a floor system.Changes the floor of this map.
The floor property remains until the map is destroyed: If you reload the same map again later, the floor is reset to the one defined in the map data file.
floor (number): The new floor number to set, or nil to set no floor.Returns the index of the lowest layer of this map.
Returns the index of the highest layer of this map.
Returns the size of this map in pixels.
Returns the x,y location of this map in its world.
The engine uses this information to implement scrolling between two adjacent maps.
For example, you can also use this property in scripts if you want to show the position of the hero on the minimap menu of your outside world. Indeed, your outside world is probably not a single map, but it is usually composed of several adjacent maps.
Returns the name of the tileset of the current map.
Changes the tileset of the current map.
It is your responsability to make sure that the new tileset is be compatible with the previous one: every tile of the previous tileset must exist in the new one and have the exact same properties, and only the images can differ.
tileset_id (string): Id of the new tileset to set.Returns the name of the music associated to this map.
This is the music to play when the map starts, as specified in the map file. It may be different from the music currently being played. To get the music currently being played, see sol.audio.get_music().
musics directory and without extension. It can also be the special value "same" if the map specifies to keep the music unchanged, or nil if the map specifies to play no music.Returns the camera entity of the map.
Returns the kind of ground (terrain) of a point.
The ground is defined by tiles (and other entities that may change it like dynamic tiles) that overlap this point.
x (number): X coordinate of a point of the map.y (number): Y coordinate of a point of the map.layer (number): The layer, between map:get_min_layer() and map:get_max_layer().ground property of the tileset file: "empty", "traversable", "wall", "low_wall", "wall_top_right", "wall_top_left", "wall_bottom_left", "wall_bottom_right", "wall_top_right_water", "wall_top_left_water", "wall_bottom_left_water", "wall_bottom_right_water", "deep_water", "shallow_water", "grass", "hole", "ice", "ladder", "prickles" or "lava".Draws a drawable object (surface, text surface or sprite) on the camera at the given map coordinates.
This function can be used as an alternative to drawable:draw() in order to draw the object relative to the map (instead of relative to the screen).
If the object to draw is a sprite, its origin point will be displayed at the given location, relative to the the upper left corner of the map.
This function should only be called during the drawing phase of the map, for example from map:on_draw() or from custom_entity:on_post_draw().
drawable (drawable): The visual object to draw on the map.x (number): X coordinate of where to draw the object, in map coordinates.y (number): Y coordinate of where to draw the object, in map coordinates.Draws a sprite on the screen at the given map coordinates.
Use map:draw_visual() instead.
Returns the configuration of crystal blocks.
false initially (orange blocks lowered), true otherwise (blue blocks lowered).Sets the configuration of crystal blocks.
This state persists accross maps of the same world. It is reset when the world changes and when the savegame is reloaded.
state (boolean): false to set the initial configuration (orange blocks lowered), true to the modified one (blue blocks lowered).Inverts the configuration of crystal blocks.
map:set_crystal_state(not map:get_crystal_state()).Opens the doors whose name starts with the specified prefix, enables or disables relative dynamic tiles accordingly and plays the "door_open" sound.
Opening a door may be more complex than just modifying a single door entity. Indeed, there is often a corresponding door is the adjacent room that you also want to open (that corresponding door is another entity). Name both doors with the same prefix, and you can use this function to open both of them.
Furthermore, you sometimes want dynamic tiles to be shown or hidden depending on the state of a door. When a door is open, all dynamic tiles whose prefix is the door's name followed by _open or _closed are automatically enabled or disabled, respectively.
prefix (string): Prefix of the name of doors to open.Closes the doors whose name starts with the specified prefix, enables or disables relative dynamic tiles accordingly and plays the "door_closed" sound.
Closing a door may be more complex than just modifying a single door entity. Indeed, there is often a corresponding door is the adjacent room that you also want to open (that corresponding door is another entity). Name both doors with the same prefix, and you can use this function to close both of them.
Furthermore, you sometimes want dynamic tiles to be shown or hidden depending on the state of a door. When a door is closed, all dynamic tiles whose prefix is the door's name followed by _open or _closed are automatically disabled or enabled, respectively.
prefix (string): Prefix of the name of doors to close.Like map:open_doors() or map:close_doors(), but does not play any sound or any sprite animation.
This function is intended to be called when you don't want the player to notice the change, typically when your map starts (i.e. from the map:on_started() event).
prefix (string): Prefix of the name of doors to set.open (boolean, optional): true to open the doors, false to close them (no value means true).Returns the map entity with the specified name if it exists on this map. Entity names are unique (two entities cannot exist on the map with the same name at the same time). The name is optional: some entities may have no name. In this case, you cannot access them from this function.
As a convenient feature, map entities can also be accessed directly through the environment of the map script. In other words, you can just write bob:get_position() as an equivalent to map:get_entity("bob"):get_position().
name (string): Name of the map entity to get.nil if there exists no entity with this name on the map.__index metamethod). Entities are imported to the Lua side only when your script requests them. If you have thousands of named entities in your map, you won't have thousands of useless objects living in Lua. Only the ones your script tries to access are imported.Returns whether there currently exists a map entity with the specified name on the map.
name (string): Name of the map entity to check.true if such an entity exists.map:get_entity(name) ~= nil (but a bit lighter because it avoids to export the entity to Lua).Returns an iterator to all map entities whose name has the specified prefix.
The typical usage of this function is:
for entity in map:get_entities("your_prefix") do
-- some code related to the entity
end
prefix (string, optional): Prefix of the entities to get. No value means all entities (equivalent to an empty prefix).Returns the number of map entities having the specified prefix.
prefix (string): Prefix of the entities to count.Returns whether there exists at least one map entity having the specified prefix.
This function can be used for example to checker whether a group of enemies is dead.
prefix (string): Prefix of the entities to check.true if at least one entity with this prefix exists on the map.map:get_entities_count(prefix) > 0 but faster when there are a lot of entities (because it stops searching as soon as there is a match).Returns an iterator to all map entities of the given type on the map.
The typical usage of this function is:
for entity in map:get_entities_by_type(type) do -- some code related to the entity end
type (string): Name of an entity type. See entity:get_type() for the possible values.Returns an iterator to all map entities whose maximum bounding box intersects the given rectangle. The maximum bounding box is the union of the entity's own bounding box and of the bounding boxes from its sprites.
The typical usage of this function is:
for entity in map:get_entities_in_rectangle(x, y, width, height) do -- some code related to the entity end
x (number): X coordinate of the rectangle's upper-left corner.y (number): Y coordinate of the rectangle's upper-left corner.width (number): Width of the rectangle.height (number): Height of the rectangle.Returns an iterator to all map entities that are in a region. Regions of the map are defined by the position of separators and map limits. The region of an entity is the one of its center point.
Regions should be rectangular. Non-convex regions, for example with an "L" shape, are not supported by this function.
The typical usage of this function is:
for entity in map:get_entities_in_region(my_entity) do -- some code related to the entity end
To get entities in the same region as a point:
x (number): X coordinate of the region to get.y (number): Y coordinate of the region to get.To get entities in the same region as another entity:
entity (entity): An entity.Returns the hero.
map:get_entity("hero") but shorter to write. This function is provided for convenience as getting the hero is often needed.Enables or disables all map entities having the specified prefix.
Disabled entities are not displayed and are not updated. Therefore, they don't move and their collisions are no longer detected. But they still exist and can be enabled back later.
prefix (string): Prefix of the entities to change.enable (boolean, optional): true to enable them, false to disable them. No value means true.Removes and destroys all map entities having the specified prefix.
Once an entity is removed, it is destroyed and it no longer exists on the map. A good practice is to avoid keeping references to destroyed entities in your scripts so that they can be garbage-collected by Lua.
prefix (string): Prefix of the entities to remove from the map.Creates an entity of type destination on the map.
properties (table): A table that describles all properties of the entity to create. Its key-value pairs must be:name (string, optional): Name identifying the entity or nil. If the name is already used by another entity, a suffix (of the form "_2", "_3", etc.) will be automatically appended to keep entity names unique.layer (number): The layer, between map:get_min_layer() and map:get_max_layer().x (number): X coordinate on the map.y (number): Y coordinate on the map.direction (number): Direction that the hero should take when arriving on the destination, between 0 (East) and 3 (South), or -1 to keep his direction unchanged.sprite (string, optional): Id of the animation set of a sprite to create for the destination. No value means no sprite (the destination will then be invisible).save_location (string, optional): Whether to update the starting location of the player when arriving to this destination. If yes, when the player restarts his game, he will restart at this destination. Must be one of:"when_world_changes" (default): Updates the starting location if the current world has just changed when arriving to this destination."yes": Updates the starting location."no": Does not update the starting location.default (boolean, optional): Sets this destination as the default one when teletransporting the hero to this map without destination specified. No value means false. Only one destination can be the default one on a map. If no default destination is set, then the first one declared becomes the default one.enabled_at_start (boolean, optional): Whether the entity should be initially enabled. The default value is true.properties (table, optional): Additional user-defined properties. See entity:set_properties() for the specification.Creates an entity of type teletransporter on the map.
properties (table): A table that describles all properties of the entity to create. Its key-value pairs must be:name (string, optional): Name identifying the entity or nil. If the name is already used by another entity, a suffix (of the form "_2", "_3", etc.) will be automatically appended to keep entity names unique.layer (number): The layer, between map:get_min_layer() and map:get_max_layer().x (number): X coordinate on the map.y (number): Y coordinate on the map.width (number): Width of the entity in pixels.height (number): Height of the entity in pixels.sprite (string, optional): Id of the animation set of a sprite to create for the teletransporter. No value means no sprite (the teletransporter will then be invisible).sound (string, optional): Sound to play when the hero uses the teletransporter. No value means no sound.transition (string, optional): Style of transition to play when the hero uses the teletransporter. Must be one of:"immediate": No transition."fade": Fade-out and fade-in effect."scrolling": Scrolling between maps. The default value is "fade".destination_map (string): Id of the map to transport to (can be the id of the current map).destination (string, optional): Location on the destination map. Can be the name of a destination entity, the special value "_same" to keep the hero's coordinates, or the special value "_side" to place on hero on the corresponding side of an adjacent map (normally used with the scrolling transition style). No value means the default destination entity of the map.enabled_at_start (boolean, optional): Whether the entity should be initially enabled. The default value is true.properties (table, optional): Additional user-defined properties. See entity:set_properties() for the specification.Creates an entity of type pickable treasure on the map.
properties (table): A table that describles all properties of the entity to create. Its key-value pairs must be:name (string, optional): Name identifying the entity or nil. If the name is already used by another entity, a suffix (of the form "_2", "_3", etc.) will be automatically appended to keep entity names unique.layer (number): The layer, between map:get_min_layer() and map:get_max_layer().x (number): X coordinate on the map.y (number): Y coordinate on the map.treasure_name (string, optional): Kind of treasure to create (the name of an equipment item). If this value is not set, or corresponds to a non-obtainable item, then no entity is created and nil is returned.treasure_variant (number, optional): Variant of the treasure (because some equipment items may have several variants). The default value is 1 (the first variant).treasure_savegame_variable (string, optional): Name of the boolean value that stores in the savegame whether this pickable treasure was found. No value means that the treasure is not saved. If the treasure is saved and the player already has it, then no entity is be created and nil is returned.enabled_at_start (boolean, optional): Whether the entity should be initially enabled. The default value is true.properties (table, optional): Additional user-defined properties. See entity:set_properties() for the specification.nil if the item is not set, not obtainable, or if the pickable treasure is already found (for a saved one).Creates an entity of type destructible object on the map.
properties (table): A table that describes all properties of the entity to create. Its key-value pairs must be:name (string, optional): Name identifying the entity or nil. If the name is already used by another entity, a suffix (of the form "_2", "_3", etc.) will be automatically appended to keep entity names unique.layer (number): The layer, between map:get_min_layer() and map:get_max_layer().x (number): X coordinate on the map.y (number): Y coordinate on the map.treasure_name (string, optional): Kind of pickable treasure to hide in the destructible object (the name of an equipment item). If this value is not set, then no treasure is placed in the destructible object. If the treasure is not obtainable when the object is destroyed, no pickable treasure is created.treasure_variant (number, optional): Variant of the treasure if any (because some equipment items may have several variants). The default value is 1 (the first variant).treasure_savegame_variable (string, optional): Name of the boolean value that stores in the savegame whether the pickable treasure hidden in the destructible object was found. No value means that the treasure (if any) is not saved. If the treasure is saved and the player already has it, then no treasure is put in the destructible object.sprite (string): Name of the animation set of a sprite to create for the destructible object.destruction_sound (string, optional): Sound to play when the destructible object is cut or broken after being thrown. No value means no sound.weight (number, optional): Level of "lift" ability required to lift the object. 0 allows the player to lift the object unconditionally. The special value -1 means that the object can never be lifted. The default value is 0.can_be_cut (boolean, optional): Whether the hero can cut the object with the sword. No value means false.can_explode (boolean, optional): Whether the object should explode when it is cut, hit by a weapon and after a delay when the hero lifts it. The default value is false.can_regenerate (boolean, optional): Whether the object should automatically regenerate after a delay when it is destroyed. The default value is false.damage_on_enemies (number, optional): Number of life points to remove from an enemy that gets hit by this object after the hero throws it. If the value is 0, enemies will ignore the object. The default value is 1.ground (string, optional): Ground defined by this entity. The ground is usually "wall", but you may set "traversable" to make the object traversable, or for example "grass" to make it traversable too but with an additional grass sprite below the hero. The default value is "wall".enabled_at_start (boolean, optional): Whether the entity should be initially enabled. The default value is true.properties (table, optional): Additional user-defined properties. See entity:set_properties() for the specification.Creates an entity of type treasure chest on the map.
properties (table): A table that describes all properties of the entity to create. Its key-value pairs must be:name (string, optional): Name identifying the entity or nil. If the name is already used by another entity, a suffix (of the form "_2", "_3", etc.) will be automatically appended to keep entity names unique.layer (number): The layer, between map:get_min_layer() and map:get_max_layer().x (number): X coordinate on the map.y (number): Y coordinate on the map.treasure_name (string, optional): Kind of treasure to place in the chest (the name of an equipment item). If this value is not set, then the chest will be empty. If the treasure is not obtainable when the hero opens the chest, it becomes empty.treasure_variant (number, optional): Variant of the treasure (because some equipment items may have several variants). The default value is 1 (the first variant).treasure_savegame_variable (string, optional): Name of the boolean value that stores in the savegame whether this chest is open. No value means that the state of the treasure is not saved. If the treasure is saved and the player already has it, then no treasure is placed in the chest (the chest will appear open).sprite (string): Name of the animation set of the sprite to create for the chest. The sprite must have animations "open" and "closed".opening_method (string, optional): Specifies the permissions for the hero to open the chest. Must be one of:"interaction" (default): Can be opened by pressing the action command in front of it."interaction_if_savegame_variable": Can be opened by pressing the action command in front of it, provided that a specific savegame variable is set."interaction_if_item": Can be opened by pressing the action command in front of it, provided that the player has a specific equipment item.opening_condition (string, optional): The condition required to open the chest. Only for opening methods "interaction_if_savegame_variable" and "interaction_if_item"."interaction_if_savegame_variable", it must be the name of a savegame variable. The hero will be allowed to open the chest if this saved value is either true, an integer greater than zero or a non-empty string."interaction_if_item", it must be the name of an equipment item. The hero will be allowed to open the chest if he has that item and, for items with an amount, if the amount is greater than zero."interaction"), this setting has no effect.opening_condition_consumed (boolean, optional): Whether opening the chest should consume the savegame variable or the equipment item that was required. The default setting is false. If you set it to true, the following rules are applied when the hero successfully opens the chest:"interaction_if_savegame_variable", the savegame variable that was required is reset to false, 0 or "" (depending on its type)."interaction_if_item", the equipment item that was required is removed. This means setting its possessed variant to 0, unless it has an associated amount: in this case, the amount is decremented.cannot_open_dialog (string, optional): Id of the dialog to show if the hero fails to open the chest. If you don't set this value, no dialog is shown.enabled_at_start (boolean, optional): Whether the entity should be initially enabled. The default value is true.properties (table, optional): Additional user-defined properties. See entity:set_properties() for the specification.Creates an entity of type jumper on the map.
properties (table): A table that describes all properties of the entity to create. Its key-value pairs must be:name (string, optional): Name identifying the entity or nil. If the name is already used by another entity, a suffix (of the form "_2", "_3", etc.) will be automatically appended to keep entity names unique.layer (number): The layer, between map:get_min_layer() and map:get_max_layer().x (number): X coordinate on the map.y (number): Y coordinate on the map.width (number): Width of the entity in pixels.height (number): Height of the entity in pixels.direction (number): Direction of the jump, between 0 (East) and 7 (South-East). If the direction is horizontal, the width must be 8 pixels. If the direction is vertical, the height must be 8 pixels. If the direction is diagonal, the size must be square.jump_length (number): Length of the baseline of the jump in pixels (see the jump movement page for details).enabled_at_start (boolean, optional): Whether the entity should be initially enabled. The default value is true.properties (table, optional): Additional user-defined properties. See entity:set_properties() for the specification.Creates an entity of type enemy on the map.
properties (table): A table that describes all properties of the entity to create. Its key-value pairs must be:name (string, optional): Name identifying the entity or nil. If the name is already used by another entity, a suffix (of the form "_2", "_3", etc.) will be automatically appended to keep entity names unique.layer (number): The layer, between map:get_min_layer() and map:get_max_layer().x (number): X coordinate on the map.y (number): Y coordinate on the map.direction (number): Initial direction of the enemy, between 0 (East) and 3 (South).breed (string): Model of enemy to create.savegame_variable (string, optional): Name of the boolean value that stores in the savegame whether this enemy is dead. No value means that the enemy is not saved. If the enemy is saved and was already killed, then no enemy is created. Instead, its pickable treasure is created if it is a saved one.treasure_name (string, optional): Kind of pickable treasure to drop when the enemy is killed (the name of an equipment item). If this value is not set, then the enemy won't drop anything. If the treasure is not obtainable when the enemy is killed, then nothing is dropped either.treasure_variant (number, optional): Variant of the treasure (because some equipment items may have several variants). The default value is 1 (the first variant).treasure_savegame_variable (string, optional): Name of the boolean value that stores in the savegame whether the pickable treasure of this enemy was obtained. No value means that the state of the treasure is not saved. If the treasure is saved and the player already has it, then the enemy won't drop anything.enabled_at_start (boolean, optional): Whether the entity should be initially enabled. The default value is true.properties (table, optional): Additional user-defined properties. See entity:set_properties() for the specification.nil is returned.Creates an entity of type non-playing character (NPC) on the map.
properties (table): A table that describes all properties of the entity to create. Its key-value pairs must be:name (string, optional): Name identifying the entity or nil. If the name is already used by another entity, a suffix (of the form "_2", "_3", etc.) will be automatically appended to keep entity names unique.layer (number): The layer, between map:get_min_layer() and map:get_max_layer().x (number): X coordinate on the map.y (number): Y coordinate on the map.direction (number): Initial direction of the NPC's sprite, between 0 (East) and 3 (South).subtype (number): Kind of NPC to create: 1 for a usual NPC who the player can talk to, 0 for a generalized NPC (not necessarily a person). See the NPC documentation for more details.sprite (string, optional): Name of the animation set of a sprite to create for the NPC. No value means no sprite (the NPC will then be invisible).behavior (string, optional): What to do when there is an interaction with the NPC."dialog#XXXX": Starts the dialog with id XXXX when the player talks to this NPC."map" (default): Forwards events to the map script (for example, calls the on_interaction() event of the NPC)."item#XXXX": Forwards events to an equipment item script (for example, calls the on_interaction() event of the equipment item with id XXXX).enabled_at_start (boolean, optional): Whether the entity should be initially enabled. The default value is true.properties (table, optional): Additional user-defined properties. See entity:set_properties() for the specification.Creates an entity of type block on the map.
properties (table): A table that describes all properties of the entity to create. Its key-value pairs must be:name (string, optional): Name identifying the entity or nil. If the name is already used by another entity, a suffix (of the form "_2", "_3", etc.) will be automatically appended to keep entity names unique.layer (number): The layer, between map:get_min_layer() and map:get_max_layer().x (number): X coordinate on the map.y (number): Y coordinate on the map.direction (number, optional): The only direction where the block can be moved, between 0 (East) and 3 (South). nil means no restriction and allows the block to be moved in any of the four main directions. The default value is nil.sprite (string): Name of the animation set of a sprite to create for the block.pushable (boolean): true to allow the block to be pushed.pullable (boolean): true to allow the block to be pulled.max_moves (number, optional): How many times the block can be moved (nil means unlimited). The default value is nil.maximum_moves (number, optional, deprecated): Like max_moves, but for historical reasons, only supports 0, 1 or the special value 2 to mean infinite. New scripts should only use max_moves. It is an error to set both values.enabled_at_start (boolean, optional): Whether the entity should be initially enabled. The default value is true.properties (table, optional): Additional user-defined properties. See entity:set_properties() for the specification.Creates an entity of type dynamic tile on the map.
properties (table): A table that describes all properties of the entity to create. Its key-value pairs must be:name (string, optional): Name identifying the entity or nil. If the name is already used by another entity, a suffix (of the form "_2", "_3", etc.) will be automatically appended to keep entity names unique.layer (number): The layer, between map:get_min_layer() and map:get_max_layer().x (number): X coordinate of the top-left corner of the dynamic tile on the map.y (number): Y coordinate of the top-left corner of the dynamic tile on the map.width (number): Width of the dynamic tile in pixels. The tile pattern will be repeated horizontally to fit to this width.height (number): Height of the entity in pixels. The tile pattern will be repeated vertically to fit to this height.pattern (string): Id of the tile pattern to use from the tileset.enabled_at_start (boolean, optional): Whether the entity should be initially enabled. The default value is true.properties (table, optional): Additional user-defined properties. See entity:set_properties() for the specification.Creates an entity of type switch on the map.
properties (table): A table that describes all properties of the entity to create. Its key-value pairs must be:name (string, optional): Name identifying the entity or nil. If the name is already used by another entity, a suffix (of the form "_2", "_3", etc.) will be automatically appended to keep entity names unique.layer (number): The layer, between map:get_min_layer() and map:get_max_layer().x (number): X coordinate on the map.y (number): Y coordinate on the map.subtype (string): Kind of switch to create:"walkable": A traversable pressure plate that gets activated when the hero walks on it."solid": A non-traversable, solid switch that can be activated in various conditions: by the sword, by an explosion or by a projectile (a thrown object, an arrow, the boomerang or the hookshot)."arrow_target" A switch that can be only activated by shooting an arrow on it.sprite (string): Name of the animation set of a sprite to create for the switch. The animation set must at least contain animations "activated" and "inactivated". No value means no sprite.sound (string, optional): Sound to play when the switch is activated. No value means no sound.inactivate_when_leaving (boolean): If true, the switch becomes inactivated when the hero or the block leaves it (only for a walkable switch).enabled_at_start (boolean, optional): Whether the entity should be initially enabled. The default value is true.properties (table, optional): Additional user-defined properties. See entity:set_properties() for the specification.Creates an entity of type wall on the map.
properties (table): A table that describes all properties of the entity to create. Its key-value pairs must be:name (string, optional): Name identifying the entity or nil. If the name is already used by another entity, a suffix (of the form "_2", "_3", etc.) will be automatically appended to keep entity names unique.layer (number): The layer, between map:get_min_layer() and map:get_max_layer().x (number): X coordinate on the map.y (number): Y coordinate on the map.width (number): Width of the entity in pixels.height (number): Height of the entity in pixels.stops_hero (boolean, optional): true to make the wall stop the hero. No value means false.stops_npcs (boolean, optional): true to make the wall stop non-playing characters. No value means false.stops_enemies (boolean, optional): true to make the wall stop enemies. No value means false.stops_blocks (boolean, optional): true to make the wall stop blocks. No value means false.stops_projectiles (boolean, optional): true to make the wall stop projectiles: thrown objects, arrows, the hookshot and the boomerang. No value means false.enabled_at_start (boolean, optional): Whether the entity should be initially enabled. The default value is true.properties (table, optional): Additional user-defined properties. See entity:set_properties() for the specification.Creates an entity of type sensor on the map.
properties (table): A table that describes all properties of the entity to create. Its key-value pairs must be:name (string, optional): Name identifying the entity or nil. If the name is already used by another entity, a suffix (of the form "_2", "_3", etc.) will be automatically appended to keep entity names unique.layer (number): The layer, between map:get_min_layer() and map:get_max_layer().x (number): X coordinate on the map.y (number): Y coordinate on the map.width (number): Width of the entity in pixels.height (number): Height of the entity in pixels.enabled_at_start (boolean, optional): Whether the entity should be initially enabled. The default value is true.properties (table, optional): Additional user-defined properties. See entity:set_properties() for the specification.Creates an entity of type crystal on the map.
properties (table): A table that describes all properties of the entity to create. Its key-value pairs must be:name (string, optional): Name identifying the entity or nil. If the name is already used by another entity, a suffix (of the form "_2", "_3", etc.) will be automatically appended to keep entity names unique.layer (number): The layer, between map:get_min_layer() and map:get_max_layer().x (number): X coordinate on the map.y (number): Y coordinate on the map.properties (table, optional): Additional user-defined properties. See entity:set_properties() for the specification.Creates an entity of type crystal block on the map.
properties (table): A table that describes all properties of the entity to create. Its key-value pairs must be:name (string, optional): Name identifying the entity or nil. If the name is already used by another entity, a suffix (of the form "_2", "_3", etc.) will be automatically appended to keep entity names unique.layer (number): The layer, between map:get_min_layer() and map:get_max_layer().x (number): X coordinate on the map.y (number): Y coordinate on the map.width (number): Width of the entity in pixels.height (number): Height of the entity in pixels.subtype (number): Kind of crystal block to create: 0 for a block initially lowered (orange), 1 for a block initially raised (blue).enabled_at_start (boolean, optional): Whether the entity should be initially enabled. The default value is true.properties (table, optional): Additional user-defined properties. See entity:set_properties() for the specification.Creates an entity of type shop treasure on the map.
properties (table): A table that describes all properties of the entity to create. Its key-value pairs must be:name (string, optional): Name identifying the entity or nil. If the name is already used by another entity, a suffix (of the form "_2", "_3", etc.) will be automatically appended to keep entity names unique.layer (number): The layer, between map:get_min_layer() and map:get_max_layer().x (number): X coordinate on the map.y (number): Y coordinate on the map.price (number): Money amount required to buy the treasure.font (string, optional): Id of the font to use to display to price. The default value is the first one in alphabetical order.dialog (string): Id of the dialog to show when the hero asks for information about the treasure.treasure_name (string): Kind of treasure to sell (the name of an equipment item). If this value or corresponds to a non-obtainable item, then the shop treasure is not created and nil is returned.treasure_variant (number, optional): Variant of the treasure (because some equipment items may have several variants). The default value is 1 (the first variant).treasure_savegame_variable (string, optional): Name of the boolean value that stores in the savegame whether the player has purchased this treasure. No value means that the state of the treasure is not saved. If the treasure is saved and the player already has it, then the shop treasure is not created and nil is returned.enabled_at_start (boolean, optional): Whether the entity should be initially enabled. The default value is true.properties (table, optional): Additional user-defined properties. See entity:set_properties() for the specification.nil if the item is not obtainable, or if the shop treasure was already purchased (for a saved one).Creates an entity of type stream on the map.
properties (table): A table that describes all properties of the entity to create. Its key-value pairs must be:name (string, optional): Name identifying the entity or nil. If the name is already used by another entity, a suffix (of the form "_2", "_3", etc.) will be automatically appended to keep entity names unique.layer (number): The layer, between map:get_min_layer() and map:get_max_layer().x (number): X coordinate on the map.y (number): Y coordinate on the map.direction (number): Direction where the stream moves the hero, between 0 (East) and 7 (South-East).sprite (string, optional): Id of the animation set of a sprite to create for the stream. No value means no sprite (the stream will then be invisible).speed (number, optional): Speed of the movement applied to the hero by the stream, in pixels per second. The default value is 64.allow_movement (boolean, optional): Whether the player can still move the hero when he is on the stream. The default value is true.allow_attack (boolean, optional): Whether the player can use the sword when he is on the stream. The default value is true.allow_item (boolean, optional): Whether the player can use equipment items when he is on the stream. The default value is true.enabled_at_start (boolean, optional): Whether the entity should be initially enabled. The default value is true.properties (table, optional): Additional user-defined properties. See entity:set_properties() for the specification.Creates an entity of type door on the map.
properties (table): A table that describes all properties of the entity to create. Its key-value pairs must be:name (string, optional): Name identifying the entity or nil. If the name is already used by another entity, a suffix (of the form "_2", "_3", etc.) will be automatically appended to keep entity names unique.layer (number): The layer, between map:get_min_layer() and map:get_max_layer().x (number): X coordinate on the map.y (number): Y coordinate on the map.direction (number): Direction of the door, between 0 (East of the room) and 3 (South of the room).sprite (string): Name of the animation set of the sprite to create for the door. The sprite must have an animation "closed", that will be shown while the door is closed. When the door is open, no sprite is displayed. Optionally, the sprite can also have animations "opening" and "closing", that will be shown (if they exist) while the door is being opened or closed, respectively. If they don't exist, the door will open close instantly.savegame_variable (string, optional): Name of the boolean value that stores in the savegame whether this door is open. No value means that the door is not saved. If the door is saved as open, then it appears open.opening_method (string, optional): How the door is supposed to be opened by the player. Must be one of:"none" (default): Cannot be opened by the player. You can only open it from Lua."interaction": Can be opened by pressing the action command in front of it."interaction_if_savegame_variable": Can be opened by pressing the action command in front of it, provided that a specific savegame variable is set."interaction_if_item": Can be opened by pressing the action command in front of it, provided that the player has a specific equipment item."explosion": Can be opened by an explosion.opening_condition (string, optional): The condition required to open the door. Only for opening methods "interaction_if_savegame_variable" and "interaction_if_item"."interaction_if_savegame_variable", it must be the name of a savegame variable. The hero will be allowed to open the door if this saved value is either true, an integer greater than zero or a non-empty string."interaction_if_item", it must be the name of an equipment item. The hero will be allowed to open the door if he has that item and, for items with an amount, if the amount is greater than zero.opening_condition_consumed (boolean, optional): Whether opening the door should consume the savegame variable or the equipment item that was required. The default setting is false. If you set it to true, the following rules are applied when the hero successfully opens the door:"interaction_if_savegame_variable", the savegame variable that was required is reset to false, 0 or "" (depending on its type)."interaction_if_item", the equipment item that was required is removed. This means setting its possessed variant to 0, unless it has an associated amount: in this case, the amount is decremented.cannot_open_dialog (string, optional): Id of the dialog to show if the hero fails to open the door. If you don't set this value, no dialog is shown.enabled_at_start (boolean, optional): Whether the entity should be initially enabled. The default value is true.properties (table, optional): Additional user-defined properties. See entity:set_properties() for the specification.Creates an entity of type stairs on the map.
properties (table): A table that describes all properties of the entity to create. Its key-value pairs must be:name (string, optional): Name identifying the entity or nil. If the name is already used by another entity, a suffix (of the form "_2", "_3", etc.) will be automatically appended to keep entity names unique.layer (number): The layer, between map:get_min_layer() and map:get_max_layer().x (number): X coordinate on the map.y (number): Y coordinate on the map.direction (number): Direction where the stairs should be turned between 0 (East of the room) and 3 (South of the room). For stairs inside a single floor, this is the direction of going upstairs.subtype (number): Kind of stairs to create:0: Spiral staircase going upstairs.1: Spiral staircase going downstairs.2: Straight staircase going upstairs.3: Straight staircase going downstairs.4: Small stairs inside a single floor (change the layer of the hero).enabled_at_start (boolean, optional): Whether the entity should be initially enabled. The default value is true.properties (table, optional): Additional user-defined properties. See entity:set_properties() for the specification.Creates an entity of type bomb on the map.
properties (table): A table that describes all properties of the entity to create. Its key-value pairs must be:name (string, optional): Name identifying the entity or nil. If the name is already used by another entity, a suffix (of the form "_2", "_3", etc.) will be automatically appended to keep entity names unique.layer (number): The layer, between map:get_min_layer() and map:get_max_layer().x (number): X coordinate on the map.y (number): Y coordinate on the map.enabled_at_start (boolean, optional): Whether the entity should be initially enabled. The default value is true.properties (table, optional): Additional user-defined properties. See entity:set_properties() for the specification.Creates an entity of type explosion on the map.
properties (table): A table that describes all properties of the entity to create. Its key-value pairs must be:name (string, optional): Name identifying the entity or nil. If the name is already used by another entity, a suffix (of the form "_2", "_3", etc.) will be automatically appended to keep entity names unique.layer (number): The layer, between map:get_min_layer() and map:get_max_layer().x (number): X coordinate on the map.y (number): Y coordinate on the map.enabled_at_start (boolean, optional): Whether the entity should be initially enabled. The default value is true.properties (table, optional): Additional user-defined properties. See entity:set_properties() for the specification.Creates an entity of type fire on the map.
properties (table): A table that describes all properties of the entity to create. Its key-value pairs must be:name (string, optional): Name identifying the entity or nil. If the name is already used by another entity, a suffix (of the form "_2", "_3", etc.) will be automatically appended to keep entity names unique.layer (number): The layer, between map:get_min_layer() and map:get_max_layer().x (number): X coordinate on the map.y (number): Y coordinate on the map.enabled_at_start (boolean, optional): Whether the entity should be initially enabled. The default value is true.properties (table, optional): Additional user-defined properties. See entity:set_properties() for the specification.Creates an entity of type separator on the map.
properties (table): A table that describles all properties of the entity to create. Its key-value pairs must be:name (string, optional): Name identifying the entity or nil. If the name is already used by another entity, a suffix (of the form "_2", "_3", etc.) will be automatically appended to keep entity names unique.layer (number): The layer, between map:get_min_layer() and map:get_max_layer().x (number): X coordinate on the map.y (number): Y coordinate on the map.width (number): Width of the entity in pixels.height (number): Height of the entity in pixels. One of width or height must be 16 pixels.enabled_at_start (boolean, optional): Whether the entity should be initially enabled. The default value is true.properties (table, optional): Additional user-defined properties. See entity:set_properties() for the specification.Creates an entity of type custom entity on the map.
properties (table): A table that describles all properties of the entity to create. Its key-value pairs must be:name (string, optional): Name identifying the entity or nil. If the name is already used by another entity, a suffix (of the form "_2", "_3", etc.) will be automatically appended to keep entity names unique.direction (number): Direction of the custom entity, between 0 (East) and 3 (South). This direction will be applied to the entity's sprites if possible.layer (number): The layer, between map:get_min_layer() and map:get_max_layer().x (number): X coordinate on the map.y (number): Y coordinate on the map.width (number): Width of the entity in pixels (default 16).height (number): Height of the entity in pixels (default 16).sprite (string, optional): Name of the animation set of a sprite to create for the custom entity.model (string, optional): Model of custom entity or nil. The model is the name of a Lua script in the "entities" directory of your quest. It will define the behavior of your entity. This script will be called with the entity as parameter. Models are useful when you need to create lots of similar entities, especially in different maps. nil means no model: in this case, no particular script will be called but you can still define the behavior of your entity in the map script.enabled_at_start (boolean, optional): Whether the entity should be initially enabled. The default value is true.properties (table, optional): Additional user-defined properties. See entity:set_properties() for the specification.Events are callback methods automatically called by the engine if you define them. In the case of maps, they are only called on the current map.
Called when this map starts (when the player enters it).
destination (destination): The destination entity from where the hero arrives on the map, or nil if he used another way than a destination entity (like the side of the map or direct coordinates).Called when this map stops (when the player leaves it).
Called at each cycle of the main loop while this map is the current one.
Called when the map has just been redrawn by the engine.
The engine has already drawn the map, but not the menus of this map if any. Use this event if you want to draw some additional content on the map before the menus, for example an overlay.
dst_surface (surface): The surface where the map is drawn. This surface represents the visible part of the screen, not the whole map.Called when the map has just been suspended or resumed.
The map is suspended by the engine in a few cases, like when the game is paused or when a dialog is active. When this happens, all map entities stop moving and most sprites stop their animation.
suspended (boolean): true if the map was just suspended, false if it was resumed.When the map begins, called when the opening transition effect finishes.
destination (destination): The destination entity from where the hero arrived on the map, or nil if he used another way than a destination entity (like the side of the map or direct coordinates).Called when the hero is obtaining a treasure on this map, before the treasure's dialog (if any).
treasure_item (item): Equipment item being obtained.treasure_variant (number): Variant of the treasure (because some equipment items may have several variants).treasure_savegame_variable (string): Name of the boolean value that stores in the savegame whether this treasure is found, or nil if this treasure is not saved.Called after the hero has obtained a treasure on this map.
In the case of a brandished treasure, this event is called once the treasure's dialog is finished. Otherwise, it is called immediately after map:on_obtaining_treasure().
treasure_item (item): Equipment item being obtained.treasure_variant (number): Variant of the treasure (because some equipment items may have several variants).treasure_savegame_variable (string): Name of the boolean value that stores in the savegame whether this treasure is found, or nil if this treasure is not saved.Called when the user presses a keyboard key while your map is active.
key (string): Name of the raw key that was pressed.modifiers (table): A table whose keys indicate what modifiers were down during the event. Possible table keys are "shift", "control" and "alt". Table values are `true.true, the event won't be propagated to other objects. If you return false or nothing, the event will continue its propagation to the commands.Called when the user releases a keyboard key while your map is active.
key (string): Name of the raw key that was released.true, the event won't be propagated to other objects. If you return false or nothing, the event will continue its propagation to the commands.Called when the user enters text while your map is active.
character (string): A utf-8 string representing the character that was pressed.true, the event won't be propagated to other objects. If you return false or nothing, the event will continue its propagation to the commands.Called when the user presses a joypad button while your map is active.
button (number): Index of the button that was pressed.true, the event won't be propagated to other objects.Called when the user releases a joypad button while your map is active.
button (number): Index of the button that was released.true, the event won't be propagated to other objects.Called when the user moves a joypad axis while your map is active.
axis (number): Index of the axis that was moved. Usually, 0 is an horizontal axis and 1 is a vertical axis.state (number): The new state of the axis that was moved. -1 means left or up, 0 means centered and 1 means right or down.true, the event won't be propagated to other objects.Called when the user moves a joypad hat while your map is active.
hat (number): Index of the hat that was moved.direction8 (number): The new direction of the hat. -1 means that the hat is centered. 0 to 7 indicates that the hat is in one of the eight main directions.true, the event won't be propagated to other objects.Called when the player presses a game command (a keyboard key or a joypad action mapped to a built-in game behavior) while this map is active. You can use this event to override the normal built-in behavior of the game command.
command (string): Name of the built-in game command that was pressed. Possible commands are "action", "attack", "pause", "item_1", "item_2", "right", "up", "left" and "down".true, the event won't be propagated to other objects (you are overriding the built-in behavior of pressing this game command).Called when the player released a game command (a keyboard key or a joypad action mapped to a built-in game behavior). while this map is active. You can use this event to override the normal built-in behavior of the game command.
command (string): Name of the built-in game command that was released. Possible commands are "action", "attack", "pause", "item_1", "item_2", "right", "up", "left" and "down".true, the event won't be propagated to other objects (you are overriding the built-in behavior of releasing this game command).Called when the user presses a mouse button while this map is active.
button (string): Name of the mouse button that was pressed. Possible values are "left", "middle", "right", "x1" and "x2".x (integer): The x position of the mouse in quest size coordinates.y (integer): The y position of the mouse in quest size coordinates.true, the event won't be propagated to other objects.Called when the user releases a mouse button while this map is active.
button (string): Name of the mouse button that was released. Possible values are "left", "middle", "right", "x1" and "x2".x (integer): The x position of the mouse in quest size coordinates.y (integer): The y position of the mouse in quest size coordinates.true, the event won't be propagated to other objects.Called when the user presses a finger while this map is active.
finger (integer): ID of the finger that was pressed.x (integer): The x position of the finger in quest size coordinates.y (integer): The y position of the finger in quest size coordinates.pressure (number): The pressure of the finger, normalized between 0 and 1.true, the event won't be propagated to other objects.Called when the user releases a finger while this map is active.
finger (integer): ID of the finger that was pressed.x (integer): The x position of the finger in quest size coordinates.y (integer): The y position of the finger in quest size coordinates.pressure (number): The pressure of the finger, normalized between 0 and 1.true, the event won't be propagated to other objects.Called when the user moves a finger while this map is active.
finger (integer): ID of the finger that was pressed.x (integer): The x position of the finger in quest size coordinates.y (integer): The y position of the finger in quest size coordinates.dx (integer): The horizontal distance moved by finger in quest size coordinates.dy (integer): The vertical distance moved by finger in quest size coordinates.pressure (number): The pressure of the finger, normalized between 0 and 1.true, the event won't be propagated to other objects.The following methods are deprecated and may be removed it future releases.
Returns the currently visible area of the map.
Use map:get_camera():get_bounding_box() instead.
Starts a camera moving sequence.
It can be rewritten in pure Lua as follows.
function map:move_camera(x, y, speed, callback, delay_before, delay_after)
local camera = map:get_camera()
local game = map:get_game()
local hero = map:get_hero()
delay_before = delay_before or 1000
delay_after = delay_after or 1000
local back_x, back_y = camera:get_position_to_track(hero)
game:set_suspended(true)
camera:start_manual()
local movement = sol.movement.create("target")
movement:set_target(camera:get_position_to_track(x, y))
movement:set_ignore_obstacles(true)
movement:set_speed(speed)
movement:start(camera, function()
local timer_1 = sol.timer.start(map, delay_before, function()
callback()
local timer_2 = sol.timer.start(map, delay_after, function()
local movement = sol.movement.create("target")
movement:set_target(back_x, back_y)
movement:set_ignore_obstacles(true)
movement:set_speed(speed)
movement:start(camera, function()
game:set_suspended(false)
camera:start_tracking(hero)
if map.on_camera_back ~= nil then
map:on_camera_back()
end
end)
end)
timer_2:set_suspended_with_map(false)
end)
timer_1:set_suspended_with_map(false)
end)
end
This function temporarily moves the camera somewhere else, like to a place where a chest or an enemy will appear.
The camera first moves towards a target point. When the target is reached, after a first delay, your callback function is called. Then, after a second delay, the camera moves back towards the hero. The game is suspended during the whole sequence.
x (number): X coordinate of the target, relative to the map's top-left corner.y (number): Y coordinate of the target, relative to the map's top-left corner.speed (number): Speed of the camera movement in pixels per second.callback (function): A function to be called when the camera reaches the target (after delay_before).delay_before (number, optional): A delay in milliseconds before calling your function once the target is reached (default 1000).delay_after (number, optional): A delay in milliseconds after calling your function, before the camera goes back (default 1000).The following events are deprecated and may be removed it future releases.
After a camera sequence initiated by map:move_camera(), this event is triggered when the camera gets back to the hero.
Use camera:on_state_changed() instead, or the callback parameter of movement:start()
1.8.13