Factorio API Docs

1.1.57 <>

Class LuaControl

This is an abstract base class containing the common functionality between LuaPlayer and entities (see LuaEntity). When accessing player-related functions through a LuaEntity, it must refer to a character entity.

get_inventory(inventory)

Get an inventory belonging to this entity.


Gets the main inventory for this character or player if this is a character or player.


can_insert(items)
boolean

Can at least some items be inserted?


insert(items)
uint

Insert items into this entity.


set_gui_arrow{type=…}

Create an arrow which points at this entity.


Removes the arrow created by set_gui_arrow.


uint

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


boolean

Does this entity have any item inside it?


boolean

Can a given entity be opened or accessed?


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.


Select an entity, as if by hovering the mouse above it.


Unselect any selected entity.


Disable the flashlight.


Enable the flashlight.


boolean

Is the flashlight enabled.


uint

Gets the count of the given recipe that can be crafted.


begin_crafting{count=…, recipe=…, silent=…}
uint

Begins crafting the given count of the given recipe.


cancel_crafting{index=…, count=…}

Cancels crafting the given count of the given crafting queue index.


mine_entity(entity, force)
boolean

Mines the given entity as if this player (or character) mined it.


mine_tile(tile)
boolean

Mines the given tile as if this player (or character) mined it.


boolean

When true control adapter is a LuaPlayer object, false for entities including characters with players.


open_technology_gui(technology)

Open the technology GUI and select a given technology.


set_personal_logistic_slot(slot_index, value)
boolean

Sets a personal logistic request and auto-trash slot to the given value.


set_vehicle_logistic_slot(slot_index, value)
boolean

Sets a vehicle logistic request and auto-trash slot to the given value.


Gets the parameters of a personal logistic request and auto-trash slot.


Gets the parameters of a vehicle logistic request and auto-trash slot.




boolean

Returns whether the player is holding a blueprint.


→ array[BlueprintEntity]?

Gets the entities that are part of the currently selected blueprint, regardless of it being in a blueprint book or picked from the blueprint library.


boolean

Returns whether the player is holding something in the cursor.


[R]

The surface this entity is currently on.


[R]

Current position of the entity.


[R]

The vehicle the player is currently sitting in; nil if none.


[RW]

The force of this entity.


[RW]

The currently selected entity; nil if none.


[RW]

The GUI the player currently has open, or nil if no GUI is open.


:: uint
[R]

Size of the crafting queue.


:: double
[R]

The crafting queue progress [0-1] 0 when no recipe is being crafted.


:: table
[RW]

Current walking state.


[RW]

Current riding state of this car or the vehicle this player is riding in.


:: table
[RW]

Current mining state.


:: table
[RW]

Current shooting state.


:: boolean
[RW]

Current item-picking state.


:: table
[RW]

Current repair state.


[R]

The player's cursor stack, or nil if the player controller is a spectator.


[RW]

The ghost prototype in the player's cursor.


:: boolean
[RW]

true if the player is in a vehicle.


:: array[CraftingQueueItem]
[R]

Gets the current crafting queue items.


:: array[LuaEntity]
[R]

The current combat robots following the character


:: boolean
[RW]

When true hand crafting is free and instant





:: double
[RW]

Modifies the running speed of this character by the given value as a percentage.












:: boolean
[RW]

If personal logistic requests are enabled for this character or players character.


:: boolean
[RW]

If personal logistic requests are enabled for this vehicle (spidertron).



:: uint
[R]

The build distance of this character or max uint when not a character or player connected to a character.


:: uint
[R]

The item drop distance of this character or max uint when not a character or player connected to a character.


:: uint
[R]

The reach distance of this character or max uint when not a character or player connected to a character.


:: double
[R]

The item pickup distance of this character or max double when not a character or player connected to a character.


:: double
[R]

The loot pickup distance of this character or max double when not a character or player connected to a character.


:: double
[R]

The resource reach distance of this character or max double when not a character or player connected to a character.


:: boolean
[R]

If this character entity is in combat.


:: double
[R]

Gets the current movement speed of this character, including effects from exoskeletons, tiles, stickers and shooting.


:: double
[R]

Gets the current mining progress between 0 and 1 of this character, or 0 if they aren't mining.

Methods

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

Return values

The inventory or nil if none with the given index was found.

Note

A given defines.inventory is only meaningful for the corresponding LuaObject type. EG: get_inventory(defines.inventory.character_main) is only meaningful if 'this' is a player character. You may get a value back but if the type of 'this' isn't the type referred to by the defines.inventory it's almost guaranteed to not be the inventory asked for.


get_main_inventory() → LuaInventory?

Gets the main inventory for this character or player if this is a character or player.

Return values

The inventory or nil if this entity is not a character or player.


can_insert(items) → boolean

Can at least some items be inserted?

Parameters

items

Items that would be inserted.

Return values

:: boolean

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

The items to insert.

Return values

:: uint

The number of items that were actually inserted.


set_gui_arrow{type=…}

Create an arrow which points at this entity. This is used in the tutorial. For examples, see control.lua in the campaign missions.

Parameters

Table with the following fields:
type
:: string

Where to point to. This field determines what other fields are mandatory. May be "nowhere", "goal", "entity_info", "active_window", "entity", "position", "crafting_queue", or "item_stack".

Other attributes may be specified depending on type:

entity

entity

position

position

crafting_queue

crafting_queueindex
:: uint

item_stack

inventory_index

item_stack_index
:: uint

source
:: string

May be either "player" or "target".


clear_gui_arrow()

Removes the arrow created by set_gui_arrow.


get_item_count(item) → uint

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

Parameters

item
:: string?

Prototype name of the item to count. If not specified, count all items.

Return values

:: uint

has_items_inside() → boolean

Does this entity have any item inside it?

Return values

:: boolean

can_reach_entity(entity) → boolean

Can a given entity be opened or accessed?

Parameters

entity

Return values

:: boolean

clear_items_inside()

Remove all items from this entity.


remove_item(items) → uint

Remove items from this entity.

Parameters

items

The items to remove.

Return values

:: uint

The number of items that were actually removed.


teleport(position, surface) → boolean

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

Parameters

position

Where to teleport to.


surface

Surface to teleport to. If not given, will teleport to the entity's current surface. Only players, cars, and spidertrons can be teleported cross-surface.

Return values

:: boolean

true if the entity was successfully teleported.

Raised events

instantly

Raised if the teleported entity is a player character.

Notes

Some entities may not be teleported. For instance, transport belts won't allow teleportation and this method will always return false when used on any such entity.

You can also pass 1 or 2 numbers as the parameters and they will be used as relative teleport coordinates 'teleport(0, 1)' to move the entity 1 tile positive y. 'teleport(4)' to move the entity 4 tiles to the positive x.


update_selected_entity(position)

Select an entity, as if by hovering the mouse above it.

Parameters

position

Position of the entity to select.

Raised events

instantly

Raised if there is an entity at the given position to select.


clear_selected_entity()

Unselect any selected entity.

Raised events

instantly

Raised if there is a currently selected entity.


disable_flashlight()

Disable the flashlight.


enable_flashlight()

Enable the flashlight.


is_flashlight_enabled() → boolean

Is the flashlight enabled.

Return values

:: boolean

get_craftable_count(recipe) → uint

Gets the count of the given recipe that can be crafted.

Parameters

recipe

The recipe.

Return values

:: uint

The count that can be crafted.


begin_crafting{count=…, recipe=…, silent=…} → uint

Begins crafting the given count of the given recipe.

Parameters

Table with the following fields:
count
:: uint

The count to craft.


recipe

The recipe to craft.


silent
:: boolean?

If false and the recipe can't be crafted the requested number of times printing the failure is skipped.

Return values

:: uint

The count that was actually started crafting.

Raised events

instantly

Raised if crafting was able to be started.


current_tick

Raised if crafting was able to be started.


cancel_crafting{index=…, count=…}

Cancels crafting the given count of the given crafting queue index.

Parameters

Table with the following fields:
index
:: uint

The crafting queue index.


count
:: uint

The count to cancel crafting.

Raised events

instantly

Raised if crafting was able to be cancelled.


current_tick

Raised if crafting was able to be cancelled.


mine_entity(entity, force) → boolean

Mines the given entity as if this player (or character) mined it.

Parameters

entity

The entity to mine


force
:: boolean?

Forces mining the entity even if the items can't fit in the player.

Return values

:: boolean

Whether the mining succeeded.

Raised events

instantly

Raised if mining is possible.


instantly

Raised if mining is successful.


instantly

Raised if mining is successful.


mine_tile(tile) → boolean

Mines the given tile as if this player (or character) mined it.

Parameters

tile
:: LuaTile

The tile to mine.

Return values

:: boolean

Whether the mining succeeded.

Raised events

instantly

Raised if mining is successful.


instantly

Raised if mining is successful.


is_player() → boolean

When true control adapter is a LuaPlayer object, false for entities including characters with players.

Return values

:: boolean

open_technology_gui(technology)

Open the technology GUI and select a given technology.

Parameters

technology

The technology to select after opening the GUI.


set_personal_logistic_slot(slot_index, value) → boolean

Sets a personal logistic request and auto-trash slot to the given value.

Parameters

slot_index
:: uint

The slot to set.


value

The logistic request parameters.

Return values

:: boolean

Whether the slot was set successfully. false if personal logistics are not researched yet.

Raised events

instantly

Raised if setting of logistic slot was successful.

Note

This will silently fail if personal logistics are not researched yet.


set_vehicle_logistic_slot(slot_index, value) → boolean

Sets a vehicle logistic request and auto-trash slot to the given value. Only used on spider-vehicules.

Parameters

slot_index
:: uint

The slot to set.


value

The logistic request parameters.

Return values

:: boolean

Whether the slot was set successfully. false if the vehicle does not use logistics.

Raised events

instantly

Raised if setting of logistic slot was successful.


get_personal_logistic_slot(slot_index) → LogisticParameters

Gets the parameters of a personal logistic request and auto-trash slot.

Parameters

slot_index
:: uint

The slot to get.

Return values

The logistic parameters. If personal logistics are not researched yet, their name will be nil.


get_vehicle_logistic_slot(slot_index) → LogisticParameters

Gets the parameters of a vehicle logistic request and auto-trash slot.

Parameters

slot_index
:: uint

The slot to get.

Return values

The logistic parameters. If the vehicle does not use logistics, their name will be nil.


clear_personal_logistic_slot(slot_index)

Parameters

slot_index
:: uint

The slot to clear.

Raised events

instantly

Raised if clearing of logistic slot was successful.

Note

This will silently fail if personal logistics are not researched yet.


clear_vehicle_logistic_slot(slot_index)

Parameters

slot_index
:: uint

The slot to clear.

Raised events

instantly

Raised if clearing of logistic slot was successful.

Note

This will silently fail if the vehicle does not use logistics.


is_cursor_blueprint() → boolean

Returns whether the player is holding a blueprint. This takes both blueprint items as well as blueprint records from the blueprint library into account.

Note that both this method and LuaControl::get_blueprint_entities refer to the currently selected blueprint, meaning a blueprint book with a selected blueprint will return the information as well.

Return values

:: boolean

get_blueprint_entities() → array[BlueprintEntity]?

Gets the entities that are part of the currently selected blueprint, regardless of it being in a blueprint book or picked from the blueprint library.

Return values

:: array[BlueprintEntity]?

Returns nil if there is no currently selected blueprint.


is_cursor_empty() → boolean

Returns whether the player is holding something in the cursor. It takes into account items from the blueprint library, as well as items and ghost cursor.

Return values

:: boolean

Attributes

surface :: LuaSurface [Read]

The surface this entity is currently on.


position :: MapPosition [Read]

Current position of the entity.


vehicle :: LuaEntity [Read]

The vehicle the player is currently sitting in; nil if none.


force :: ForceIdentification [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 force.


selected :: LuaEntity [Read/Write]

The currently selected entity; nil if none. Assigning an entity will select it if selectable otherwise clears selection.

Raised events

instantly

Raised when a selectable entity is written to this attribute.


opened :: LuaEntity or LuaItemStack or LuaEquipment or LuaEquipmentGrid or LuaPlayer or LuaGuiElement or defines.gui_type [Read/Write]

The GUI the player currently has open, or nil if no GUI is open.

This is the GUI that will asked to close (by firing the on_gui_closed event) when the Esc or E keys are pressed. If this attribute is not nil, and a new GUI is written to it, the existing one will be asked to close.

Raised events

instantly

Raised when writing a valid GUI target to this attribute.

Note

Write supports any of the types. Read will return the entity, equipment, equipment-grid, player, element or nil.


crafting_queue_size :: uint [Read]

Size of the crafting queue.


crafting_queue_progress :: double [Read]

The crafting queue progress [0-1] 0 when no recipe is being crafted.


walking_state :: table [Read/Write]

Current walking state.

Table fields

walking
:: boolean

If false, the player is currently not walking; otherwise it's going somewhere


direction

Direction where the player is walking

Example

Make the player go north. Note that a one-shot action like this will only make the player walk for one tick.

game.player.walking_state = {walking = true, direction = defines.direction.north}

riding_state :: RidingState [Read/Write]

Current riding state of this car or the vehicle this player is riding in.


mining_state :: table [Read/Write]

Current mining state.

Table fields

mining
:: boolean

Whether the player is mining at all


position

What tiles the player is mining; only used when the player is mining tiles (holding a tile in the cursor).

Note

When the player isn't mining tiles the player will mine what ever entity is currently selected. See LuaControl::selected and LuaControl::update_selected_entity.


shooting_state :: table [Read/Write]

Current shooting state.

Table fields

state

The current state


position

The position being shot at


picking_state :: boolean [Read/Write]

Current item-picking state.


repair_state :: table [Read/Write]

Current repair state.

Table fields

repairing
:: boolean

The current state


position

The position being repaired


cursor_stack :: LuaItemStack [Read]

The player's cursor stack, or nil if the player controller is a spectator. Even though this property is marked as read-only, it returns a LuaItemStack, meaning it can be manipulated like so:

Example

player.cursor_stack.clear()

cursor_ghost :: ItemPrototypeIdentification [Read/Write]

The ghost prototype in the player's cursor.

Notes

When read, it will be a LuaItemPrototype.

Items in the cursor stack will take priority over the cursor ghost.


driving :: boolean [Read/Write]

true if the player is in a vehicle. Writing to this attribute puts the player in or out of a vehicle.


crafting_queue :: array[CraftingQueueItem] [Read]

Gets the current crafting queue items.


following_robots :: array[LuaEntity] [Read]

The current combat robots following the character

Note

When called on a LuaPlayer, it must be associated with a character(see LuaPlayer::character).


cheat_mode :: boolean [Read/Write]

When true hand crafting is free and instant


character_crafting_speed_modifier :: double [Read/Write]

Note

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).


character_mining_speed_modifier :: double [Read/Write]

Note

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).


character_additional_mining_categories :: array[string] [Read/Write]

Note

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).


character_running_speed_modifier :: double [Read/Write]

Modifies the running speed of this character by the given value as a percentage. Setting the running modifier to 0.5 makes the character run 50% faster. The minimum value of -1 reduces the movement speed by 100%, resulting in a speed of 0.

Note

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).


character_build_distance_bonus :: uint [Read/Write]

Note

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).


character_item_drop_distance_bonus :: uint [Read/Write]

Note

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).


character_reach_distance_bonus :: uint [Read/Write]

Note

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).


character_resource_reach_distance_bonus :: uint [Read/Write]

Note

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).


character_item_pickup_distance_bonus :: uint [Read/Write]

Note

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).


character_loot_pickup_distance_bonus :: uint [Read/Write]

Note

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).


character_inventory_slots_bonus :: uint [Read/Write]

Note

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).


character_trash_slot_count_bonus :: uint [Read/Write]

Note

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).


character_maximum_following_robot_count_bonus :: uint [Read/Write]

Note

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).


character_health_bonus :: float [Read/Write]

Note

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).


character_personal_logistic_requests_enabled :: boolean [Read/Write]

If personal logistic requests are enabled for this character or players character.


vehicle_logistic_requests_enabled :: boolean [Read/Write]

If personal logistic requests are enabled for this vehicle (spidertron).


opened_gui_type :: defines.gui_type [Read]

Returns the defines.gui_type or nil.


build_distance :: uint [Read]

The build distance of this character or max uint when not a character or player connected to a character.


drop_item_distance :: uint [Read]

The item drop distance of this character or max uint when not a character or player connected to a character.


reach_distance :: uint [Read]

The reach distance of this character or max uint when not a character or player connected to a character.


item_pickup_distance :: double [Read]

The item pickup distance of this character or max double when not a character or player connected to a character.


loot_pickup_distance :: double [Read]

The loot pickup distance of this character or max double when not a character or player connected to a character.


resource_reach_distance :: double [Read]

The resource reach distance of this character or max double when not a character or player connected to a character.


in_combat :: boolean [Read]

If this character entity is in combat.


character_running_speed :: double [Read]

Gets the current movement speed of this character, including effects from exoskeletons, tiles, stickers and shooting.


character_mining_progress :: double [Read]

Gets the current mining progress between 0 and 1 of this character, or 0 if they aren't mining.

|<

Classes

Events

Concepts

Defines

Builtin types

>|