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.
or nil
if this entity doesn't have an inventory with the given index.
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.
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.
Items to insert.
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.
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"
.
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.
Items to remove.
Number of items 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
when the entity was successfully teleported.
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
get_craftable_count
(recipe)
→ uint
begin_crafting
{count,
recipe,
silent}
→ uint
Begins crafting the given count of the given recipe.
The count that was actually started crafting.
mine_entity
(entity,
force)
→ boolean
mine_tile
(tile)
→ boolean
Mines the given tile as if this player (or character) mined it.
The tile to mine.
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.
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.
set_vehicle_logistic_slot
(slot_index,
value)
→ boolean
Sets a vehicle 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 the vehicle does not use logistics.
get_personal_logistic_slot
(slot_index)
→ LogisticParameters
Gets the parameters of a personal logistic request and auto-trash slot.
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.
This will silently fail if personal logistics are not researched yet.
clear_vehicle_logistic_slot
(slot_index)
The slot to clear.
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.
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.
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. Writing to it fires the on_gui_opened event.
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.
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]
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.
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]
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.
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.