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.
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:
- entity
  - entity :: LuaEntity
- position
  - position :: Position
- crafting_queue
  - crafting_queueindex :: uint
- item_stack
  - inventory_index :: defines.inventory
  - 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 (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.

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

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:

state :: defines.shooting: The current state
position :: Position: The position being shot at

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]