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.

class LuaControl - sort
get_inventory(inventory) → LuaInventory Get an inventory belonging to this entity.
get_main_inventory() → LuaInventory 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.
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.
has_items_inside() → boolean Does this entity have any item inside it?
can_reach_entity(entity) → boolean Can a given entity be opened or accessed?
clear_items_inside() Remove all items from this entity.
remove_item(items) → uint Remove items from this entity.
teleport(position, surface) → boolean Teleport the entity to a given position, possibly on another surface.
update_selected_entity(position) Select an entity, as if by hovering the mouse above it.
clear_selected_entity() Unselect any selected entity.
disable_flashlight() Disable the flashlight.
enable_flashlight() Enable the flashlight.
is_flashlight_enabled() Is the flashlight enabled.
get_craftable_count(recipe) → 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.
is_player() → 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.
get_personal_logistic_slot(slot_index) → PersonalLogisticParameters Gets the parameters of a personal logistic request and auto-trash slot.
get_vehicle_logistic_slot(slot_index) → PersonalLogisticParameters Gets the parameters of a vehicle logistic request and auto-trash slot.
clear_personal_logistic_slot(slot_index)
clear_vehicle_logistic_slot(slot_index)
is_cursor_blueprint() → boolean Returns whether the player is holding a blueprint, it takes into account a blueprint as an item as well as blueprint from the blueprint record from the blueprint library.
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.
is_cursor_empty() → boolean Returns whether the player is holding something in the cursor.
surface :: LuaSurface [R] The surface this entity is currently on.
position :: Position [R] Current position of the entity.
vehicle :: LuaEntity [R] The vehicle the player is currently sitting in; nil if none.
force :: ForceIdentification [RW] The force of this entity.
selected :: LuaEntity [RW] The currently selected entity; nil if none.
opened :: LuaEntity or LuaItemStack or LuaEquipment or LuaEquipmentGrid or LuaPlayer or LuaGuiElement or defines.gui_type [RW] The GUI target the player currently has open; nil if none.
crafting_queue_size :: uint [R] Size of the crafting queue.
crafting_queue_progress :: double [R] The crafting queue progress [0-1] 0 when no recipe is being crafted.
walking_state :: table [RW] Current walking state.
riding_state :: RidingState [RW] Current riding state of this car or the vehicle this player is riding in.
mining_state :: table [RW] Current mining state.
shooting_state :: table [RW] Current shooting state.
picking_state :: boolean [RW] Current item-picking state.
repair_state :: table [RW] Current repair state.
cursor_stack :: LuaItemStack [R] The player's cursor stack, or nil if the player controller is a spectator.
cursor_ghost :: ItemPrototypeIdentification [RW] The ghost prototype in the player's cursor.
driving :: boolean [RW] true if the player is in a vehicle.
crafting_queue :: array[CraftingQueueItem] [R] Gets the current crafting queue items.
following_robots :: array[LuaEntity] [R] The current combat robots following the character
cheat_mode :: boolean [RW] When true hand crafting is free and instant
character_crafting_speed_modifier :: double [RW]
character_mining_speed_modifier :: double [RW]
character_additional_mining_categories :: array[string] [RW]
character_running_speed_modifier :: double [RW] Modifies the running speed of this character by the given value as a percentage.
character_build_distance_bonus :: uint [RW]
character_item_drop_distance_bonus :: uint [RW]
character_reach_distance_bonus :: uint [RW]
character_resource_reach_distance_bonus :: uint [RW]
character_item_pickup_distance_bonus :: uint [RW]
character_loot_pickup_distance_bonus :: uint [RW]
character_inventory_slots_bonus :: uint [RW]
character_trash_slot_count_bonus :: uint [RW]
character_maximum_following_robot_count_bonus :: uint [RW]
character_health_bonus :: float [RW]
character_personal_logistic_requests_enabled :: boolean [RW] If personal logistic requests are enabled for this character or players character.
vehicle_logistic_requests_enabled :: boolean [RW] If personal logistic requests are enabled for this vehicle (spidertron).
opened_gui_type :: defines.gui_type [R] Returns the defines.gui_type or nil.
build_distance :: uint [R] The build distance of this character or max uint when not a character or player connected to a character.
drop_item_distance :: uint [R] The item drop distance of this character or max uint when not a character or player connected to a character.
reach_distance :: uint [R] The reach distance of this character or max uint when not a character or player connected to a character.
item_pickup_distance :: double [R] The item pickup distance of this character or max double when not a character or player connected to a character.
loot_pickup_distance :: double [R] The loot pickup distance of this character or max double when not a character or player connected to a character.
resource_reach_distance :: double [R] The resource reach distance of this character or max double when not a character or player connected to a character.
in_combat :: boolean [R] If this character entity is in combat.
character_running_speed :: double [R] Gets the current movement speed of this character, including effects from exoskeletons, tiles, stickers and shooting.
character_mining_progress :: double [R] Gets the current mining progress between 0 and 1 of this character, or 0 if they aren't mining.
get_inventory(inventory) → LuaInventory

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

Parameters
inventory :: defines.inventory
Return value
or nil if this entity doesn't have an inventory with the given index.
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 value
or nil if this entity is not a character or player.
can_insert(items) → boolean

Can at least some items be inserted?

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

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

Parameters
items :: ItemStackIdentification: Items to insert.
Return value
Number of items 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:
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 (optional): Prototype name of the item to count. If not specified, count all items.
has_items_inside() → boolean

Does this entity have any item inside it?

can_reach_entity(entity) → boolean

Can a given entity be opened or accessed?

Parameters
entity :: LuaEntity
clear_items_inside()

Remove all items from this entity.

remove_item(items) → uint

Remove items from this entity.

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

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

Parameters
position :: Position: Where to teleport to.
surface :: SurfaceIdentification (optional): 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 value
true when the entity was successfully teleported.
Note: 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.
Note: 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: Position of the entity to select
clear_selected_entity()

Unselect any selected entity.

disable_flashlight()

Disable the flashlight.

enable_flashlight()

Enable the flashlight.

is_flashlight_enabled()

Is the flashlight enabled.

get_craftable_count(recipe) → uint

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

Parameters
recipe :: string or LuaRecipe: The recipe.
Return value
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 :: string or LuaRecipe: The recipe to craft.
  • silent :: boolean (optional): If false and the recipe can't be crafted the requested number of times printing the failure is skipped.
Return value
The count that was actually started crafting.
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.
mine_entity(entity, force) → boolean

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

Parameters
entity :: LuaEntity: The entity to mine
force :: boolean (optional): Forces mining the entity even if the items can't fit in the player.
Return value
If the mining succeeded.
mine_tile(tile) → boolean

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

Parameters
tile :: LuaTile: The tile to mine.
Return value
If the mining succeeded.
is_player() → 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.

Parameters
technology :: TechnologyIdentification (optional): 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 :: PersonalLogisticParameters: The logistic request parameters.
Return value
Whether the slot was set successfully.
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.

Parameters
slot_index :: uint: The slot to set.
value :: PersonalLogisticParameters: The logistic request parameters.
Return value
Whether the slot was set successfully.
Note: This will silently fail if the vehicle does not use logistics.
get_personal_logistic_slot(slot_index) → PersonalLogisticParameters

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

Parameters
slot_index :: uint: The slot to get.
Note: This will silently return an empty value (name will be nil) if personal logistics are not researched yet.
get_vehicle_logistic_slot(slot_index) → PersonalLogisticParameters

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

Parameters
slot_index :: uint: The slot to get.
Note: This will silently return an empty value (name will be nil) if the vehicle does not use logistics.
clear_personal_logistic_slot(slot_index)

Parameters
slot_index :: uint: The slot to clear.
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.
Note: This will silently fail if the vehicle does not use logistics.
is_cursor_blueprint() → boolean

Returns whether the player is holding a blueprint, it takes into account a blueprint as an item as well as blueprint from the blueprint record from the blueprint library. Note that the is_cursor_blueprint and get_cursor_blueprint_entities refer to the currently selected blueprint, so it returns blueprint related information also when holding a blueprint book with a blueprint being selected in it.

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

surface :: LuaSurface [Read-only]

The surface this entity is currently on.

position :: Position [Read-only]

Current position of the entity.

vehicle :: LuaEntity [Read-only]

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.

The GUI target the player currently has open; nil if none.

Note: Write supports any of the types. Read will return the entity, equipment, equipment-grid, player, element or nil.
crafting_queue_size :: uint [Read-only]

Size of the crafting queue.

crafting_queue_progress :: double [Read-only]

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

walking_state :: table [Read-Write]

Current walking state.

Table with the following fields:
  • walking :: boolean: If false, the player is currently not walking; otherwise it's going somewhere
  • direction :: defines.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 with the following fields:
  • mining :: boolean: Whether the player is mining at all
  • position :: Position (optional): 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 with the following fields:

picking_state :: boolean [Read-Write]

Current item-picking state.

repair_state :: table [Read-Write]

Current repair state.

Table with the following fields:
  • repairing :: boolean: The current state
  • position :: Position: The position being repaired

cursor_stack :: LuaItemStack [Read-only]

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.

Note: When read, it will be a LuaItemPrototype.
Note: 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-only]

Gets the current crafting queue items.

following_robots :: array[LuaEntity] [Read-only]

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-only]

Returns the defines.gui_type or nil.

build_distance :: uint [Read-only]

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

drop_item_distance :: uint [Read-only]

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

reach_distance :: uint [Read-only]

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

item_pickup_distance :: double [Read-only]

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-only]

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-only]

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

in_combat :: boolean [Read-only]

If this character entity is in combat.

character_running_speed :: double [Read-only]

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

character_mining_progress :: double [Read-only]

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