Solarus quests  1.5
Quest maker's reference
Map entities

Table of Contents

Objects placed on the map are called map entities (or just entities).

There exists many types of entities. They can be either declared in the map data file, or created dynamically by using the map:create_* methods of the map API.

Overview

All entities have a position on the map (X, Y and layer) and a size. Depending on their type, they can be visible or not. When they are visible, they are usually represented by one or several sprites. Some entities are fixed, others move according to a movement object.

Entities can also have a name that uniquely identifies them on the map. This is useful to access them from the map API. The name is optional, but if an entity has a name, it must be unique on the map.

Here are the existing types of entities.

Remarks
Note that sprites and movements are not map entities, but they can be attached to map entities (to display them and to move them, respectively). Sprites and movements can also be used outside a map, for example in your title screen or in other menus.

Methods of all entity types

These methods exist in all entity types.

entity:get_type()

Returns the type of entity.

  • Return value (string): The type of this entity. Can be one of: "hero", "dynamic_tile", "teletransporter", "destination", "pickable", "destructible", "carried_object", "chest", "shop_treasure", "enemy", "npc", "block", "jumper", "switch", "sensor", "separator", "wall", "crystal", "crystal_block", "stream", "door", "stairs", "bomb", "explosion", "fire", "arrow", "hookshot", "boomerang" or "custom_entity".
Remarks
The type "tile" is not is this list because tiles don't exist at runtime for optimization reasons.

entity:get_map()

Returns the map this entity belongs to.

  • Return value (map): The map that contains this entity.

entity:get_game()

Returns the game that is running the map this entity belongs to.

  • Return value (game): The current game.

entity:get_name()

Returns the name of this map entity.

The name uniquely identifies the entity on the map.

  • Return value (string): The name of this entity, or nil if the entity has no name (because the name is optional).

entity:exists()

Returns whether this entity still exists on the map.

An entity gets destroyed when you call entity:remove() or when the engine removes it (for example an enemy that gets killed or a pickable treasure that gets picked up). If you refer from Lua to an entity that no longer exists in the C++ side, this method returns false.

  • Return value (boolean): true if the entity exists, false if it was destroyed.

entity:remove()

Removes this entity from the map and destroys it.

After the entity is destroyed, entity:exists() returns false and there is no reason to keep a reference to it in the Lua side (though it is harmless).

entity:is_enabled()

Returns whether this entity is enabled.

When an entity is disabled, it is not displayed on the map, it does not move and does not detect collisions. But it still exists, it still has a position and it can be enabled again later.

  • Return value (boolean): true if this entity is enabled.

entity:set_enabled([enabled])

Enables or disables this entity.

When an entity is disabled, it is not displayed on the map, it does not move and does not detect collisions. Its movement, its sprites and its timers if any are suspended and will be resumed when the entity gets enabled again. While the entity is disabled, it still exists, it still has a position and it can be enabled again later.

  • enabled (boolean, optional): true to enable the entity, false to disable it. No value means true.

entity:get_size()

Returns the size of the bounding box of this entity.

The bounding box determines the position of the entity on the map. It is a rectangle whose width and height are multiples of 8 pixels. The bounding box is used to detect whether the entity overlaps obstacles or other entities.

  • Return value 1 (number): Width of the entity in pixels.
  • Return value 2 (number): Height of the entity in pixels.
Remarks
Note that the sprites of an entity may have a different size than the entity itself. See sprite:get_size() to know it.

entity:get_origin()

Returns the origin point of this entity, relative to the upper left corner of its bounding box.

When an entity is located at some coordinates on the map, the origin points determines what exact point of the entity's bounding box is at those coordinates. It is not necessarily the upper left corner of the entity's bounding box.

The origin point is usually be the central point of contact between the entity and the ground. For example, the origin point of the hero, enemies, non-playing characters and most entities is the center of their shadow. Thus, for entities of size (16,16), the origin point is often (8,13).

This origin point property allows entities of different sizes to have comparable reference points that can be used by the engine. Indeed, when two enemies overlap, the engine needs to determine which one has to be displayed first (it is always the one with the lowest Y coordinate). Sometimes, the engine also needs to compute an angle between two entities, for example to push away an enemy that was just hit. Using the upper left corner of their bounding box would not give the correct angle (unless both entities had the same size).

The origin point is also the point of synchronization of an entity with its sprites (because again, an entity that has a given size may have sprites with different sizes).

  • Return value 1 (number): X coordinate of the origin point in pixels, relative to the upper left corner of the entity's bounding box.
  • Return value 2 (number): Y coordinate of the origin point in pixels, relative to the upper left corner of the entity's bounding box.

entity:get_position()

Returns the position of this entity on the map (coordinates and layer).

  • Return value 1 (number): X coordinate of the origin point of the entity, relative to the upper left corner of the map.
  • Return value 2 (number): Y coordinate of the origin point of the entity, relative to the upper left corner of the map.
  • Return value 3 (number): Layer where the entity is on the map, between map:get_min_layer() and map:get_max_layer().

entity:set_position(x, y, [layer])

Changes instantly the position of this entity on the map (coordinates and layer). The origin point of the entity gets placed at these coordinates, relative to the map's upper left corner. Any previous movement or other action performed by the entity continues normally.

  • x (number): X coordinate to set.
  • y (number): Y coordinate to set.
  • layer (number, optional): Layer to set, between map:get_min_layer() and map:get_max_layer(). By default, the layer is unchanged.
Remarks
Be careful: this function does not check collisions with obstacles.

entity:get_center_position()

Returns the coordinates of the center point of this entity on the map.

  • Return value 1 (number): X coordinate of the center of this entity's bounding box, relative to the upper left corner of the map.
  • Return value 2 (number): Y coordinate of the center of this entity's bounding box, relative to the upper left corner of the map.
  • Return value 3 (number): Layer of the entity.

entity:get_facing_position()

Returns the coordinates of the point this entity is looking at. This point depends on the direction of the main sprite if any. If the entity has no sprite, or if the main sprite has not 4 directions, then the movement is considered. If there is no movement either, the entity is assumed to look to the North.

  • Return value 1 (number): X coordinate of the facing point of this entity, relative to the upper left corner of the map.
  • Return value 2 (number): Y coordinate of the facing point of this entity, relative to the upper left corner of the map.
  • Return value 3 (number): Layer of the entity.

entity:get_facing_entity()

Returns the entity this entity is looking at, if any.

This is an entity overlapping the facing position of this entity. If several entities are overlapping the facing position, the first one in Z order is returned.

  • Return value (entity): The facing entity, or nil if there is no entity in front of this entity.

entity:get_ground_position()

Returns the coordinates of the point used for ground detection for this entity on the map.

The ground position is the point tested by all features related to the ground, like all effects of various grounds on the hero, the result of entity:get_ground_below() and the event custom_entity:on_ground_below_changed().

  • Return value 1 (number): X coordinate of the ground point of this entity, relative to the upper left corner of the map.
  • Return value 2 (number): Y coordinate of the ground point of this entity, relative to the upper left corner of the map.
  • Return value 3 (number): Layer of the entity.
Remarks
The ground point of an entity is slightly (2 pixels) above its origin point as returned by entity:get_position().

entity:get_ground_below()

Returns the map's ground below this entity.

The ground is defined by the topmost tile below this entity, plus potential dynamic entities that may affect the ground, like dynamic tiles, destructibles and custom entities.

The exact point tested is the one returned by entity:get_ground_position(), and it is slightly different from entity:get_position().

  • Return value (string): The ground below this entity. See map:get_ground() for the list of possible grounds.

entity:get_bounding_box()

Returns the rectangle representing the coordinates and size of this entity on the map.

The bounding box determines the position of the entity on the map. It is a rectangle whose width and height are multiples of 8 pixels. The bounding box is used to detect whether the entity overlaps obstacles or other entities.

  • Return value 1 (number): X coordinate of the upper left corner of the bounding box.
  • Return value 2 (number): Y coordinate of the upper left corner of the bounding box.
  • Return value 3 (number): Width of the bounding box.
  • Return value 4 (number): Height of the bounding box.
Remarks
The sprites of this entity (if any) may exceed the bounding box. See entity:get_max_bounding_box().

entity:get_max_bounding_box()

Returns the rectangle surrounding the bounding box of this entity plus the bounding boxes of its sprites in all their possible animations and directions.

This is usually larger than entity:get_bounding_box(), because the sprite of an entity often exceeds its bounding box.

  • Return value 1 (number): X coordinate of the upper left corner of the sprites bounding box.
  • Return value 2 (number): Y coordinate of the upper left corner of the sprites bounding box.
  • Return value 3 (number): Width of the sprites bounding box.
  • Return value 4 (number): Height of the sprites bounding box.

entity:overlaps(x, y, [width, height])

Returns whether the bounding box of this entity overlaps the specified rectangle or point.

To test if this entity overlaps a rectangle or a point (a point is a rectangle of size 1x1):

  • x (number): X coordinate of the upper left corner of the rectangle to check.
  • y (number): Y coordinate of the upper left corner of the rectangle to check.
  • width (number, optional): Width of the rectangle (default 1).
  • height (number, optional): Height of the rectangle (default 1).
  • Return value (boolean): true if the bounding box of this entity overlaps the rectangle.

entity:overlaps(other_entity, [collision_mode])

Returns whether another entity collides with this entity according to the specified collision test.

  • entity (entity): Another entity.
  • collision_mode (string, optional): Specifies what kind of collision you want to test. This may be one of:
    • "overlapping": Collision if the bounding box of both entities overlap. This is the default value.
    • "containing": Collision if the bounding box of the other entity is fully inside the bounding box of this entity.
    • "origin": Collision if the origin point or the other entity is inside the bounding box of this entity.
    • "center": Collision if the center point of the other entity is inside the bounding box of this entity.
    • "facing": Collision if the facing position of the other entity's bounding box is touching this entity's bounding box. Bounding boxes don't necessarily overlap, but they are in contact: there is no space between them. When you consider the bounding box of an entity, which is a rectangle with four sides, the facing point is the middle point of the side the entity is oriented to. This "facing" collision test is useful when the other entity cannot traverse your custom entity. For instance, if the other entity has direction "east", there is a collision if the middle of the east side of its bounding box touches (but does not necessarily overlap) this entity's bounding box. This is typically what you need to let the hero interact with this entity when he is looking at it.
    • "touching": Like "facing", but accepts all four sides of the other entity's bounding box, no matter its direction.
    • "sprite": Collision if a sprite of the other entity overlaps a sprite of this entity. The collision test is pixel precise.
  • Return value (boolean): true if a collision is detected with this collision test.
Remarks
For custom entities, see also custom_entity:add_collision_test() to be automatically notified when a collision is detected.

entity:get_distance(x, y), entity:get_distance(other_entity)

Returns the distance in pixels between this map entity and a point or another map entity.

To compute the distance to a specified point:

  • x (number): X coordinate of the point.
  • y (number): Y coordinate of the point.
  • Return value (number): The distance in pixels between the origin point of this entity and the point.

To compute the distance to another map entity:

  • other_entity (entity): The entity to compute the distance to.
  • Return value (number): The distance in pixels between the origin point of this entity and the origin point of the other entity.

entity:get_angle(x, y), entity:get_angle(other_entity)

Returns the angle between the X axis and the vector that joins this entity to a point.

To compute the angle to a specified point:

  • x (number): X coordinate of the point.
  • y (number): Y coordinate of the point.
  • Return value (number): The angle in radians between the origin point of this entity and the specified point. The angle is between 0 and 2 * math.pi.

To compute the angle to another map entity:

  • other_entity (entity): The entity to compute the angle to.
  • Return value (number): The angle in radians between the origin point of this entity and the origin point of the other entity. The angle is between 0 and 2 * math.pi.

entity:get_direction4_to(x, y), entity:get_direction4_to(other_entity)

Like entity:get_angle(), but instead of an angle in radians, returns the closest direction among the 4 main directions.

This is a utility function that essentially rounds the result of entity:get_angle().

To compute the direction to a specified point:

  • x (number): X coordinate of the point.
  • y (number): Y coordinate of the point.
  • Return value (number): The direction this entity should take to look at this point, between 0 (East) and 3 (South).

To compute the direction to another map entity:

  • other_entity (entity): An entity to target.
  • Return value (number): The direction this entity should take to look at the other entity, between 0 (East) and 3 (South).

entity:get_direction8_to(x, y), entity:get_direction8_to(other_entity)

Like entity:get_angle(), but instead of an angle in radians, returns the closest direction among the 8 main directions.

This is a utility function that essentially rounds the result of entity:get_angle().

To compute the direction to a specified point:

  • x (number): X coordinate of the point.
  • y (number): Y coordinate of the point.
  • Return value (number): The direction this entity should take to look at this point, between 0 (East) and 7 (South-East).

To compute the direction to another map entity:

  • other_entity (entity): An entity to target.
  • Return value (number): The direction this entity should take to look at the other entity, between 0 (East) and 7 (South-East).

entity:snap_to_grid()

Makes sure this entity's upper left corner is aligned with the 8*8 grid of the map.

Remarks
Be careful: this function does not check collisions with obstacles.

entity:bring_to_front()

Places this entity in front of all other entities on the same layer.

Since entities that are on the same layer can overlap, you can use this function to change their Z-index.

Remarks
Some entities like NPCs, enemies, the hero and some custom entities have the property to be displayed in Y order. The Z-index of these entities is already managed by the engine to show entities more to the north behind the ones more to the south. Therefore, this function has no effect on their drawing order.

entity:bring_to_back()

Places this entity behind all other entities on the same layer.

Since entities that are on the same layer can overlap, you can use this function to change their Z-index.

Remarks
Some entities like NPCs, enemies and the hero have the property to be displayed in Y order. The Z-index of these entities is already managed by the engine to show entities more to the north behind the ones more to the south. Therefore, this function has no effect on their drawing.

entity:get_optimization_distance()

Returns the optimization threshold hint of this map entity.

Above this distance from the camera, the engine may decide to skip updates or drawings. This is only a hint: the engine is responsible of the final decision. A value of 0 means an infinite distance (the entity is never optimized away).

  • Return value (number): The optimization distance hint in pixels.

entity:set_optimization_distance(optimization_distance)

Sets the optimization threshold hint of this map entity.

Above this distance from the camera, the engine may decide to skip updates or drawings. This is only a hint: the engine is responsible of the final decision.

A value of 0 means an infinite distance (the entity is never optimized away). The default value is 0.

  • optimization_distance (number): The optimization distance hint to set in pixels.

entity:is_in_same_region(other_entity)

Returns whether this entity is in the same region as another one.

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.

You can use this function to make sure that an enemy close to the hero but in the other side of a separator won't attack him.

  • other_entity (entity): Another entity.
  • Return value (boolean): true if both entities are in the same region.

entity:test_obstacles([dx, dy, [layer]])

Returns whether there would be a collision with obstacles if this map entity was translated.

  • dx (number, optional): X component of the translation in pixels (0 means the current X position). No value means 0.
  • dx (number, optional): Y component of the translation in pixels (0 means the current Y position). No value means 0.
  • layer (number, optional): Layer to test. No value means the current layer.
  • Return value (boolean): true if there would be a collision in this position.

entity:get_sprite([name])

Returns a sprite representing this entity.

To manage entities with multiple sprites, you can set names with sprite creation methods like enemy:create_sprite() and custom_entity:create_sprite(). However, it is easier to just leave the names blank and simply store the result of these sprite creation methods. The name is more useful for built-in entities that have multiple sprites automatically created by the engine. Such entities are the hero, pickable treasures, carried objects and crystals. See the documentation pages of these entities to know their exact sprites, the name of these sprites and which one is their main sprite. For enemies and custom entities, the main sprite is the first one in Z order, which is the sprite creation order unless you call entity:bring_sprite_to_front() or entity:bring_sprite_to_back().

  • name (string, optional): Name of the sprite to get. Only useful for entities that have multiple sprites. No value means the main sprite.
  • Return value (sprite): The entity sprite with this name, or its main sprite if no name is specified. Returns nil if the entity has no such sprite.

entity:get_sprites()

Returns an iterator to all sprites of this entity.

At each step, the iterator provides two values: the name of a sprite (which is an empty string if the sprite has no name) and the sprite itself. See entity:get_sprite() for more details about named sprites.

Sprites are returned in their displaying order. Note that this order can be changed with entity:bring_sprite_to_front() and entity:bring_sprite_to_back().

The typical usage of this function is:

for sprite_name, sprite in entity:get_sprites() do
  -- some code related to the sprite
end
  • Return value (function): An iterator to all sprites of this entity.

entity:bring_sprite_to_front(sprite)

Reorders a sprite of this entity to be displayed after other sprites (displayed to the front).

This function is only useful for entities that have multiple sprites.

  • sprite (sprite): The sprite to reorder. It must belong to this entity.

entity:bring_sprite_to_back(sprite)

Reorders a sprite of this entity to be displayed before other sprites (displayed to the back).

This function is only useful for entities that have multiple sprites.

  • sprite (sprite): The sprite to reorder. It must belong to this entity.

entity:is_visible()

Returns whether this entity is visible.

When the entity is hidden, its sprites (if any) are not displayed, but everything else continues normally, including collisions.

  • Return value (boolean): true if the entity is visible.

entity:set_visible([visible])

Hides or shows the entity.

When the entity is hidden, its sprites (if any) are not displayed, but everything else continues normally, including collisions.

  • visible (boolean, optional): true to show the entity, false to hide it. No value means true.

entity:get_movement()

Returns the current movement of this map entity.

  • Return value (movement): The current movement, or nil if the entity is not moving.

entity:stop_movement()

Stops the current movement of this map entity if any.

Events of all entity types

Events are callback methods automatically called by the engine if you define them.

entity:on_created()

Called when this entity has just been created on the map.

entity:on_removed()

Called when this entity is about to be removed from the map (and therefore destroyed).

entity:on_position_changed(x, y, layer)

Called when the coordinates of this entity have just changed.

  • x (number): The new X coordinate of the entity.
  • y (number): The new Y coordinate of the entity.
  • layer (number): The new layer of the entity.

entity:on_obstacle_reached(movement)

Called when the movement of this entity was stopped because of an obstacle.

When an obstacle is reached, this event is called instead of entity:on_position_changed().

  • movement (movement): The movement of the entity.

entity:on_movement_started(movement)

Called when a movement is started on this entity.

  • movement (movement): The movement that was just started on this entity.

entity:on_movement_changed(movement)

Called when some characteristics of this entity's movement (like the speed or the angle) have just changed.

  • movement (movement): The movement of the entity.

entity:on_movement_finished()

Called when the movement of the entity is finished (if there is an end).