1.14.31 - Custom entity

A custom entity is a map entity entirely defined by your Lua scripts.

This type of map entity can be declared in the map data file. It can also be created dynamically with map:create_custom_entity().

Overview

Custom entities have no special properties or behavior. You can define them entirely in your scripts.

Optionally, a custom entity may be managed by a model. The model is the name of a Lua script that will be applied to all custom entities refering to it. This works exactly like the breed of enemies, except that it is optional. The model is useful if you have a lot of identical (or very similar) custom entities in your game, like for example torches.

If you make an entity that is unique in your game, like for example, a big rock that blocks the entrance of a dungeon and that requires some special action from the player, you don't need a model. You can just program the behavior of your custom entity in the script of its map. Similarly, to define a customized weapon of the hero, like a hammer, you don't need a model. Just create a custom entity from the item script of the hammer and define its behavior there.

Methods inherited from map entity

Custom entities are particular map entities. Therefore, they inherit all methods from the type map entity.

See Methods of all entity types to know these methods.

Methods of the type custom entity

The following methods are specific to custom entities.

custom_entity:get_model()

Returns the model of this custom entity.

The model is the name of a Lua script in the "entities" directory that manages this custom entity. This works exactly like the breed of enemies, except that it is optional.

custom_entity:set_size(width, height)

Sets the size of the bounding box of this custom entity.

The default value is 16x16 pixels. This is the effective size used to detect obstacles when moving, but the sprite(s) of the custom entity may be larger.

Remarks
If you create a pixel-precise collision test, the test will use the sprite(s) of this custom entity, not its bounding box. Therefore, this function has no influence on pixel-precise collisions, only on the detection of obstacles of the map when the custom entity moves.

custom_entity:set_origin(origin_x, origin_y)

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

This origin point property allows entities of different sizes to have comparable reference points. For example, if you need to compute an angle between two entities, for example to move an entity away from another one, the calculation uses the origin point of both entities. 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).

The default values is 8,13 and is usually okay for custom entities of size 16x16. See entity:get_origin() for more explanations about the origin point.

custom_entity:get_direction()

Returns the direction of this custom entity.

This direction is set at creation time or when you can call custom_entity:set_direction().

custom_entity:set_direction(direction)

Sets the direction of this custom entity.

Sprites of your custom entity that have such a direction automatically take it.

custom_entity:create_sprite(animation_set_id, [sprite_name])

Creates a sprite for this custom entity.

custom_entity:remove_sprite([sprite])

Removes and destroys a sprite of this custom_entity.

It may have been created at the creation of the custom entity, or when you called custom_entity:create_sprite().

custom_entity:is_drawn_in_y_order()

Returns whether this custom entity is drawn in Y order.

The displaying order of entities having this property depends on their Y position. Entities without this property are drawn in the normal order (i.e. in the order of their creation), and before all entities with this property.

Entities with this property are displayed from the one the most to the north to the one the most to the south.

custom_entity:set_drawn_in_y_order([y_order])

Sets whether this custom entity should be drawn in Y order.

The default setting is false, meaning that by default, a custom entity is displayed in Z order, which is the creation order unless you call entity:bring_to_front() or entity:bring_to_back().

See custom_entity:is_drawn_in_y_order() for more details.

custom_entity:set_traversable_by([entity_type], traversable)

Sets whether this custom entity can be traversed by other entities.

By default, a custom entity can be traversed.

custom_entity:set_can_traverse([entity_type], traversable)

Sets whether this custom entity can traverse other entities.

This is important only if your custom entity can move.

By default, this depends on the other entities: for example, sensors can be traversed by default while doors cannot unless they are open.

custom_entity:can_traverse_ground(ground)

Returns whether this custom entity can traverse a kind of ground.

This is important only if your custom entity can move.

The ground is the terrain property of the map. It is defined by tiles and by other entities that may change it dynamically.

custom_entity:set_can_traverse_ground(ground, traversable)

Sets whether this custom entity can traverse a kind of ground.

This is important only if your custom entity can move.

The ground is the terrain property of the map. It is defined by tiles and by other entities that may change it dynamically.

By default, this depends on the the ground: for example, the "grass" ground can be traversed by default while the "low wall" ground cannot.

custom_entity:add_collision_test(collision_mode, callback)

Registers a function to be called when your custom entity detects a collision when another entity.

Remarks
See also entity:overlaps() to directly test a collision rather than registering a callback.

custom_entity:clear_collision_tests()

Disables any collision test previously registered with custom_entity:add_collision_test().

custom_entity:has_layer_independent_collisions()

Returns whether this custom entity can detect collisions with entities even if they are not on the same layer.

By default, custom entities can only have collisions with entities on the same layer.

custom_entity:set_layer_independent_collisions([independent])

Sets whether this custom entity can detect collisions with entities even if they are not on the same layer.

By default, custom entities can only have collisions with entities on the same layer. If you set this property to true, the collision tests will be performed even with entities that are on a different layer.

custom_entity:get_modified_ground()

Returns the kind of ground (terrain) defined by this custom entity on the map.

custom_entity:set_modified_ground(modified_ground)

Sets the kind of ground (terrain) defined by this custom entity on the map.

The ground of the map is normally defined by tiles, but other entities may modify it dynamically.

This property allows you to make a custom entity that modifies the ground of the map, for example a hole with a special sprite or ice with particular collision callbacks. The modified ground will be applied on the map in the rectangle of this custom entity's bounding box. Your custom entity can move: the ground will still be correctly applied.

Remarks
If you only need to modify the ground of the map dynamically, for example to make a moving platform over holes, a dynamic tile with a movement may be enough.

Events inherited from map entity

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

Custom entities are particular map entities. Therefore, they inherit all events from the type map entity.

See Events of all entity types to know these events.

Events of the type custom entity

The following events are specific to custom entities.

custom_entity:on_update()

Called at each cycle while this custom entity lives on the map.

Remarks
As this function is called at each cycle, it is recommended to use other solutions when possible, like timers and other events.

custom_entity:on_suspended(suspended)

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 the camera is being moved by a script. When this happens, all map entities stop moving and most sprites stop their animation.

custom_entity:on_created()

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

custom_entity:on_enabled()

Called when this custom entity has just been enabled.

custom_entity:on_disabled()

Called when this custom entity has just been disabled.

custom_entity:on_pre_draw()

Called just before this custom entity is drawn on the map. You may display additional things below the sprites.

custom_entity:on_post_draw()

Called just after this custom entity is drawn on the map. You may display additional things above the sprites.

custom_entity:on_ground_below_changed(ground_below)

Called when the kind of ground on the map below this custom entity has changed. It may change because this custom entity is moving, or when because another entity changes it.

custom_entity:on_interaction()

Called when the hero interacts with this custom entity, that is, when the player presses the action command while facing this custom entity.

Remarks
This event is also available with NPCs.

custom_entity:on_interaction_item(item_used)

Called when the hero uses any equipment item (the player pressed an item command) while facing this custom entity.

Remarks
This event is also available with NPCs.