Entity module

Tools for working with entities.

Usage

local Entity = require('stdlib/entity/entity')

Functions

_are_equal (entity_a, entity_b)	Tests if two entities are equal.
get_data (entity)	Gets the user data that is associated with an entity.
has (entity, field_name)	Tests whether an entity has access to a given field.
set_data (entity, data)	Associates the user data to an entity.
set_frozen (entity[, mode=true])	Freezes an entity, by making it inactive, inoperable, and non-rotatable, or unfreezes by doing the reverse.
set_indestructible (entity[, mode=true])	Makes an entity indestructible so that it cannot be damaged or mined neither by the player nor by their enemy factions.
to_collision_area ()	Deprecated see LuaEntity.bounding_box Converts an entity and its collision_box to the area around it.
to_selection_area ()	Converts an entity and its selection_box to the area around it.

Functions that raise events

create_entity (surface, settings[, player_index][, raise_script_event])	Create an entity and raise a build event.
destroy_entity (entity[, died=false][, cause][, force])	Destroy an entity by first raising the event.
revive (ghost[, player_index][, raise_script_event])	Revivie an entity ghost and raise the on_built or on_robot_built event.

Functions

# _are_equal (entity_a, entity_b)

Tests if two entities are equal.

If they don't have a reference equality and entity_a has equals function, it will be called with entity_b as its first argument.

Parameters:

• entity_a : (LuaEntity)
• entity_b : (LuaEntity)

Returns:

• (boolean)

# get_data (entity)

Gets the user data that is associated with an entity.

The user data is stored in the global object and it persists between loads.

The user data will be removed from an entity when the entity becomes invalid.

Parameters:

• entity : (LuaEntity) the entity to look up

Returns:

• (nil or Mixed) the user data, or nil if no data exists for the entity

# has (entity, field_name)

Tests whether an entity has access to a given field.

Parameters:

• entity : (LuaEntity) the entity to test the access to a field
• field_name : (string) the field name

Returns:

• (boolean) true if the entity has access to the field, false if the entity threw an exception when trying to access the field

# set_data (entity, data)

Associates the user data to an entity.

The user data will be stored in the global object and it will persist between loads.

The user data will be removed from an entity when the entity becomes invalid.

Parameters:

• entity : (LuaEntity) the entity with which to associate the user data
• data : (nil or Mixed) the data to set, or nil to delete the data associated with the entity

Returns:

• (nil or Mixed) the previous data associated with the entity, or nil if the entity had no previous data

# set_frozen (entity[, mode=true])

Freezes an entity, by making it inactive, inoperable, and non-rotatable, or unfreezes by doing the reverse.

Parameters:

• entity : (LuaEntity) the entity to freeze or unfreeze
• mode : (boolean) if true, freezes the entity, if false, unfreezes the entity. If not specified, it is set to true (default: true)

Returns:

• (LuaEntity) the entity that has been frozen or unfrozen

# set_indestructible (entity[, mode=true])

Makes an entity indestructible so that it cannot be damaged or mined neither by the player nor by their enemy factions.

Parameters:

• entity : (LuaEntity) the entity to make indestructable
• mode : (boolean) if true, makes the entity indestructible, if false, makes the entity destructable (default: true)

Returns:

• (LuaEntity) the entity that has been made indestructable or destructable

# to_collision_area ()

Deprecated see LuaEntity.bounding_box
Converts an entity and its collision_box to the area around it.

See also:

• Area.to_collision_area
• LuaEntity.bounding_box

# to_selection_area ()

Converts an entity and its selection_box to the area around it.

See also:

• Area.to_selection_area

Functions that raise events

# create_entity (surface, settings[, player_index][, raise_script_event])

Create an entity and raise a build event.

Parameters:

• surface : (LuaSurface) the surface to create the entity on
• settings : (table) settings to pass to create_entity see LuaSurface.create_entity
• player_index : (uint) the index of the player, when not present and not raisescriptevent pass a fake robot (optional)
• raise_script_event : (boolean) raise scriptraisedbuilt (optional)

Returns:

• (LuaEntity) the created entity

# destroy_entity (entity[, died=false][, cause][, force])

Destroy an entity by first raising the event.

Some entities can't be destroyed, such as the rails with trains on them.

Parameters:

• entity : (LuaEntity) the entity to be destroyed
• died : (boolean) raise onentitydied event (default: false)
• cause : (LuaEntity) the entity if available that did the killing for onentitydied (optional)
• force : (LuaForce) the force if any that did the killing (optional)

Returns:

• (boolean) was the entity destroyed?

# revive (ghost[, player_index][, raise_script_event])

Revivie an entity ghost and raise the on_built or on_robot_built event.

Parameters:

• ghost : (LuaEntity) the ghost entity to revivie
• player_index : (uint) if present, raise on_built_entity with player_index, if not present raise on_robot_built_entity (optional)
• raise_script_event : (boolean) , if true raise scriptraisedbuilt as the event (optional)

Returns:

• (table) the item stacks this entity collided with
• (LuaEntity) the new revived entity
• (LuaEntity) the item request proxy if present