Entity.Entity module

Tools for working with entities.

Usage

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

Functions

has(entity, field_name) Tests whether an entity has access to a given field.
get_data(entity) Gets the user data that is associated with an entity.
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.
_are_equal(entity_a, entity_b) Tests if two entities are equal.

Functions that raise events

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

Functions

# 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
# 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: Returns:
  • (nil or Mixed) the user data, or nil if no data exists for the entity
# 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
# _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: Returns:

Functions that raise events

# 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?
# 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:
# 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