LuaEntity

class LuaEntity
get_output_inventory() → LuaInventory Gets the entities output inventory if it has one.
get_module_inventory() → LuaInventory
damage(damage, force, type) → float Damages the entity.
destroy() → boolean Destroys the entity.
set_command(command) Give the entity a command.
has_command() → boolean Has this unit been assigned a command?
die() Immediately kills the entity.
has_flag(flag) → boolean Test whether this entity's prototype has a flag set.
add_market_item{price=…, offer=…} Offer a thing on the market.
remove_market_item(offer) → boolean Remove an offer from a market.
get_market_items() → array of Offer Get all offers in a market as an array.
connect_neighbour(target) Connect two devices with wire or cable.
disconnect_neighbour(target) Disconnect wires or cables.
order_deconstruction(force) Sets the entity to be deconstructed by construction robots.
cancel_deconstruction(force) Cancels deconstruction if it is scheduled, does nothing otherwise.
to_be_deconstructed(force) → boolean Is this entity marked for deconstruction?
get_filter(slot) → string Get the filter for a slot.
set_filter(filter, slot) Set the filter for a slot.
clear_filter(slot) Clear the filter for a slot.
get_request_slot(slot) → LuaItemStack Get a logistic requester slot.
set_request_slot(request, slot) Set a logistic requester slot.
clear_request_slot(slot) Clear a logistic requester slot.
get_circuit_condition(connector)
set_circuit_condition(connector, condition_or_parameters)
is_crafting() → boolean
is_opened() → boolean
is_opening() → boolean
is_closed() → boolean
is_closing() → boolean
request_to_open(force, extra_time)
request_to_close(force)
get_transport_line(index) → LuaTransportLine Get a transport line of a belt.
launch_rocket() → boolean
revive() → uint Revive a ghost.
get_connected_rail{rail_direction=…, rail_connection_direction=…} → LuaEntity
get_inventory(inventory) → LuaInventory Get an inventory belonging to this entity.
can_insert(items) → boolean Can at least some items be inserted?
insert(items) → uint Insert items into this entity.
get_item_count(item) → uint Get the number of all or some items in this entity.
has_items_inside() → boolean Does this entity have any item inside it?
clear_items_inside() Remove all items from this entity.
remove_item(items) → uint Remove items from this entity.
teleport(position, surface) → boolean Teleport the entity to a given position, possibly on another surface.
valid :: boolean [R] Is this object valid?
passenger :: LuaEntity [RW] Setting to nil forces the character out of the vehicle, setting to a new character forces any existing passenger out and the given character becomes the new passenger.
name :: string [R] Name of the entity prototype.
ghost_name :: string [R] Name of the entity contained in this ghost
localised_name :: LocalisedString [R] Localised name of the entity.
ghost_localised_name :: LocalisedString [R] Localised name of the entity contained in this ghost.
type :: string [R] The entity prototype type of this entity.
ghost_type :: string [R] The prototype type of the entity contained in this ghost.
active :: boolean [RW] Deactivating an entity will stop all its operations (car will stop moving, inserters will stop working, fish will stop moving etc).
destructible :: boolean [RW] When the entity is not destructible it can't be damaged.
minable :: boolean [RW]
rotatable :: boolean [RW] When entity is not to be rotatable (inserter, transport belt etc), it can't be rotated by player using the R key.
operable :: boolean [RW] Player can't open gui of this entity and he can't quick insert/input stuff in to the entity when it is not operable.
health :: float [RW] Health of the entity.
direction :: defines.direction [RW] The current direction this entity is facing.
orientation :: float [RW] The smooth orientation.
amount :: uint [RW] Count of resource units contained.
effectivity_modifier :: float [RW] Multiplies the acceleration the vehicle can create for one unit of energy.
consumption_modifier :: float [RW] Multiplies the the energy consumption.
friction_modifier :: float [RW] Multiplies the car friction rate.
speed :: float [RW] The current speed of the car.
stack :: LuaItemStack [R]
prototype :: LuaEntityPrototype [R] The entity prototype of this entity.
ghost_prototype :: LuaEntityPrototype [R] The entity prototype of the entity contained in this ghost.
drop_position :: Position [R] Position where the entity puts its stuff.
drop_target :: LuaEntity [R] The entity this entity is putting its stuff to or nil if there is no such entity.
selected_gun_index :: uint [RW] Index of the currently selected weapon slot of this character.
energy :: float [RW] Energy stored in the entity (heat in furnace, energy stored in electrical devices etc.
recipe :: LuaRecipe [RW] Current recipe being assembled by this machine.
held_stack :: LuaItemStack [R] The item stack currently held in an inserter's hand.
train :: LuaTrain [R] The train this rolling stock belongs to.
neighbours :: dictionary stringarray of LuaEntity or array of LuaEntity or LuaEntity [R]
fluidbox :: LuaFluidBox [RW]
backer_name :: string [RW] The name of a backer (of Factorio) assigned to a lab or train station / stop.
time_to_live :: uint [RW] The ticks left for a ghost entity before it's destroyed.
color :: Color [RW] The character's color.
signal_state :: signal_state [R] The state of this rail signal.
chain_signal_state :: uint [R] The state of this chain signal.
to_be_looted :: boolean [RW] Will this entity be picked up automatically when the player walks over it?
crafting_progress :: float [R] The current crafting progress, as a number in range [0, 1].
bonus_progress :: float [R] The current productivity bonus progress, as a number in range [0, 1].
belt_to_ground_type :: string [R] "input" or "output", depending on whether this underground belt goes down or up.
rocket_parts :: uint [RW] Number of rocket parts in the silo.
logistic_network :: LuaLogisticNetwork [R] The logistic network this entity is a part of.
logistic_cell :: LuaLogisticCell [R] The logistic cell this entity is a part of.
unit_group :: LuaUnitGroup [R] The unit group this unit is a member of, or nil if none.
force :: string or LuaForce [RW] The force of this entity.
surface :: LuaSurface [R] The surface this entity is currently on.
position :: Position [R] Current position of the entity.

The primary interface for interacting with entities through the Lua API. Entity is everything on the map except tiles.

get_output_inventory() → LuaInventory

Gets the entities output inventory if it has one.

Return value
a reference to the entities output inventory.
get_module_inventory() → LuaInventory

Return value
Inventory for storing modules of this entity; nil if this entity has no module inventory.
damage(damage, force, type) → float

Damages the entity.

Parameters
damage :: float: The amount of damage to be done
force :: string or LuaForce: The force that will be doing the damage.
type :: string (optional): The type of damage to be done.
Return value
the total damage actually applied after resistances.
Can only be used if this is EntityWithHealth
destroy() → boolean

Destroys the entity.

Return value
if the entity was actually destroyed.
Note: Not all entities can be destroyed - things such as rails under trains cannot be destroyed until the train is moved or destroyed.
set_command(command)

Give the entity a command.

Parameters
command :: Command
Can only be used if this is Unit
has_command() → boolean

Has this unit been assigned a command?

Can only be used if this is Unit
die()

Immediately kills the entity. Doesn't attribute the kill to any force. Doesn't care whether the entity is destroyable or damageable. Error is thrown when called on entity that doesn't have health. Unlike LuaEntity::destroy, die will trigger on_entity_died and the entity will drop loot and corpse if it have any.

has_flag(flag) → boolean

Test whether this entity's prototype has a flag set.

Parameters
flag :: string: The flag to test
Return value
true if the entity has the given flag set.
Note: entity.has_flag(f) is a shortcut for entity.prototype.has_flag(f).
add_market_item{price=…, offer=…}

Offer a thing on the market.

Parameters
Table with the following fields:
  • price: list of prices, every element is 2 item table, first is the item name, the second is count.
  • offer :: Modifier: The action that will take place when a player accepts the offer. Usuallly a "give-item" modifier.
Example
Adds market offer, 1 copper ore for 10 iron ore.
market.add_market_item{price={{"iron-ore", 10}}, offer={type="give-item", item="copper-ore"}}
Example
Adds market offer, 1 copper ore for 5 iron ore and 5 stone ore.
market.add_market_item{price={{"iron-ore", 5}, {"stone", 5}}, offer={type="give-item", item="copper-ore"}}
Can only be used if this is Market
remove_market_item(offer) → boolean

Remove an offer from a market.

Parameters
offer :: uint: Index of offer to remove.
Return value
true if the offer was successfully removed; false when the given index was not valid.
Can only be used if this is Market
get_market_items() → array of Offer

Get all offers in a market as an array.

Return value
See LuaEntity::add_market_item for the format of an Offer.
Can only be used if this is Market
connect_neighbour(target)

Connect two devices with wire or cable.

Parameters
target :: LuaEntity or table:
  • To connect two electric poles, target has to be a LuaEntity specifying another electric pole. This will connect them with copper cable.
  • To connect two devices with wire, this parameter is a table:
disconnect_neighbour(target)

Disconnect wires or cables.

Parameters
target :: defines.circuitconnector or LuaEntity or table (optional):
order_deconstruction(force)

Sets the entity to be deconstructed by construction robots.

Parameters
force :: string or LuaForce: The force whose robots are supposed to do the deconstruction.
cancel_deconstruction(force)

Cancels deconstruction if it is scheduled, does nothing otherwise.

Parameters
force :: string or LuaForce: The force who did the deconstruction order.
to_be_deconstructed(force) → boolean

Is this entity marked for deconstruction?

Parameters
force :: string or LuaForce: The force which ordered the deconstruction. This parameter is is currently unused; it exists only for forward compatibility of the API.
get_filter(slot) → string

Get the filter for a slot.

Parameters
slot :: uint: Slot to get the filter of.
Return value
Prototype name of the entity being filtered; nil if the given slot has no filter.
Note: If called on an inserter, that inserter must allow filters (i.e. it must be a smart inserter).
Can only be used if this is Inserter or CargoWagon
set_filter(filter, slot)

Set the filter for a slot.

Parameters
filter :: string: Prototype name of the entity to filter.
slot :: uint: Slot to set the filter of.
Note: If called on an inserter, that inserter must allow filters (i.e. it must be a smart inserter).
Example
Make the 2nd slot only accept iron plates:
entity.set_filter("iron-plate", 2)
Can only be used if this is Inserter or CargoWagon
clear_filter(slot)

Clear the filter for a slot.

Parameters
slot :: uint: The slot to clear.
Note: If called on an inserter, that inserter must allow filters (i.e. it must be a smart inserter).
Example
Make a slot accept anything:
entity.clear_filter(2)
Can only be used if this is Inserter or CargoWagon
get_request_slot(slot) → LuaItemStack

Get a logistic requester slot.

Parameters
slot :: uint: The slot index.
Return value
Contents of the specified slot; nil if the given slot contains no request.
Note: Useable only on entities that have requester slots.
set_request_slot(request, slot)

Set a logistic requester slot.

Parameters
request :: SimpleItemStack: What to request.
slot :: uint: The slot index.
Note: Useable only on entities that have requester slots.
clear_request_slot(slot)

Clear a logistic requester slot.

Parameters
slot :: uint: The slot index.
Note: Useable only on entities that have requester slots.
get_circuit_condition(connector)

Parameters
Return value
Either nil if the entity has no circuit condition with the given index, or the following table:
Note: Either both condition and fulfilled fields are present, or only the parameters field is present, depending on the type of the entity this function was called on.
Example
local currentCondition = inserter.get_circuit_condition(defines.circuitconditionindex.inserter_circuit)
currentCondition.count = currentCondition.count + 10
inserter.set_circuit_condition(defines.circuitconditionindex.inserter_circuit, currentCondition)
set_circuit_condition(connector, condition_or_parameters)

Parameters
condition_or_parameters: Table with the following fields:
Note: condition may be nil in order to clear the circuit condition.
Example
Tell a certain lamp to be lit when it receives a signal of more than 4 chain signals.
a_lamp.set_circuit_condition(defines.circuitconditionindex.lamp,
                             {condition={comparator=">",
                                         first_signal={type="item", name="rail-chain-signal"},
                                         constant=4}})
Example
Instruct an arithmetic combinator to subtract the value of light oil from the value of stone, and output the difference as virtual signal 4.
a_combinator.set_circuit_condition(defines.circuitconditionindex.arithmetic_combinator,
                                   {parameters={first_signal={type="item", name="stone"},
                                                second_signal={type="fluid", name="light-oil"},
                                                operation="-",
                                                output_signal={type="virtual", name="signal-4"}}})
is_crafting() → boolean

Return value
true if this machine is currently crafting.
Can only be used if this is CraftingMachine
is_opened() → boolean

Return value
true if this gate is currently opened.
Can only be used if this is Gate
is_opening() → boolean

Return value
true if this gate is currently opening.
Can only be used if this is Gate
is_closed() → boolean

Return value
true if this gate is currently closed.
Can only be used if this is Gate
is_closing() → boolean

Return value
true if this gate is currently closing
Can only be used if this is Gate
request_to_open(force, extra_time)

Parameters
force :: string or LuaForce: The force that requests the gate to be open.
extra_time :: uint (optional): Extra ticks to stay open.
Can only be used if this is Gate
request_to_close(force)

Parameters
force :: string or LuaForce: The force that requests the gate to be closed.
Can only be used if this is Gate
get_transport_line(index) → LuaTransportLine

Get a transport line of a belt.

Parameters
index :: uint: Index of the requested transport line.
Can only be used if this is TransportBeltConnectable
launch_rocket() → boolean

Return value
true if the rocket was successfully launched. Return value of false means the silo is not ready for launch.
Can only be used if this is RocketSilo
revive() → uint

Revive a ghost. I.e. turn it from a ghost to a real entity.

Return value
Number of items the items the new real entity collided with or nil if the ghost could not be revived.
get_connected_rail{rail_direction=…, rail_connection_direction=…} → LuaEntity

Parameters
Table with the following fields:
Return value
Rail connected in the specified manner to this one.
Can only be used if this is Rail
get_inventory(inventory) → LuaInventory

Get an inventory belonging to this entity. This can be either the "main" inventory or some auxiliary one, like the module slots or logistic trash slots.

Parameters
inventory :: defines.inventory
can_insert(items) → boolean

Can at least some items be inserted?

Parameters
items :: SimpleItemStack: Items that would be inserted.
Return value
true if at least a part of the given items could be inserted into this inventory.
insert(items) → uint

Insert items into this entity. This works the same way as inserters or shift-clicking: the "best" inventory is chosen automatically.

Parameters
items :: SimpleItemStack: Items to insert.
Return value
Number of items actually inserted.
get_item_count(item) → uint

Get the number of all or some items in this entity.

Parameters
item :: string (optional): Prototype name of the item to count. If not specified, count all items.
has_items_inside() → boolean

Does this entity have any item inside it?

clear_items_inside()

Remove all items from this entity.

remove_item(items) → uint

Remove items from this entity.

Parameters
items :: SimpleItemStack: Items to remove.
Return value
Number of items actually removed.
teleport(position, surface) → boolean

Teleport the entity to a given position, possibly on another surface.

Parameters
position :: Position: Where to teleport to.
surface :: SurfaceSpecification (optional): Surface to teleport to. If not given, will teleport to the entity's current surface.
Return value
true when the entity was successfully teleported.
Note: Some entities may not be teleported. For instance, walls, rail signals or entities with fluid boxes won't allow teleportation and this method will always return false when used on any such entity.
valid :: boolean [Read-only]

Is this object valid? This Lua object holds a reference to an object within the game engine. It is possible that the game-engine object is removed whilst a mod still holds the corresponding Lua object. If that happens, the object becomes invalid, i.e. this attribute will be false. Mods are advised to check for object validity if any change to the game state might have occurred between the creation of the Lua object and its access.

passenger :: LuaEntity [Read-Write]

Setting to nil forces the character out of the vehicle, setting to a new character forces any existing passenger out and the given character becomes the new passenger.

Note: May be nil if the car contains no passenger.
Can only be used if this is Vehicle
name :: string [Read-only]

Name of the entity prototype. E.g. "inserter" or "smart-inserter".

ghost_name :: string [Read-only]

Name of the entity contained in this ghost

Can only be used if this is Ghost
localised_name :: LocalisedString [Read-only]

Localised name of the entity.

ghost_localised_name :: LocalisedString [Read-only]

Localised name of the entity contained in this ghost.

Can only be used if this is Ghost
type :: string [Read-only]

The entity prototype type of this entity.

ghost_type :: string [Read-only]

The prototype type of the entity contained in this ghost.

Can only be used if this is Ghost
active :: boolean [Read-Write]

Deactivating an entity will stop all its operations (car will stop moving, inserters will stop working, fish will stop moving etc).

Note: Entities that are are not active naturally can't be set to be active (setting it to be active will do nothing)
Note: It is even possible to set the player to not be active, so he can't move and perform most of the tasks.
destructible :: boolean [Read-Write]

When the entity is not destructible it can't be damaged.

Note: An indestructible entity can still be mined.
Note: Entities that are indestructible naturally (they have no health, like smoke, resource etc) can't be set to be destructible.
minable :: boolean [Read-Write]

Note: Not minable entities can still be destroyed.
Note: Entities that are not minable naturally (like smoke, player, enemy units etc) can't be set to minable.
rotatable :: boolean [Read-Write]

When entity is not to be rotatable (inserter, transport belt etc), it can't be rotated by player using the R key.

Note: Entities that are not rotatable naturally (like chest or furnace) can't be set to be rotatable.
operable :: boolean [Read-Write]

Player can't open gui of this entity and he can't quick insert/input stuff in to the entity when it is not operable.

health :: float [Read-Write]

Health of the entity. Setting health to less than 0 will set health to 0, entities with 0 health can not be attacked. Setting health to higher than max health will set health to max health.

Note: If used on an entity that doesn't support health, this field will be nil.
direction :: defines.direction [Read-Write]

The current direction this entity is facing.

orientation :: float [Read-Write]

The smooth orientation.

amount :: uint [Read-Write]

Count of resource units contained.

Can only be used if this is ResourceEntity
effectivity_modifier :: float [Read-Write]

Multiplies the acceleration the vehicle can create for one unit of energy. By default is 1.

Can only be used if this is Car
consumption_modifier :: float [Read-Write]

Multiplies the the energy consumption.

Can only be used if this is Car
friction_modifier :: float [Read-Write]

Multiplies the car friction rate.

Example
This will allow the car to go much faster
game.player.vehicle.friction_modifier = 0.5
Can only be used if this is Car
speed :: float [Read-Write]

The current speed of the car.

Can only be used if this is Car
stack :: LuaItemStack [Read-only]

Can only be used if this is ItemEntity
prototype :: LuaEntityPrototype [Read-only]

The entity prototype of this entity.

ghost_prototype :: LuaEntityPrototype [Read-only]

The entity prototype of the entity contained in this ghost.

Can only be used if this is Ghost
drop_position :: Position [Read-only]

Position where the entity puts its stuff.

Note: Meaningful only for entities that put stuff somewhere, such as mining drills or inserters.
drop_target :: LuaEntity [Read-only]

The entity this entity is putting its stuff to or nil if there is no such entity.

Note: Meaningful only for entities that put stuff somewhere, such as mining drills or inserters.
selected_gun_index :: uint [Read-Write]

Index of the currently selected weapon slot of this character.

Can only be used if this is Character
energy :: float [Read-Write]

Energy stored in the entity (heat in furnace, energy stored in electrical devices etc.). always 0 for entities that don't have the concept of energy stored inside.

Example
game.player.print("Machine energy: " .. game.player.selected.energy .. "J")
game.player.selected.energy = 3000
recipe :: LuaRecipe [Read-Write]

Current recipe being assembled by this machine.

Can only be used if this is AssemblingMachine
held_stack :: LuaItemStack [Read-only]

The item stack currently held in an inserter's hand.

Can only be used if this is Inserter
train :: LuaTrain [Read-only]

The train this rolling stock belongs to.

Can only be used if this is RollingStock
neighbours :: dictionary stringarray of LuaEntity or array of LuaEntity or LuaEntity [Read-only]

  • When called on an electric pole, this is a dictionary of all connections, indexed by the strings "copper", "red", and "green".
  • When called on a pipe-connectable entity, this is an array of all entities this pipe is connected to.
  • When called on an underground transport belt, this is the other end of the underground belt connection, or nil if none.

fluidbox :: LuaFluidBox [Read-Write]

backer_name :: string [Read-Write]

The name of a backer (of Factorio) assigned to a lab or train station / stop.

Note: Only useable on entities that support backer names.
time_to_live :: uint [Read-Write]

The ticks left for a ghost entity before it's destroyed. Cannot be set higher than LuaForce::ghost_time_to_live of the entity's force.

Can only be used if this is Ghost
color :: Color [Read-Write]

The character's color.

Can only be used if this is Character
signal_state :: signal_state [Read-only]

The state of this rail signal.

Can only be used if this is RailSignal
chain_signal_state :: uint [Read-only]

The state of this chain signal.

Can only be used if this is RailChainSignal
to_be_looted :: boolean [Read-Write]

Will this entity be picked up automatically when the player walks over it?

Can only be used if this is ItemEntity
crafting_progress :: float [Read-only]

The current crafting progress, as a number in range [0, 1].

Can only be used if this is CraftingMachine
bonus_progress :: float [Read-only]

The current productivity bonus progress, as a number in range [0, 1].

Can only be used if this is CraftingMachine
belt_to_ground_type :: string [Read-only]

"input" or "output", depending on whether this underground belt goes down or up.

Can only be used if this is TransportBeltToGround
rocket_parts :: uint [Read-Write]

Number of rocket parts in the silo.

Can only be used if this is RocketSilo
logistic_network :: LuaLogisticNetwork [Read-only]

The logistic network this entity is a part of.

logistic_cell :: LuaLogisticCell [Read-only]

The logistic cell this entity is a part of.

unit_group :: LuaUnitGroup [Read-only]

The unit group this unit is a member of, or nil if none.

Can only be used if this is Unit
force :: string or LuaForce [Read-Write]

The force of this entity. Reading will always give a LuaForce, but it is possible to assign either string or LuaForce to this attribute to change the entity's force.

surface :: LuaSurface [Read-only]

The surface this entity is currently on.

position :: Position [Read-only]

Current position of the entity.