LuaControl

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.
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.
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_logistic_slot_count_bonus :: uint [RW]
character_trash_slot_count_bonus :: uint [RW]
character_maximum_following_robot_count_bonus :: uint [RW]
character_health_bonus :: float [RW]
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.

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

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.player_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.
Return value
true when the entity was successfully teleported.
Note: Some entities may not be teleported. For instance, rail signals 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.
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.

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