Factorio API Docs

1.1.53 <>

Class LuaEntity extends LuaControl

The primary interface for interacting with entities through the Lua API. Entities are everything that exists on the map except for tiles (see LuaTile).

Most functions on LuaEntity also work when the entity is contained in a ghost.

Gets the entities output inventory if it has one.



The fuel inventory for this entity or nil if this entity doesn't have a fuel inventory.


The burnt result inventory for this entity or nil if this entity doesn't have a burnt result inventory.


damage(damage, force, type, dealer)
float

Damages the entity.


boolean

Checks if the entity can be destroyed


destroy{do_cliff_correction, raise_destroy}
boolean

Destroys the entity.


set_command(command)

Give the entity a command.


Give the entity a distraction command.


boolean

Has this unit been assigned a command?


die(force, cause)
boolean

Immediately kills the entity.


has_flag(flag)
boolean

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


boolean

Same as LuaEntity::has_flag, but targets the inner entity on a entity ghost.


Offer a thing on the market.


boolean

Remove an offer from a market.


→ array[Offer]

Get all offers in a market as an array.


Removes all offers from a market.


boolean

Connect two devices with a circuit wire or copper cable.


Disconnect circuit wires or copper cables between devices.


order_deconstruction(force, player)
boolean

Sets the entity to be deconstructed by construction robots.


cancel_deconstruction(force, player)

Cancels deconstruction if it is scheduled, does nothing otherwise.


boolean

Is this entity marked for deconstruction?


order_upgrade{force, target, player, direction}
boolean

Sets the entity to be upgraded by construction robots.


cancel_upgrade(force, player)
boolean

Cancels upgrade if it is scheduled, does nothing otherwise.


boolean

Is this entity marked for upgrade?


Get a logistic requester slot.


set_request_slot(request, slot)
boolean

Set a logistic requester slot.


Clear a logistic requester slot.


Returns whether a craft is currently in process.






request_to_open(force, extra_time)


Get a transport line of a belt or belt connectable entity.


uint

Get the maximum transport line index of a belt or belt connectable entity.



revive{return_item_request_proxy, raise_revive}
→ dictionary[stringuint]

Revive a ghost.


silent_revive{return_item_request_proxy, raise_revive}
→ dictionary[stringuint]

Revives a ghost silently.


get_connected_rail{rail_direction, rail_connection_direction}
LuaEntity

→ array[LuaEntity]

Get the rails that this signal is connected to.


get_rail_segment_entity(direction, in_else_out)
LuaEntity

Get the rail signal or train stop at the start/end of the rail segment this rail is in, or nil if the rail segment doesn't start/end with a signal nor a train stop.


LuaEntity

Get the rail at the end of the rail segment this rail is in.


double

Get the length of the rail segment this rail is in.


→ array[LuaEntity]

Get a rail from each rail segment that overlaps with this rail's rail segment.


get_filter(slot_index)
string

Get the filter for a slot in an inserter, loader, or logistic storage container.


set_filter(slot_index, item)

Set the filter for a slot in an inserter, loader, or logistic storage container.


Gets the filter for this infinity container at the given index or nil if the filter index doesn't exist or is empty.


Sets the filter for this infinity container at the given index.


Gets the filter for this infinity pipe or nil if the filter is empty.


Sets the filter for this infinity pipe.


Gets the heat setting for this heat interface.


Sets the heat setting for this heat interface.


Gets the control behavior of the entity (if any).


Gets (and or creates if needed) the control behavior of the entity.


get_circuit_network(wire, circuit_connector)

get_merged_signal(signal, circuit_connector)
int

Read a single signal from the combined circuit networks.


get_merged_signals(circuit_connector)
→ array[Signal]

The merged circuit network signals or nil if there are no signals.


boolean

Whether this entity supports a backer name.


copy_settings(entity, by_player)
→ dictionary[stringuint]

Copies settings from the given entity onto this entity.


Gets all the LuaLogisticPoints that this entity owns.


play_note(instrument, note)
boolean

Plays a note with the given instrument and note.


boolean

Connects the rolling stock in the given direction.


boolean

Tries to disconnect this rolling stock in the given direction.


Reconnect loader, beacon, cliff and mining drill connections to entities that might have been teleported out or in by the script.


LuaRecipe

Current recipe being assembled by this machine or nil if no recipe is set.


set_recipe(recipe)
→ dictionary[stringuint]

Sets the current recipe in this assembly machine.


rotate{reverse, by_player, spill_items, enable_looted, force}
boolean

Rotates this entity as if the player rotated it.


Gets the driver of this vehicle if any.


set_driver(driver)

Sets the driver of this vehicle.


Gets the passenger of this car or spidertron if any.


set_passenger(passenger)

Sets the passenger of this car or spidertron.


boolean

Returns true if this entity is connected to an electric network.


→ array[LuaTrain]

The trains scheduled to stop at this train stop.


LuaTrain

The train currently stopped at this train stop or nil if none.


clone{position, surface, force, create_build_effect_smoke}
LuaEntity

Clones this entity.


double

Get the amount of all or some fluid in this entity.


→ dictionary[stringdouble]

Get amounts of all fluids in this entity.


remove_fluid{name, amount, minimum_temperature, maximum_temperature, temperature}
double

Remove fluid from this entity.


insert_fluid(fluid)
double

Insert fluid into this entity.


Remove all fluids from this entity.


Get the source of this beam.


set_beam_source(source)

Set the source of this beam.


Get the target of this beam.


set_beam_target(target)

Set the target of this beam.


double

The radius of this entity.


float

The health ratio of this entity between 1 and 0 (for full health and no health respectively).


Creates the same smoke that is created when you place a building by hand.


Release the unit from the spawner which spawned it.


Toggle this entity's equipment movement bonus.


can_shoot(target, position)
boolean

If this character can shoot the given entity or position.


Only works if the entity is a speech-bubble, with an "effect" defined in its wrapper_flow_style.


Returns the new entity prototype.


Returns the new entity direction after upgrading.


float

Returns the amount of damage to be taken by this entity.


Depletes and destroys this resource entity.


mine{inventory, force, raise_destroyed, ignore_minable}
boolean

Mines this entity.


Triggers spawn_decoration actions defined in the entity prototype or does nothing if entity is not "turret" or "unit-spawner".


can_wires_reach(entity)
boolean

Can wires reach between these entities.


LuaEntity

Gets rolling stock connected to the given end of this stock


boolean

Is this entity or tile ghost or item request proxy registered for construction?


boolean

Is this entity registered for deconstruction with this force?


boolean

Is this entity registered for upgrade?


boolean

Is this entity registered for repair?


Adds the given position to this spidertron's autopilot's queue of destinations.


Connects current linked belt with another one.


Disconnects linked belt from its neighbour.


→ array[LuaEntity]

Gets legs of given SpiderVehicle.


help()
string

All methods and properties that this object supports.


:: string
[R]

Name of the entity prototype.


:: string
[R]

Name of the entity or tile contained in this ghost


[R]

Localised name of the entity.



[R]

Localised name of the entity or tile contained in this ghost.



:: string
[R]

The entity prototype type of this entity.


:: string
[R]

The prototype type of the entity or tile contained in this ghost.


:: boolean
[RW]

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


:: boolean
[RW]

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


:: boolean
[RW]

:: boolean
[RW]

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


:: 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.


:: float
[RW]

The current health of the entity, or nil if it doesn't have health.


[RW]

The current direction this entity is facing.


:: boolean
[R]

Whether the entity has direction.


[RW]

The smooth orientation of this entity, if it supports orientation.


[R]

The orientation of this cliff.


[RW]

The relative orientation of the vehicle turret, artillery turret, artillery wagon or nil if this entity isn't a vehicle with a vehicle turret or artillery turret/wagon.


[RW]

The torso orientation of this spider vehicle.


:: uint
[RW]

Count of resource units contained.


:: uint
[RW]

Count of initial resource units contained.


:: float
[RW]

Multiplies the acceleration the vehicle can create for one unit of energy.


:: float
[RW]

Multiplies the energy consumption.


:: float
[RW]

Multiplies the car friction rate.


:: boolean
[RW]

Whether the driver of this car or spidertron is the gunner, if false, the passenger is the gunner.


[RW]

Read when this spidertron auto-targets enemies


:: float
[RW]

The current speed of this car in tiles per tick, rolling stock, projectile or spider vehicle, or current max speed of the unit.


:: float
[R]

The current speed of this unit in tiles per tick, taking into account any walking speed modifier given by the tile the unit is standing on.



[R]

The entity prototype of this entity.


[R]

The prototype of the entity or tile contained in this ghost.


[RW]

Position where the entity puts its stuff.


[RW]

Where the inserter will pick up items from.


[RW]

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


[RW]

The entity this inserter will attempt to pick up items from, or nil if there is no such entity.


:: uint
[RW]

Index of the currently selected weapon slot of this character, car, or spidertron, or nil if the car/spidertron doesn't have guns.


:: double
[RW]

Energy stored in the entity (heat in furnace, energy stored in electrical devices etc.).


:: double
[RW]

The temperature of this entities heat energy source if this entity uses a heat energy source or nil.


[R]

The previous recipe this furnace was using or nil if the furnace had no previous recipe.


[R]

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


[R]

Current position of the inserter's "hand".


[R]

The train this rolling stock belongs to or nil if not rolling stock.


:: dictionary[string → array[LuaEntity]] or array[array[LuaEntity]] or LuaEntity
[R]
  • When called on an electric pole, this is a dictionary of all connections, indexed by the strings "copper", "red", and "green".

:: dictionary[string → array[LuaEntity]]
[R]

The belt connectable neighbours of this belt connectable entity.


[RW]

Fluidboxes of this entity.


:: string
[RW]

The backer name assigned to this entity, or nil if this entity doesn't support backer names.


:: string
[RW]

The label of this entity if it has one or nil.


:: uint
[RW]

The ticks left before a ghost, combat robot, highlight box or smoke with trigger is destroyed.


:: Color
[RW]

The character, rolling stock, train stop, car, spider-vehicle, flying text, corpse or simple-entity-with-owner color.


[RW]

The text of this flying-text entity.


[R]

The state of this rail signal.


[R]

The state of this chain signal.


:: boolean
[RW]

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


:: double
[R]

The current crafting speed, including speed bonuses from modules and beacons.


:: float
[RW]

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


:: double
[RW]

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


:: double
[R]

The productivity bonus of this entity.


:: double
[R]

The pollution bonus of this entity.


:: double
[R]

The speed bonus of this entity.


:: double
[R]

The consumption bonus of this entity.


:: string
[R]

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


:: string
[RW]

"input" or "output", depending on whether this loader puts to or gets from a container.


:: uint
[RW]

Number of rocket parts in the silo.


[RW]

The logistic network this entity is a part of.


[R]

The logistic cell this entity is a part of.


:: dictionary[stringuint]
[RW]

Items this ghost will request when revived or items this item request proxy is requesting.


[R]

The player connected to this character or nil if none.


[R]

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


:: double
[RW]

The damage dealt by this turret, artillery turret, or artillery wagon.


:: uint
[RW]

The number of units killed by this turret, artillery turret, or artillery wagon.


[RW]

The last player that changed any setting on this entity.


:: double
[RW]

The buffer size for the electric energy source or nil if the entity doesn't have an electric energy source.


:: double
[R]

The input flow limit for the electric energy source or nil if the entity doesn't have an electric energy source.


:: double
[R]

The output flow limit for the electric energy source or nil if the entity doesn't have an electric energy source.


:: double
[R]

The electric drain for the electric energy source or nil if the entity doesn't have an electric energy source.


:: double
[R]

The emissions for the electric energy source or nil if the entity doesn't have an electric energy source.


:: uint
[R]

The unit number or nil if the entity doesn't have one.


:: uint
[R]

The unit number of the entity contained in this ghost or nil if the entity doesn't have one.


:: double
[RW]

The mining progress for this mining drill or nil if this isn't a mining drill.


:: double
[RW]

The bonus mining progress for this mining drill or nil if this isn't a mining drill.


:: double
[RW]

The power production specific to the ElectricEnergyInterface entity type.


:: double
[RW]

The power usage specific to the ElectricEnergyInterface entity type.


[R]

LuaEntityPrototype::collision_box around entity's given position and respecting the current entity orientation.


[R]

The secondary bounding box of this entity or nil if it doesn't have one.


[R]

LuaEntityPrototype::selection_box around entity's given position and respecting the current entity orientation.


[R]

The secondary selection box of this entity or nil if it doesn't have one.


[R]

The mining target or nil if none


:: table
[R]

Entities that are directly connected to this entity via the circuit network.


[R]

The connection definition for entities that are directly connected to this entity via the circuit network.


:: uint
[R]

The index of the configured request with the highest index for this entity.


:: uint
[R]

The number of filter slots this inserter, loader, or logistic storage container has.


[R]

The container entity this loader is pointing at/pulling from depending on the LuaEntity::loader_type.


[R]

The equipment grid or nil if this entity doesn't have an equipment grid.


:: uint8
[RW]

The graphics variation for this entity or nil if this entity doesn't use graphics variations.


:: uint8
[RW]

Index of the tree color.


:: uint8
[R]

Maximum index of the tree colors.


:: uint8
[RW]

Index of the tree stage.


:: uint8
[R]

Maximum index of the tree stages.


:: uint8
[RW]

Index of the tree gray stage


:: uint8
[R]

Maximum index of the tree gray stages.


[R]

The burner energy source for this entity or nil if there isn't one.


[RW]

The shooting target for this turret or nil.


[R]

The target entity for this item-request-proxy or nil


:: array[LuaEntity]
[R]

The sticker entities attached to this entity or nil if none.


[R]

The entity this sticker is sticked to.




[R]

The electric network statistics for this electric pole.


:: uint
[RW]

Sets the stack size limit on this inserter.


:: uint
[RW]

The number of products this machine finished crafting in its lifetime.


[R]

The spawner associated with this unit entity or nil if the unit has no associated spawner.


:: array[LuaEntity]
[R]

The units associated with this spawner entity.


:: boolean
[RW]

The state of this power switch.


[R]

The effects being applied to this entity or nil.


[RW]

The filters for this infinity container.


:: boolean
[RW]

If items not included in this infinity container filters should be removed from the container.


:: uint
[RW]

The player index associated with this character corpse.


:: uint
[RW]

The tick this character corpse died at.


[RW]

The reason this character corpse character died (if any).


[RW]

The player this character is associated with or nil if none.


:: uint
[RW]

The last tick this character entity was attacked.


:: uint
[RW]

The last tick this character entity was damaged.


[RW]

The filter for this splitter or nil if no filter is set.


:: string
[RW]

The filter mode for this filter inserter: "whitelist", "blacklist", or nil if this inserter doesn't use filters.


:: string
[RW]

The input priority for this splitter : "left", "none", or "right".


:: string
[RW]

The output priority for this splitter : "left", "none", or "right".


:: boolean
[R]

If this land mine is armed.


:: boolean
[RW]

When locked; the recipe in this assembling machine can't be changed by the player.


[R]

The rail entity this train stop is connected to or nil if there is none.


[R]

Rail direction to which this train stop is binding.


:: uint
[R]

The number of trains in this rail block for this rail entity.


:: uint
[RW]

The timeout that's left on this landmine in ticks.


:: double
[R]

The current total neighbour bonus of this reactor.


[R]

The ai settings of this unit.


:: string
[RW]

The hightlight box type of this highlight box entity.


:: uint
[RW]

The blink interval of this highlight box entity.


[R]

The status of this entity or nil if no status.


:: boolean
[RW]

If equipment grid logistics are enabled while this vehicle is moving.


[RW]

The player that this simple-entity-with-owner, simple-entity-with-force, flying-text, or highlight-box is visible to.


[RW]

The forces that this simple-entity-with-owner, simple-entity-with-force, or flying-text is visible to.


[R]

The rail target of this pump or nil.


:: boolean
[R]

Returns true if this unit is moving.


:: uint
[R]

Returns the id of the electric network that this entity is connected to or nil.


:: boolean
[RW]

Whether this character's personal roboports are allowed to dispatch robots.


:: boolean
[RW]

Whether this rocket silo automatically launches the rocket when cargo is inserted.


:: double
[R]

How much energy this generator generated in the last tick.


[RW]

The storage filter for this logistic storage container.


:: boolean
[RW]

Whether this requester chest is set to also request from buffer chests.


:: boolean
[RW]

Whether this corpse will ever fade away.


:: boolean
[RW]

If true, corpse won't be destroyed when entities are placed over it.


:: Tags
[RW]

The tags associated with this entity ghost or nil if not an entity ghost.


:: Command
[R]

The command given to this unit or nil is the unit has no command.


:: Command
[R]

The distraction command given to this unit or nil is the unit currently isn't distracted.


:: uint
[RW]

The ticks until the next trigger effect of this smoke-with-trigger.


[RW]

Destination position of spidertron's autopilot.


:: array[MapPosition]
[R]

The queued destination positions of spidertron's autopilot.


:: uint
[R]

Amount of trains related to this particular train stop.


:: uint
[RW]

Amount of trains above which no new trains will be sent to this train stop.


:: boolean
[R]

(deprecated by 1.1.51) If this entity is a MilitaryTarget.


:: boolean
[RW]

If this entity is a MilitaryTarget.


:: boolean
[R]

If this entity is EntityWithOwner


:: boolean
[R]

If this entity is EntityWithHealth


[RW]

The owner of this combat robot if any.


:: uint
[RW]

The link ID this linked container is using.


[RW]

The follow target of this spidertron if any.


[RW]

The follow offset of this spidertron if any.


:: string
[RW]

Type of linked belt: it is either "input" or "output".


[R]

Neighbour to which this linked belt is connected to.


:: boolean
[R]

Is this object valid?


:: string
[R]

The class name of this object.


Inherited from LuaControl: surface, position, vehicle, force, selected, opened, crafting_queue_size, crafting_queue_progress, walking_state, riding_state, mining_state, shooting_state, picking_state, repair_state, cursor_stack, cursor_ghost, driving, crafting_queue, following_robots, cheat_mode, character_crafting_speed_modifier, character_mining_speed_modifier, character_additional_mining_categories, character_running_speed_modifier, character_build_distance_bonus, character_item_drop_distance_bonus, character_reach_distance_bonus, character_resource_reach_distance_bonus, character_item_pickup_distance_bonus, character_loot_pickup_distance_bonus, character_inventory_slots_bonus, character_trash_slot_count_bonus, character_maximum_following_robot_count_bonus, character_health_bonus, character_personal_logistic_requests_enabled, vehicle_logistic_requests_enabled, opened_gui_type, build_distance, drop_item_distance, reach_distance, item_pickup_distance, loot_pickup_distance, resource_reach_distance, in_combat, character_running_speed, character_mining_progress, get_inventory, get_main_inventory, can_insert, insert, set_gui_arrow, clear_gui_arrow, get_item_count, has_items_inside, can_reach_entity, clear_items_inside, remove_item, teleport, update_selected_entity, clear_selected_entity, disable_flashlight, enable_flashlight, is_flashlight_enabled, get_craftable_count, begin_crafting, cancel_crafting, mine_entity, mine_tile, is_player, open_technology_gui, set_personal_logistic_slot, set_vehicle_logistic_slot, get_personal_logistic_slot, get_vehicle_logistic_slot, clear_personal_logistic_slot, clear_vehicle_logistic_slot, is_cursor_blueprint, get_blueprint_entities, is_cursor_empty

Methods

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.


get_fuel_inventory () → LuaInventory

The fuel inventory for this entity or nil if this entity doesn't have a fuel inventory.


get_burnt_result_inventory () → LuaInventory

The burnt result inventory for this entity or nil if this entity doesn't have a burnt result inventory.


damage (damage, force, type, dealer) → float

Damages the entity.

Parameters

damage
:: float

The amount of damage to be done


force

The force that will be doing the damage.


type
:: string
Optional

The type of damage to be done, defaults to "impact".


dealer
Optional

The entity to consider as the damage dealer.

Return value

the total damage actually applied after resistances.

Can only be used if this is EntityWithHealth

can_be_destroyed () → boolean

Checks if the entity can be destroyed

Return value

if the entity can be destroyed.


destroy {do_cliff_correction, raise_destroy} → boolean

Destroys the entity.

Parameters

Table (optional) with the following fields:
do_cliff_correction
:: boolean
Optional

Whether neighbouring cliffs should be corrected. Defaults to false.


raise_destroy
:: boolean
Optional

If true, script_raised_destroy will be called. Defaults to false.

Return value

Returns false if the entity was valid and destruction failed, true in all other cases.

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

set_distraction_command (command)

Give the entity a distraction 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 (force, cause) → boolean

Immediately kills the entity. Does nothing if the entity doesn't have health.

Unlike LuaEntity::destroy, die will trigger the on_entity_died event and the entity will produce a corpse and drop loot if it has any.

Parameters

force
Optional

The force to attribute the kill to.


cause
Optional

The cause to attribute the kill to.

Return value

Whether the entity was successfully killed.

Example

This function can be called with only the cause argument and no force:

entity.die(nil, killer_entity)

Note

If force is not specified, on_entity_died will blame the "neutral" force.


has_flag (flag) → boolean

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

Parameters

flag
:: string

The flag to test. See EntityPrototypeFlags for a list of flags.

Return value

true if this entity has the given flag set.

Note

entity.has_flag(f) is a shortcut for entity.prototype.has_flag(f).


ghost_has_flag (flag) → boolean

Same as LuaEntity::has_flag, but targets the inner entity on a entity ghost.

Parameters

flag
:: string

The flag to test. See EntityPrototypeFlags for a list of flags.

Return value

true if the entity has the given flag set.

Can only be used if this is EntityGhost

add_market_item (offer)

Offer a thing on the market.

Parameters

offer
:: Offer

Examples

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"}}

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.

Note

The other offers are moved down to fill the gap created by removing the offer, which decrements the overall size of the offer array.

Can only be used if this is Market

get_market_items () → array[Offer]

Get all offers in a market as an array.

Can only be used if this is Market

clear_market_items ()

Removes all offers from a market.

Can only be used if this is Market

connect_neighbour (target) → boolean

Connect two devices with a circuit wire or copper cable. Depending on which type of connection should be made, there are different procedures:

  • To connect two electric poles, target must be a LuaEntity that specifies another electric pole. This will connect them with copper cable.
  • To connect two devices with circuit wire, target must be a table of type WireConnectionDefinition.

Parameters

target

The target with which to establish a connection.

Return value

Whether the connection was successfully formed.


disconnect_neighbour (target)

Disconnect circuit wires or copper cables between devices. Depending on which type of connection should be cut, there are different procedures:

  • To remove all copper cables, leave the target parameter blank: pole.disconnect_neighbour().
  • To remove all wires of a specific color, set target to defines.wire_type.red or defines.wire_type.green.
  • To remove a specific copper cable between two electric poles, target must be a LuaEntity that specifies the other pole: pole1.disconnect_neighbour(pole2).
  • To remove a specific circuit wire, target must be a table of type WireConnectionDefinition.

Parameters

target
Optional

The target with which to cut a connection.


order_deconstruction (force, player) → boolean

Sets the entity to be deconstructed by construction robots.

Parameters

force

The force whose robots are supposed to do the deconstruction.


player
Optional

The player to set the last_user to if any.

Return value

if the entity was marked for deconstruction.


cancel_deconstruction (force, player)

Cancels deconstruction if it is scheduled, does nothing otherwise.

Parameters

force

The force who did the deconstruction order.


player
Optional

The player to set the last_user to if any.


to_be_deconstructed () → boolean

Is this entity marked for deconstruction?


order_upgrade {force, target, player, direction} → boolean

Sets the entity to be upgraded by construction robots.

Parameters

Table with the following fields:
force

The force whose robots are supposed to do the upgrade.


target

The prototype of the entity to upgrade to.


player
Optional

direction
Optional

The new direction if any.

Return value

if the entity was marked for upgrade.


cancel_upgrade (force, player) → boolean

Cancels upgrade if it is scheduled, does nothing otherwise.

Parameters

force

The force who did the upgrade order.


player
Optional

The player to set the last_user to if any.

Return value

If the cancel was successful.


to_be_upgraded () → boolean

Is this entity marked for upgrade?


get_request_slot (slot) → SimpleItemStack

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) → boolean

Set a logistic requester slot.

Parameters

request

What to request.


slot
:: uint

The slot index.

Return value

If the slot was set.

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.


is_crafting ()

Returns whether a craft is currently in process. It does not indicate whether progress is currently being made, but whether any crafting action has made progress in this machine.

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

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

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 or belt connectable entity.

Parameters

index
:: uint

Index of the requested transport line. Transport lines are 1-indexed.

Can only be used if this is TransportBeltConnectable

get_max_transport_line_index () → uint

Get the maximum transport line index of a belt or belt connectable entity.

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 {return_item_request_proxy, raise_revive} → dictionary[stringuint]

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

Parameters

Table (optional) with the following fields:
return_item_request_proxy
:: boolean
Optional

If true the function will return item request proxy as the third parameter.


raise_revive
:: boolean
Optional

If true, and an entity ghost; script_raised_revive will be called. Else if true, and a tile ghost; script_raised_set_tiles will be called.

Return value

Any items the new real entity collided with or nil if the ghost could not be revived.

Note

If this is an entity ghost and it is successfully revived this will also return the revived entity or nil as a second return value and possibly item request proxy as the third parameter depending on value of return_item_request_proxy.


silent_revive {return_item_request_proxy, raise_revive} → dictionary[stringuint]

Revives a ghost silently.

Parameters

Table (optional) with the following fields:
return_item_request_proxy
:: boolean
Optional

If true the function will return item request proxy as the third parameter.


raise_revive
:: boolean
Optional

If true, and an entity ghost; script_raised_revive will be called. Else if true, and a tile ghost; script_raised_set_tiles will be called.

Return value

Any items the new real entity collided with or nil if the ghost could not be revived.

Note

If this is an entity ghost and it is successfully revived this will also return the revived entity or nil as a second return value and possibly item request proxy as the third parameter depending on value of return_item_request_proxy.


get_connected_rail {rail_direction, rail_connection_direction} → LuaEntity

Parameters

Table with the following fields:
rail_direction

rail_connection_direction

Return value

Rail connected in the specified manner to this one.

Can only be used if this is Rail

get_connected_rails () → array[LuaEntity]

Get the rails that this signal is connected to.

Can only be used if this is RailSignal or RailChainSignal

get_rail_segment_entity (direction, in_else_out) → LuaEntity

Get the rail signal or train stop at the start/end of the rail segment this rail is in, or nil if the rail segment doesn't start/end with a signal nor a train stop.

Parameters

direction

The direction of travel relative to this rail.


in_else_out
:: boolean

If true, gets the entity at the entrance of the rail segment, otherwise gets the entity at the exit of the rail segment.

Note

A rail segment is a continuous section of rail with no branches, signals, nor train stops.

Can only be used if this is Rail

get_rail_segment_end (direction) → LuaEntity

Get the rail at the end of the rail segment this rail is in.

Parameters

direction

Notes

A rail segment is a continuous section of rail with no branches, signals, nor train stops.

This function has a second return value. A defines.rail_direction that points out of the rail segment from the end rail.

Can only be used if this is Rail

get_rail_segment_length () → double

Get the length of the rail segment this rail is in.

Note

A rail segment is a continuous section of rail with no branches, signals, nor train stops.

Can only be used if this is Rail

get_rail_segment_overlaps () → array[LuaEntity]

Get a rail from each rail segment that overlaps with this rail's rail segment.

Note

A rail segment is a continuous section of rail with no branches, signals, nor train stops.

Can only be used if this is Rail

get_filter (slot_index) → string

Get the filter for a slot in an inserter, loader, or logistic storage container.

Parameters

slot_index
:: uint

Index of the slot to get the filter for.

Return value

Prototype name of the item being filtered. nil if the given slot has no filter.

Note

The entity must allow filters.


set_filter (slot_index, item)

Set the filter for a slot in an inserter, loader, or logistic storage container.

Parameters

slot_index
:: uint

Index of the slot to set the filter for.


item
:: string

Prototype name of the item to filter.

Note

The entity must allow filters.


get_infinity_container_filter (index) → InfinityInventoryFilter

Gets the filter for this infinity container at the given index or nil if the filter index doesn't exist or is empty.

Parameters

index
:: uint

The index to get.

Can only be used if this is InfinityContainer

set_infinity_container_filter (index, filter)

Sets the filter for this infinity container at the given index.

Parameters

index
:: uint

The index to set.


filter

The new filter or nil to clear the filter.

Can only be used if this is InfinityContainer

get_infinity_pipe_filter () → InfinityPipeFilter

Gets the filter for this infinity pipe or nil if the filter is empty.

Can only be used if this is InfinityPipe

set_infinity_pipe_filter (filter)

Sets the filter for this infinity pipe.

Parameters

filter

The new filter or nil to clear the filter.

Can only be used if this is InfinityPipe

get_heat_setting () → HeatSetting

Gets the heat setting for this heat interface.

Can only be used if this is HeatInterface

set_heat_setting (filter)

Sets the heat setting for this heat interface.

Parameters

filter

The new setting.

Can only be used if this is HeatInterface

get_control_behavior () → LuaControlBehavior

Gets the control behavior of the entity (if any).

Return value

The control behavior or nil.


get_or_create_control_behavior () → LuaControlBehavior

Gets (and or creates if needed) the control behavior of the entity.

Return value

The control behavior or nil.


get_circuit_network (wire, circuit_connector) → LuaCircuitNetwork

Parameters

wire

Wire color of the network connected to this entity.


circuit_connector
Optional

The connector to get circuit network for. Must be specified for entities with more than one circuit network connector.

Return value

The circuit network or nil.


get_merged_signal (signal, circuit_connector) → int

Read a single signal from the combined circuit networks.

Parameters

signal

The signal to read.


circuit_connector
Optional

The connector to get signals for. Must be specified for entities with more than one circuit network connector.

Return value

The current value of the signal.


get_merged_signals (circuit_connector) → array[Signal]

The merged circuit network signals or nil if there are no signals.

Parameters

circuit_connector
Optional

The connector to get signals for. Must be specified for entities with more than one circuit network connector.

Return value

The sum of signals on both the red and green networks, or nil if it doesn't have a circuit connector.


supports_backer_name () → boolean

Whether this entity supports a backer name.


copy_settings (entity, by_player) → dictionary[stringuint]

Copies settings from the given entity onto this entity.

Parameters

entity

by_player
Optional

If provided, the copying is done 'as' this player and on_entity_settings_pasted is triggered.

Return value

Any items removed from this entity as a result of copying the settings.


get_logistic_point (index) → LuaLogisticPoint or array[LuaLogisticPoint]

Gets all the LuaLogisticPoints that this entity owns. Optionally returns only the point specified by the index parameter.

Parameters

index
Optional

If provided, only returns the LuaLogisticPoint specified by this index.

Note

When index is not given, this will be a single LuaLogisticPoint for most entities. For some (such as the player character), it can be zero or more.


play_note (instrument, note) → boolean

Plays a note with the given instrument and note.

Parameters

instrument
:: uint

note
:: uint

Return value

If the request is valid. The sound may or may not be played depending on polyphony settings.

Can only be used if this is ProgrammableSpeaker

connect_rolling_stock (direction) → boolean

Connects the rolling stock in the given direction.

Parameters

direction

Return value

If any connection was made


disconnect_rolling_stock (direction) → boolean

Tries to disconnect this rolling stock in the given direction.

Parameters

direction

Return value

If anything was disconnected


update_connections ()

Reconnect loader, beacon, cliff and mining drill connections to entities that might have been teleported out or in by the script. The game doesn't do this automatically as we don't want to loose performance by checking this in normal games.


get_recipe () → LuaRecipe

Current recipe being assembled by this machine or nil if no recipe is set.

Can only be used if this is CraftingMachine

set_recipe (recipe) → dictionary[stringuint]

Sets the current recipe in this assembly machine.

Parameters

recipe

The new recipe or nil to clear the recipe.

Return value

Any items removed from this entity as a result of setting the recipe.

Can only be used if this is AssemblingMachine

rotate {reverse, by_player, spill_items, enable_looted, force} → boolean

Rotates this entity as if the player rotated it.

Parameters

Table (optional) with the following fields:
reverse
:: boolean
Optional

If true, rotate the entity in the counter-clockwise direction.


by_player
Optional

spill_items
:: boolean
Optional

If the player is not given should extra items be spilled or returned as a second return value from this.


enable_looted
:: boolean
Optional

When true, each spilled item will be flagged with the LuaEntity::to_be_looted flag.


force
Optional

When provided the spilled items will be marked for deconstruction by this force.

Return value

Whether the rotation was successful.


get_driver () → LuaEntity or LuaPlayer

Gets the driver of this vehicle if any.

Note

May be nil if the vehicle contains no driver. To check if there's a passenger see LuaEntity::get_passenger.

Can only be used if this is Vehicle

set_driver (driver)

Sets the driver of this vehicle.

Parameters

driver

The new driver or nil to eject the current driver if any.

Note

This differs over LuaEntity::set_passenger in that the passenger can't drive the vehicle.

Can only be used if this is Vehicle

get_passenger () → LuaEntity or LuaPlayer

Gets the passenger of this car or spidertron if any.

Notes

May be nil if the vehicle contains no passenger. To check if there's a driver see LuaEntity::get_driver.

This differs over LuaEntity::get_driver in that the passenger can't drive the car.

Can only be used if this is Vehicle

set_passenger (passenger)

Sets the passenger of this car or spidertron.

Parameters

Note

This differs over LuaEntity::get_driver in that the passenger can't drive the car.

Can only be used if this is Vehicle

is_connected_to_electric_network () → boolean

Returns true if this entity is connected to an electric network.


get_train_stop_trains () → array[LuaTrain]

The trains scheduled to stop at this train stop.

Can only be used if this is TrainStop

get_stopped_train () → LuaTrain

The train currently stopped at this train stop or nil if none.

Can only be used if this is TrainStop

clone {position, surface, force, create_build_effect_smoke} → LuaEntity

Clones this entity.

Parameters

Table with the following fields:
position

The destination position


surface
Optional

The destination surface


force
Optional

create_build_effect_smoke
:: boolean
Optional

If false, the building effect smoke will not be shown around the new entity.

Return value

The cloned entity or nil if this entity can't be cloned/can't be cloned to the given location.

Note


get_fluid_count (fluid) → double

Get the amount of all or some fluid in this entity.

Parameters

fluid
:: string
Optional

Prototype name of the fluid to count. If not specified, count all fluids.

Note

If information about fluid temperatures is required, LuaEntity::fluidbox should be used instead.


get_fluid_contents () → dictionary[stringdouble]

Get amounts of all fluids in this entity.

Return value

The amounts, indexed by fluid names.

Note

If information about fluid temperatures is required, LuaEntity::fluidbox should be used instead.


remove_fluid {name, amount, minimum_temperature, maximum_temperature, temperature} → double

Remove fluid from this entity.

Parameters

Table with the following fields:
name
:: string

Fluid prototype name.


amount
:: double

Amount to remove


minimum_temperature
:: double
Optional

maximum_temperature
:: double
Optional

temperature
:: double
Optional

Return value

Amount of fluid actually removed.

Note

If temperature is given only fluid matching that exact temperature is removed. If minimum and maximum is given fluid within that range is removed.


insert_fluid (fluid) → double

Insert fluid into this entity. Fluidbox is chosen automatically.

Parameters

fluid
:: Fluid

Fluid to insert.

Return value

Amount of fluid actually inserted.


clear_fluid_inside ()

Remove all fluids from this entity.


get_beam_source () → BeamTarget

Get the source of this beam.

Can only be used if this is Beam

set_beam_source (source)

Set the source of this beam.

Parameters

source
Can only be used if this is Beam

get_beam_target () → BeamTarget

Get the target of this beam.

Can only be used if this is Beam

set_beam_target (target)

Set the target of this beam.

Parameters

target
Can only be used if this is Beam

get_radius () → double

The radius of this entity.


get_health_ratio () → float

The health ratio of this entity between 1 and 0 (for full health and no health respectively).


create_build_effect_smoke ()

Creates the same smoke that is created when you place a building by hand. You can play the building sound to go with it by using LuaSurface::play_sound, eg: entity.surface.play_sound{path="entity-build/"..entity.prototype.name, position=entity.position}


release_from_spawner ()

Release the unit from the spawner which spawned it. This allows the spawner to continue spawning additional units.

Can only be used if this is Unit

toggle_equipment_movement_bonus ()

Toggle this entity's equipment movement bonus. Does nothing if the entity does not have an equipment grid.

Note

This property can also be read and written on the equipment grid of this entity.


can_shoot (target, position) → boolean

If this character can shoot the given entity or position.

Parameters

target

position

start_fading_out ()

Only works if the entity is a speech-bubble, with an "effect" defined in its wrapper_flow_style. Starts animating the opacity of the speech bubble towards zero, and destroys the entity when it hits zero.


get_upgrade_target () → LuaEntityPrototype

Returns the new entity prototype.

Return value

nil if this entity is not marked for upgrade.


get_upgrade_direction () → defines.direction

Returns the new entity direction after upgrading.

Return value

nil if this entity is not marked for upgrade.


get_damage_to_be_taken () → float

Returns the amount of damage to be taken by this entity.


deplete ()

Depletes and destroys this resource entity.

Can only be used if this is ResourceEntity

mine {inventory, force, raise_destroyed, ignore_minable} → boolean

Mines this entity.

Parameters

Table (optional) with the following fields:
inventory
Optional

If provided the item(s) will be transferred into this inventory. If provided, this must be an inventory created with LuaGameScript::create_inventory or be a basic inventory owned by some entity.


force
:: boolean
Optional

If true, when the item(s) don't fit into the given inventory the entity is force mined. If false, the mining operation fails when there isn't enough room to transfer all of the items into the inventory. Defaults to false. This is ignored and acts as 'true' if no inventory is provided.


raise_destroyed
:: boolean
Optional

If true, script_raised_destroy will be raised. Defaults to true.


ignore_minable
:: boolean
Optional

If true, the minable state of the entity is ignored. Defaults to false. If false, an entity that isn't minable (set as not-minable in the prototype or isn't minable for other reasons) will fail to be mined.

Return value

Whether mining succeeded.

Notes

'standard' operation is to keep calling mine() with an inventory until all items are transferred and the items dealt with.

The result of mining the entity (the item(s) it produces when mined) will be dropped on the ground if they don't fit into the provided inventory.


spawn_decorations ()

Triggers spawn_decoration actions defined in the entity prototype or does nothing if entity is not "turret" or "unit-spawner".


can_wires_reach (entity) → boolean

Can wires reach between these entities.

Parameters

entity

get_connected_rolling_stock (direction) → LuaEntity

Gets rolling stock connected to the given end of this stock

Parameters

direction

Return value

One of connected rolling stocks

Note

This will also return defines.rail_direction of other rolling stock that is connected back to this rolling stock


is_registered_for_construction () → boolean

Is this entity or tile ghost or item request proxy registered for construction? If false, it means a construction robot has been dispatched to build the entity, or it is not an entity that can be constructed.


is_registered_for_deconstruction (force) → boolean

Is this entity registered for deconstruction with this force? If false, it means a construction robot has been dispatched to deconstruct it, or it is not marked for deconstruction. The complexity is effectively O(1) - it depends on the number of objects targeting this entity which should be small enough.

Parameters

force

The force construction manager to check.


is_registered_for_upgrade () → boolean

Is this entity registered for upgrade? If false, it means a construction robot has been dispatched to upgrade it, or it is not marked for upgrade. This is worst-case O(N) complexity where N is the current number of things in the upgrade queue.


is_registered_for_repair () → boolean

Is this entity registered for repair? If false, it means a construction robot has been dispatched to upgrade it, or it is not damaged. This is worst-case O(N) complexity where N is the current number of things in the repair queue.


add_autopilot_destination (position)

Adds the given position to this spidertron's autopilot's queue of destinations.

Parameters

position

The position the spidertron should move to.

Can only be used if this is SpiderVehicle

connect_linked_belts (neighbour)

Connects current linked belt with another one.

Neighbours have to be of different type. If given linked belt is connected to something else it will be disconnected first. If provided neighbour is connected to something else it will also be disconnected first. Automatically updates neighbour to be connected back to this one.

Parameters

neighbour

Another linked belt or entity ghost containing linked belt to connect or nil to disconnect

Note

Can also be used on entity ghost if it contains linked-belt

Can only be used if this is LinkedBelt

disconnect_linked_belts ()

Disconnects linked belt from its neighbour.

Note

Can also be used on entity ghost if it contains linked-belt

Can only be used if this is LinkedBelt

get_spider_legs () → array[LuaEntity]

Gets legs of given SpiderVehicle.

Can only be used if this is SpiderVehicle

help () → string

All methods and properties that this object supports.

Attributes

name :: string [Read]

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


ghost_name :: string [Read]

Name of the entity or tile contained in this ghost


localised_name :: LocalisedString [Read]

Localised name of the entity.


localised_description :: LocalisedString [Read]


ghost_localised_name :: LocalisedString [Read]

Localised name of the entity or tile contained in this ghost.


ghost_localised_description :: LocalisedString [Read]


type :: string [Read]

The entity prototype type of this entity.


ghost_type :: string [Read]

The prototype type of the entity or tile contained in this 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).

Notes

Entities that are not active naturally can't be set to be active (setting it to be active will do nothing)

Ghosts, simple smoke, and corpses can't be modified at this time.

It is even possible to set the character 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.

Notes

An indestructible entity can still be mined.

Entities that are indestructible naturally (they have no health, like smoke, resource etc) can't be set to be destructible.


minable :: boolean [Read/Write]

Notes

Not minable entities can still be destroyed.

Entities that are not minable naturally (like smoke, character, 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]

The current health of the entity, or nil if it doesn't have health. Health is automatically clamped to be between 0 and max health (inclusive). Entities with a health of 0 can not be attacked.

Note

To get the maximum possible health of this entity, see LuaEntityPrototype::max_health on its prototype.


direction :: defines.direction [Read/Write]

The current direction this entity is facing.


supports_direction :: boolean [Read]

Whether the entity has direction. When it is false for this entity, it will always return north direction when asked for.


orientation :: RealOrientation [Read/Write]

The smooth orientation of this entity, if it supports orientation.


cliff_orientation :: CliffOrientation [Read]

The orientation of this cliff.


relative_turret_orientation :: RealOrientation [Read/Write]

The relative orientation of the vehicle turret, artillery turret, artillery wagon or nil if this entity isn't a vehicle with a vehicle turret or artillery turret/wagon.

Note

Writing does nothing if the vehicle doesn't have a turret.


torso_orientation :: RealOrientation [Read/Write]

The torso orientation of this spider vehicle.


amount :: uint [Read/Write]

Count of resource units contained.


initial_amount :: uint [Read/Write]

Count of initial resource units contained.

Note

If this is not an infinite resource reading will give nil and writing will give an error.


effectivity_modifier :: float [Read/Write]

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


consumption_modifier :: float [Read/Write]

Multiplies the energy consumption.


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

driver_is_gunner :: boolean [Read/Write]

Whether the driver of this car or spidertron is the gunner, if false, the passenger is the gunner.


vehicle_automatic_targeting_parameters :: VehicleAutomaticTargetingParameters [Read/Write]

Read when this spidertron auto-targets enemies


speed :: float [Read/Write]

The current speed of this car in tiles per tick, rolling stock, projectile or spider vehicle, or current max speed of the unit. Only the speed of units, cars, and projectiles are writable.


effective_speed :: float [Read]

The current speed of this unit in tiles per tick, taking into account any walking speed modifier given by the tile the unit is standing on.


stack :: LuaItemStack [Read]


prototype :: LuaEntityPrototype [Read]

The entity prototype of this entity.


ghost_prototype :: LuaEntityPrototype or LuaTilePrototype [Read]

The prototype of the entity or tile contained in this ghost.


drop_position :: Position [Read/Write]

Position where the entity puts its stuff.

Note

Meaningful only for entities that put stuff somewhere, such as mining drills or inserters. Mining drills can't have their drop position changed; inserters must have allow_custom_vectors set to true on their prototype to allow changing the drop position.


pickup_position :: Position [Read/Write]

Where the inserter will pick up items from.

Note

Inserters must have allow_custom_vectors set to true on their prototype to allow changing the pickup position.


drop_target :: LuaEntity [Read/Write]

The entity this entity is putting its items to, or nil if there is no such entity. If there are multiple possible entities at the drop-off point, writing to this attribute allows a mod to choose which one to drop off items to. The entity needs to collide with the tile box under the drop-off position.

Note

Meaningful only for entities that put items somewhere, such as mining drills or inserters. Returns nil for any other entity.


pickup_target :: LuaEntity [Read/Write]

The entity this inserter will attempt to pick up items from, or nil if there is no such entity. If there are multiple possible entities at the pick-up point, writing to this attribute allows a mod to choose which one to pick up items from. The entity needs to collide with the tile box under the pick-up position.


selected_gun_index :: uint [Read/Write]

Index of the currently selected weapon slot of this character, car, or spidertron, or nil if the car/spidertron doesn't have guns.


energy :: double [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

temperature :: double [Read/Write]

The temperature of this entities heat energy source if this entity uses a heat energy source or nil.


previous_recipe :: LuaRecipe [Read]

The previous recipe this furnace was using or nil if the furnace had no previous recipe.


held_stack :: LuaItemStack [Read]

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


held_stack_position :: Position [Read]

Current position of the inserter's "hand".


train :: LuaTrain [Read]

The train this rolling stock belongs to or nil if not rolling stock.


neighbours :: dictionary[string → array[LuaEntity]] or array[array[LuaEntity]] or LuaEntity [Read]

  • 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 entity arrays of all entities a given fluidbox is connected to.
  • When called on an underground transport belt, this is the other end of the underground belt connection, or nil if none.
  • When called on a wall-connectable entity or reactor, this is a dictionary of all connections indexed by the connection direction "north", "south", "east", and "west".
  • When called on a cliff entity, this is a dictionary of all connections indexed by the connection direction "north", "south", "east", and "west".

belt_neighbours :: dictionary[string → array[LuaEntity]] [Read]

The belt connectable neighbours of this belt connectable entity. Only entities that input to or are outputs of this entity. Does not contain the other end of an underground belt, see LuaEntity::neighbours for that. This is a dictionary with "inputs", "outputs" entries that are arrays of transport belt connectable entities, or empty tables if no entities.


fluidbox :: LuaFluidBox [Read/Write]

Fluidboxes of this entity.


backer_name :: string [Read/Write]

The backer name assigned to this entity, or nil if this entity doesn't support backer names. Entities that support backer names are labs, locomotives, radars, roboports, and train stops.

Note

While train stops get the name of a backer when placed down, players can rename them if they want to. In this case, backer_name returns the player-given name of the entity.


entity_label :: string [Read/Write]

The label of this entity if it has one or nil. Changing the value will trigger on_entity_renamed event

Note

only usable on entities that have labels (currently only spider-vehicles).


time_to_live :: uint [Read/Write]

The ticks left before a ghost, combat robot, highlight box or smoke with trigger is destroyed.

  • for ghosts set to uint32 max (4,294,967,295) to never expire.
  • for ghosts Cannot be set higher than LuaForce::ghost_time_to_live of the entity's force.

color :: Color [Read/Write]

The character, rolling stock, train stop, car, spider-vehicle, flying text, corpse or simple-entity-with-owner color. Returns nil if this entity doesn't use custom colors.

Note

Car color is overridden by the color of the current driver/passenger, if there is one.


text :: LocalisedString [Read/Write]

The text of this flying-text entity.


signal_state :: defines.signal_state [Read]

The state of this rail signal.


chain_signal_state :: defines.chain_signal_state [Read]

The state of this chain signal.


to_be_looted :: boolean [Read/Write]

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


crafting_speed :: double [Read]

The current crafting speed, including speed bonuses from modules and beacons.


crafting_progress :: float [Read/Write]

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


bonus_progress :: double [Read/Write]

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


productivity_bonus :: double [Read]

The productivity bonus of this entity.

Note

This includes force based bonuses as well as beacon/module bonuses.


pollution_bonus :: double [Read]

The pollution bonus of this entity.


speed_bonus :: double [Read]

The speed bonus of this entity.

Note

This includes force based bonuses as well as beacon/module bonuses.


consumption_bonus :: double [Read]

The consumption bonus of this entity.


belt_to_ground_type :: string [Read]

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


loader_type :: string [Read/Write]

"input" or "output", depending on whether this loader puts to or gets from a container.


rocket_parts :: uint [Read/Write]

Number of rocket parts in the silo.


logistic_network :: LuaLogisticNetwork [Read/Write]

The logistic network this entity is a part of.


logistic_cell :: LuaLogisticCell [Read]

The logistic cell this entity is a part of. Will be nil if this entity is not a part of any logistic cell.


item_requests :: dictionary[stringuint] [Read/Write]

Items this ghost will request when revived or items this item request proxy is requesting. Result is a dictionary mapping each item prototype name to the required count.


player :: LuaPlayer [Read]

The player connected to this character or nil if none.


unit_group :: LuaUnitGroup [Read]

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


damage_dealt :: double [Read/Write]

The damage dealt by this turret, artillery turret, or artillery wagon.


kills :: uint [Read/Write]

The number of units killed by this turret, artillery turret, or artillery wagon.


last_user :: LuaPlayer [Read/Write]

The last player that changed any setting on this entity. This includes building the entity, changing its color, or configuring its circuit network. Can be nil if the last user is not part of the save anymore. Mods can overwrite it if desired.


electric_buffer_size :: double [Read/Write]

The buffer size for the electric energy source or nil if the entity doesn't have an electric energy source.

Note

Write access is limited to the ElectricEnergyInterface type


electric_input_flow_limit :: double [Read]

The input flow limit for the electric energy source or nil if the entity doesn't have an electric energy source.


electric_output_flow_limit :: double [Read]

The output flow limit for the electric energy source or nil if the entity doesn't have an electric energy source.


electric_drain :: double [Read]

The electric drain for the electric energy source or nil if the entity doesn't have an electric energy source.


electric_emissions :: double [Read]

The emissions for the electric energy source or nil if the entity doesn't have an electric energy source.


unit_number :: uint [Read]

The unit number or nil if the entity doesn't have one. This is universally unique for every entity that has one, for the lifetime of a whole game.


ghost_unit_number :: uint [Read]

The unit number of the entity contained in this ghost or nil if the entity doesn't have one.


mining_progress :: double [Read/Write]

The mining progress for this mining drill or nil if this isn't a mining drill. Is a number in range [0, mining_target.prototype.mineable_properties.mining_time]


bonus_mining_progress :: double [Read/Write]

The bonus mining progress for this mining drill or nil if this isn't a mining drill. Read yields a number in range [0, mining_target.prototype.mineable_properties.mining_time]


power_production :: double [Read/Write]

The power production specific to the ElectricEnergyInterface entity type.


power_usage :: double [Read/Write]

The power usage specific to the ElectricEnergyInterface entity type.


bounding_box :: BoundingBox [Read]

LuaEntityPrototype::collision_box around entity's given position and respecting the current entity orientation.


secondary_bounding_box :: BoundingBox [Read]

The secondary bounding box of this entity or nil if it doesn't have one.


selection_box :: BoundingBox [Read]

LuaEntityPrototype::selection_box around entity's given position and respecting the current entity orientation.


secondary_selection_box :: BoundingBox [Read]

The secondary selection box of this entity or nil if it doesn't have one.


mining_target :: LuaEntity [Read]

The mining target or nil if none


circuit_connected_entities :: table [Read]

Entities that are directly connected to this entity via the circuit network.

Table fields

red
:: array[LuaEntity]

Entities connected via the red wire.


green
:: array[LuaEntity]

Entities connected via the green wire.


circuit_connection_definitions :: array[CircuitConnectionDefinition] [Read]

The connection definition for entities that are directly connected to this entity via the circuit network.


request_slot_count :: uint [Read]

The index of the configured request with the highest index for this entity. This means 0 if no requests are set and e.g. 20 if the 20th request slot is configured.


filter_slot_count :: uint [Read]

The number of filter slots this inserter, loader, or logistic storage container has. 0 if not one of those entities.


loader_container :: LuaEntity [Read]

The container entity this loader is pointing at/pulling from depending on the LuaEntity::loader_type.


grid :: LuaEquipmentGrid [Read]

The equipment grid or nil if this entity doesn't have an equipment grid.


graphics_variation :: uint8 [Read/Write]

The graphics variation for this entity or nil if this entity doesn't use graphics variations.


tree_color_index :: uint8 [Read/Write]

Index of the tree color.


tree_color_index_max :: uint8 [Read]

Maximum index of the tree colors.


tree_stage_index :: uint8 [Read/Write]

Index of the tree stage.


tree_stage_index_max :: uint8 [Read]

Maximum index of the tree stages.


tree_gray_stage_index :: uint8 [Read/Write]

Index of the tree gray stage


tree_gray_stage_index_max :: uint8 [Read]

Maximum index of the tree gray stages.


burner :: LuaBurner [Read]

The burner energy source for this entity or nil if there isn't one.


shooting_target :: LuaEntity [Read/Write]

The shooting target for this turret or nil.


proxy_target :: LuaEntity [Read]

The target entity for this item-request-proxy or nil


stickers :: array[LuaEntity] [Read]

The sticker entities attached to this entity or nil if none.


sticked_to :: LuaEntity [Read]

The entity this sticker is sticked to.


parameters :: ProgrammableSpeakerParameters [Read/Write]


alert_parameters :: ProgrammableSpeakerAlertParameters [Read/Write]


electric_network_statistics :: LuaFlowStatistics [Read]

The electric network statistics for this electric pole.


inserter_stack_size_override :: uint [Read/Write]

Sets the stack size limit on this inserter. If the stack size is > than the force stack size limit the value is ignored.

Note

Set to 0 to reset.


products_finished :: uint [Read/Write]

The number of products this machine finished crafting in its lifetime.


spawner :: LuaEntity [Read]

The spawner associated with this unit entity or nil if the unit has no associated spawner.


units :: array[LuaEntity] [Read]

The units associated with this spawner entity.


power_switch_state :: boolean [Read/Write]

The state of this power switch.


effects :: ModuleEffects [Read]

The effects being applied to this entity or nil. For beacons this is the effect the beacon is broadcasting.


infinity_container_filters :: array[InfinityInventoryFilter] [Read/Write]

The filters for this infinity container.


remove_unfiltered_items :: boolean [Read/Write]

If items not included in this infinity container filters should be removed from the container.


character_corpse_player_index :: uint [Read/Write]

The player index associated with this character corpse.

Note

The index is not guaranteed to be valid so it should always be checked first if a player with that index actually exists.


character_corpse_tick_of_death :: uint [Read/Write]

The tick this character corpse died at.


character_corpse_death_cause :: LocalisedString [Read/Write]

The reason this character corpse character died (if any).


associated_player :: LuaPlayer [Read/Write]

The player this character is associated with or nil if none. When the player logs off in multiplayer all of the associated characters will be logged off with him.

Notes

A character associated with a player is not directly controlled by any player.

Set to nil to clear. The player will be automatically disassociated when a controller is set on the character.


tick_of_last_attack :: uint [Read/Write]

The last tick this character entity was attacked.


tick_of_last_damage :: uint [Read/Write]

The last tick this character entity was damaged.


splitter_filter :: LuaItemPrototype [Read/Write]

The filter for this splitter or nil if no filter is set.


inserter_filter_mode :: string [Read/Write]

The filter mode for this filter inserter: "whitelist", "blacklist", or nil if this inserter doesn't use filters.


splitter_input_priority :: string [Read/Write]

The input priority for this splitter : "left", "none", or "right".


splitter_output_priority :: string [Read/Write]

The output priority for this splitter : "left", "none", or "right".


armed :: boolean [Read]

If this land mine is armed.


recipe_locked :: boolean [Read/Write]

When locked; the recipe in this assembling machine can't be changed by the player.


connected_rail :: LuaEntity [Read]

The rail entity this train stop is connected to or nil if there is none.


connected_rail_direction :: defines.rail_direction [Read]

Rail direction to which this train stop is binding. This returns a value even when no rails are present.


trains_in_block :: uint [Read]

The number of trains in this rail block for this rail entity.


timeout :: uint [Read/Write]

The timeout that's left on this landmine in ticks. It describes the time between the landmine being placed and it being armed.


neighbour_bonus :: double [Read]

The current total neighbour bonus of this reactor.


ai_settings :: LuaAISettings [Read]

The ai settings of this unit.


highlight_box_type :: string [Read/Write]

The hightlight box type of this highlight box entity.



status :: defines.entity_status [Read]

The status of this entity or nil if no status.


enable_logistics_while_moving :: boolean [Read/Write]

If equipment grid logistics are enabled while this vehicle is moving.


render_player :: LuaPlayer [Read/Write]

The player that this simple-entity-with-owner, simple-entity-with-force, flying-text, or highlight-box is visible to. nil means it is rendered for every player.


render_to_forces :: array[ForceIdentification] [Read/Write]

The forces that this simple-entity-with-owner, simple-entity-with-force, or flying-text is visible to. nil or an empty array means it is rendered for every force.

Note

Reading will always give an array of LuaForce


pump_rail_target :: LuaEntity [Read]

The rail target of this pump or nil.


moving :: boolean [Read]

Returns true if this unit is moving.


electric_network_id :: uint [Read]

Returns the id of the electric network that this entity is connected to or nil.


allow_dispatching_robots :: boolean [Read/Write]

Whether this character's personal roboports are allowed to dispatch robots.


auto_launch :: boolean [Read/Write]

Whether this rocket silo automatically launches the rocket when cargo is inserted.


energy_generated_last_tick :: double [Read]

How much energy this generator generated in the last tick.


storage_filter :: LuaItemPrototype [Read/Write]

The storage filter for this logistic storage container.


request_from_buffers :: boolean [Read/Write]

Whether this requester chest is set to also request from buffer chests.

Note

Useable only on entities that have requester slots.


corpse_expires :: boolean [Read/Write]

Whether this corpse will ever fade away.

Note

Useable only on corpses.


corpse_immune_to_entity_placement :: boolean [Read/Write]

If true, corpse won't be destroyed when entities are placed over it. If false, whether corpse will be removed or not depends on value of CorpsePrototype::remove_on_entity_placement.

Note

Useable only on corpses.


tags :: Tags [Read/Write]

The tags associated with this entity ghost or nil if not an entity ghost.


command :: Command [Read]

The command given to this unit or nil is the unit has no command.


distraction_command :: Command [Read]

The distraction command given to this unit or nil is the unit currently isn't distracted.


time_to_next_effect :: uint [Read/Write]

The ticks until the next trigger effect of this smoke-with-trigger.


autopilot_destination :: MapPosition [Read/Write]

Destination position of spidertron's autopilot. Returns nil if autopilot doesn't have destination set.


autopilot_destinations :: array[MapPosition] [Read]

The queued destination positions of spidertron's autopilot.


trains_count :: uint [Read]

Amount of trains related to this particular train stop. Includes train stopped at this train stop (until it finds a path to next target) and trains having this train stop as goal or waypoint. Writing nil will disable the limit (will set a maximum possible value).

Notes

Train may be included multiple times when braking distance covers this train stop multiple times

Value may be read even when train stop has no control behavior


trains_limit :: uint [Read/Write]

Amount of trains above which no new trains will be sent to this train stop.

Note

When a train stop has a control behavior with wire connected and set_trains_limit enabled, this value will be overwritten by it


is_entity_with_force :: boolean [Read]

(deprecated by 1.1.51) If this entity is a MilitaryTarget. Returns same value as LuaEntity::is_military_target


is_military_target :: boolean [Read/Write]

If this entity is a MilitaryTarget. Can be written to if LuaEntityPrototype::allow_run_time_change_of_is_military_target returns true


is_entity_with_owner :: boolean [Read]

If this entity is EntityWithOwner


is_entity_with_health :: boolean [Read]

If this entity is EntityWithHealth


combat_robot_owner :: LuaEntity [Read/Write]

The owner of this combat robot if any.



follow_target :: LuaEntity [Read/Write]

The follow target of this spidertron if any.


follow_offset :: Position [Read/Write]

The follow offset of this spidertron if any. If it is not following an entity this will be nil. This is randomized each time the follow entity is set.


linked_belt_type :: string [Read/Write]

Type of linked belt: it is either "input" or "output". Changing type will also flip direction so the belt is out of the same side

Notes

Can only be changed when linked belt is disconnected (has no neighbour set)

Can also be used on entity ghost if it contains linked-belt


linked_belt_neighbour :: LuaEntity [Read]

Neighbour to which this linked belt is connected to. Returns nil if not connected.

Notes

Can also be used on entity ghost if it contains linked-belt

May return entity ghost which contains linked belt to which connection is made


valid :: boolean [Read]

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.


object_name :: string [Read]

The class name of this object. Available even when valid is false. For LuaStruct objects it may also be suffixed with a dotted path to a member of the struct.

|<

Classes

Events

Concepts

Defines

Builtin types