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.
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(options) 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 the personal request and trash to the given values.
get_personal_logistic_slot(slot_index) → PersonalLogisticParameters Sets the personal request and trash to the given values.
clear_personal_logistic_slot(slot_index)
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 :: ForceSpecification [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.
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 :: ItemPrototypeSpecification [RW] The ghost prototype in the player's cursor.
driving :: boolean [RW] true if the player is in a vehicle.
crafting_queue :: array of CraftingQueueItem [R] Gets the current crafting queue items.
following_robots :: array of 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 of string [RW]
character_running_speed_modifier :: double [RW]
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_logistic_slot_count :: uint [RW] The number of enabled logistic slots for this character or players character.
character_personal_logistic_requests_enabled :: boolean [RW] If personal logistic requests are enabled for this character or players character.
auto_trash_filters :: dictionary stringuint [RW] The auto-trash filters.
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 :: ItemStackSpecification: 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 :: ItemStackSpecification: 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".
  • Additional type-specific parameters
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 :: ItemStackSpecification: Items to remove.
Return value
Number of items actually removed.
teleport(position, surface) → boolean

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

Parameters
position :: Position: Where to teleport to.
surface :: SurfaceSpecification (optional): Surface to teleport to. If not given, will teleport to the entity's current surface. Only players and cars 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.

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
  • 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(options)

Cancels crafting the given count of the given crafting queue index

Parameters
options: :
  • 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 :: TechnologySpecification (optional): The technology to select after opening the GUI.
set_personal_logistic_slot(slot_index, value) → boolean

Sets the personal request and trash to the given values.

Parameters
slot_index :: uint: The slot to set/
Return value
If the slot was set.
Note: This will silently fail if personal logistics are not researched.
get_personal_logistic_slot(slot_index) → PersonalLogisticParameters

Sets the personal request and trash to the given values.

Parameters
slot_index :: uint: The slot to get.
Note: This will silently return an empty value (.name will be nil) if personal logistics aren't researched yet.
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.
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 :: ForceSpecification [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, element or nil.
crafting_queue_size :: uint [Read-only]

Size of the crafting queue.

walking_state :: table [Read-Write]

Current walking state.

It is a table with two 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.

It is a table with two 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.

It is a table with two fields:

picking_state :: boolean [Read-Write]

Current item-picking state.

repair_state :: table [Read-Write]

Current repair state.

It is a table with two 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.

cursor_ghost :: ItemPrototypeSpecification [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 of CraftingQueueItem [Read-only]

Gets the current crafting queue items.

Each CraftingQueueItem is a table:

  • index :: uint: The crafting queue index
  • recipe :: string: The recipe.
  • count :: uint: The count being crafted.

following_robots :: array of 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 of 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]

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_logistic_slot_count :: uint [Read-Write]

The number of enabled logistic slots for this character or players character.

Note: This auto-rounds to keep the GUI rows correct.
character_personal_logistic_requests_enabled :: boolean [Read-Write]

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

auto_trash_filters :: dictionary stringuint [Read-Write]

The auto-trash filters. The keys are item prototype names, the values are the slot values.

Note: When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
Example
This will set the auto-trash slots to keep only at most 20 iron plates and 42 copper wires in the player's inventory.
game.player.auto_trash_filters = {["iron-plate"] = 20, ["copper-cable"] = 42}
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.