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.
LuaControl
Get an inventory belonging to this entity.
Gets the main inventory for this character or player if this is a character or player.
Can at least some items be inserted?
Create an arrow which points at this entity.
Removes the arrow created by set_gui_arrow
.
Get the number of all or some items in this entity.
Does this entity have any item inside it?
Can a given entity be opened or accessed?
Remove all items from this entity.
Remove items from this entity.
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.
Is the flashlight enabled.
Gets the count of the given recipe that can be crafted.
Begins crafting the given count of the given recipe.
Cancels crafting the given count of the given crafting queue index.
Mines the given entity as if this player (or character) mined it.
When true
control adapter is a LuaPlayer object, false
for entities including characters with players.
Open the technology GUI and select a given technology.
Sets a personal logistic request and auto-trash slot to the given value.
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.
Returns whether the player is holding a blueprint.
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 whether the player is holding something in the cursor.
The surface this entity is currently on.
Current position of the entity.
The force of this entity.
The GUI the player currently has open, or nil
if no GUI is open.
Size of the crafting queue.
The crafting queue progress [0-1] 0 when no recipe is being crafted.
Current walking state.
Current riding state of this car or the vehicle this player is riding in.
Current mining state.
Current shooting state.
Current item-picking state.
Current repair state.
The player's cursor stack, or nil
if the player controller is a spectator.
The ghost prototype in the player's cursor.
Gets the current crafting queue items.
The current combat robots following the character
When true
hand crafting is free and instant
Modifies the running speed of this character by the given value as a percentage.
If personal logistic requests are enabled for this character or players character.
If personal logistic requests are enabled for this vehicle (spidertron).
Returns the defines.gui_type or nil
.
The build distance of this character or max uint when not a character or player connected to a character.
The item drop distance of this character or max uint when not a character or player connected to a character.
The reach distance of this character or max uint when not a character or player connected to a character.
The item pickup distance of this character or max double when not a character or player connected to a character.
The loot pickup distance of this character or max double when not a character or player connected to a character.
The resource reach distance of this character or max double when not a character or player connected to a character.
Gets the current movement speed of this character, including effects from exoskeletons, tiles, stickers and shooting.
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.
The inventory or nil
if none with the given index was found.
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.
The inventory or nil
if this entity is not a character or player.
can_insert(items)
→
boolean
Can at least some items be inserted?
Items that would be inserted.
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.
The items to insert.
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.
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
position
crafting_queue
item_stack
get_item_count(item)
→
uint
Get the number of all or some items in this entity.
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
remove_item(items)
→
uint
Remove items from this entity.
The items to remove.
The number of items that were actually removed.
teleport(position,
surface)
→
boolean
Teleport the entity to a given position, possibly on another surface.
Where to teleport to.
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.
true
if the entity was successfully teleported.
Raised if the teleported entity is a player character.
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.
Position of the entity to select.
Raised if there is an entity at the given position to select.
clear_selected_entity()
Unselect any selected entity.
Raised if there is a currently selected entity.
is_flashlight_enabled()
→
boolean
Is the flashlight enabled.
get_craftable_count(recipe)
→
uint
begin_crafting{count=…,
recipe=…,
silent=…}
→
uint
Begins crafting the given count of the given recipe.
The count to craft.
If false and the recipe can't be crafted the requested number of times printing the failure is skipped.
The count that was actually started crafting.
Raised if crafting was able to be started.
Raised if crafting was able to be started.
cancel_crafting{index=…,
count=…}
Cancels crafting the given count of the given crafting queue index.
Raised if crafting was able to be cancelled.
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.
The entity to mine
Forces mining the entity even if the items can't fit in the player.
Whether the mining succeeded.
Raised if mining is possible.
Raised if mining is successful.
Raised if mining is successful.
mine_tile(tile)
→
boolean
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.
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.
The slot to set.
The logistic request parameters.
Whether the slot was set successfully. false
if personal logistics are not researched yet.
Raised if setting of logistic slot was successful.
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-vehicle
.
The slot to set.
The logistic request parameters.
Whether the slot was set successfully. false
if the vehicle does not use logistics.
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. Only used on spider-vehicle
.
The slot to get.
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.
The slot to get.
The logistic parameters. If the vehicle does not use logistics, their name
will be nil
.
clear_personal_logistic_slot(slot_index)
The slot to clear.
Raised if clearing of logistic slot was successful.
This will silently fail if personal logistics are not researched yet.
clear_vehicle_logistic_slot(slot_index)
The slot to clear.
Raised if clearing of logistic slot was successful.
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.
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]
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]
selected
:: LuaEntity
[Read/Write]
The currently selected entity; nil
if none. Assigning an entity will select it if selectable otherwise clears selection.
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 when writing a valid GUI target to this attribute.
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/Write]
The crafting queue progress [0-1] 0 when no recipe is being crafted.
walking_state
:: table
[Read/Write]
Current walking state.
If false
, the player is currently not walking; otherwise it's going somewhere
Direction where the player is walking
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.
Whether the player is mining at all
What tiles the player is mining; only used when the player is mining tiles (holding a tile in the cursor).
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.
The current state
The position being shot at
picking_state
:: boolean
[Read/Write]
Current item-picking state.
repair_state
:: table
[Read/Write]
Current repair state.
The current state
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:
player.cursor_stack.clear()
cursor_ghost
:: ItemPrototypeIdentification
[Read/Write]
The ghost prototype in the player's cursor.
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.
Raised if the driving state successfully changed.
crafting_queue
:: array[CraftingQueueItem]
[Read]
Gets the current crafting queue items.
following_robots
:: array[LuaEntity]
[Read]
The current combat robots following the character
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]
When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
character_mining_speed_modifier
:: double
[Read/Write]
When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
character_additional_mining_categories
:: array[string]
[Read/Write]
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
.
When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
character_build_distance_bonus
:: uint
[Read/Write]
When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
character_item_drop_distance_bonus
:: uint
[Read/Write]
When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
character_reach_distance_bonus
:: uint
[Read/Write]
When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
character_resource_reach_distance_bonus
:: uint
[Read/Write]
When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
character_item_pickup_distance_bonus
:: uint
[Read/Write]
When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
character_loot_pickup_distance_bonus
:: uint
[Read/Write]
When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
character_inventory_slots_bonus
:: uint
[Read/Write]
When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
character_trash_slot_count_bonus
:: uint
[Read/Write]
When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
character_maximum_following_robot_count_bonus
:: uint
[Read/Write]
When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
character_health_bonus
:: float
[Read/Write]
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.