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.

Attributes

surface

• Read: LuaSurface
• Write: unknown
• Optional: false

The surface this entity is currently on.

surface_index

• Read: uint32
• Write: unknown
• Optional: false

Unique index (ID) associated with the surface this entity is currently on.

position

• Read: MapPosition
• Write: unknown
• Optional: false

The current position of the entity.

render_position

• Read: MapPosition
• Write: unknown
• Optional: false

The current render position of the entity.

is_flying

• Read: boolean
• Write: unknown
• Optional: false

If this player or character entity is flying.

When called on an entity, only valid if this entity is a character.

flight_height

• Read: double
• Write: unknown
• Optional: false

The current flight height for this player or character entity.

When called on an entity, only valid if this entity is a character.

vehicle

• Read: LuaEntity
• Write: unknown
• Optional: true

The vehicle the player is currently sitting in.

cargo_pod

• Read: LuaEntity
• Write: unknown
• Optional: true

The cargo pod the player is currently sitting in or the cargo pod attached to this rocket silo.

hub

• Read: LuaEntity
• Write: unknown
• Optional: true

The space platform hub the player is currently sitting in.

force

• Read: LuaForce
• Write: ForceID
• Optional: false

The force of this entity. Reading will always give a LuaForce, but it is possible to assign either string, uint8 or LuaForce to this attribute to change the force.

force_index

• Read: uint32
• Write: unknown
• Optional: false

Unique index (ID) associated with the force of this entity.

selected

• Read: LuaEntity
• Write: LuaEntity
• Optional: true

The currently selected entity. Assigning an entity will select it if is selectable, otherwise the selection is cleared.

opened

• Read: LuaEntity | LuaItemStack | LuaEquipment | LuaEquipmentGrid | LuaPlayer | LuaGuiElement | LuaInventory | LuaLogisticNetwork | LuaItemStack | defines.gui_type
• Write: LuaEntity | LuaItemStack | LuaEquipment | LuaEquipmentGrid | LuaPlayer | LuaGuiElement | LuaInventory | LuaLogisticNetwork | LuaItemStack | defines.gui_type
• Optional: true

The GUI the player currently has 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 non-nil, then writing nil or a new GUI to it will ask the existing GUI to close.

Write supports any of the types. Read will return the entity, equipment, equipment-grid, player, element, inventory, item or nil.

crafting_queue_size

• Read: uint32
• Write: unknown
• Optional: false

Size of the crafting queue.

crafting_queue_progress

• Read: double
• Write: double
• Optional: false

The crafting queue progress in the range [0-1]. 0 when no recipe is being crafted.

walking_state

• Read: { direction: defines.direction, walking: boolean }
• Write: { direction: defines.direction, walking: boolean }
• Optional: false

Current walking state of the player, or the spider-vehicle the character is driving.

riding_state

• Read: RidingState
• Write: RidingState
• Optional: false

Current riding state of this car, or of the car this player is riding in.

mining_state

• Read: { mining: boolean, position?: MapPosition }
• Write: { mining: boolean, position?: MapPosition }
• Optional: false

Current mining state.

When the player isn't mining tiles the player will mine whatever entity is currently selected. See LuaControl::selected and LuaControl::update_selected_entity.

shooting_state

• Read: { position: MapPosition, state: defines.shooting }
• Write: { position: MapPosition, state: defines.shooting }
• Optional: false

Current shooting state.

picking_state

• Read: boolean
• Write: boolean
• Optional: false

Current item-picking state.

repair_state

• Read: { position: MapPosition, repairing: boolean }
• Write: { position: MapPosition, repairing: boolean }
• Optional: false

Current repair state.

cursor_stack

• Read: LuaItemStack
• Write: unknown
• Optional: true

The player's cursor stack. nil if the player controller is a spectator.

cursor_ghost

• Read: ItemIDAndQualityIDPair
• Write: ItemWithQualityID
• Optional: true

The ghost prototype in the player's cursor.

Items in the cursor stack will take priority over the cursor ghost.

cursor_record

• Read: LuaRecord
• Write: unknown
• Optional: true

The blueprint record in the player's cursor.

driving

• Read: boolean
• Write: boolean
• Optional: false

true if the player is in a vehicle. Writing to this attribute puts the player in or out of a vehicle.

crafting_queue

• Read: Array<CraftingQueueItem>
• Write: unknown
• Optional: false

The current crafting queue items.

following_robots

• Read: Array<LuaEntity>
• Write: unknown
• Optional: false

The current combat robots following the character.

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).

cheat_mode

• Read: boolean
• Write: boolean
• Optional: false

When true hand crafting is free and instant.

character_crafting_speed_modifier

• Read: double
• Write: double
• Optional: false

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).

character_mining_speed_modifier

• Read: double
• Write: double
• Optional: false

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).

character_additional_mining_categories

• Read: Array<string>
• Write: Array<string>
• Optional: false

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).

character_running_speed_modifier

• Read: double
• Write: double
• Optional: false

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

• Read: uint32
• Write: uint32
• Optional: false

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).

character_item_drop_distance_bonus

• Read: uint32
• Write: uint32
• Optional: false

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).

character_reach_distance_bonus

• Read: uint32
• Write: uint32
• Optional: false

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).

character_resource_reach_distance_bonus

• Read: uint32
• Write: uint32
• Optional: false

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).

character_item_pickup_distance_bonus

• Read: uint32
• Write: uint32
• Optional: false

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).

character_loot_pickup_distance_bonus

• Read: uint32
• Write: uint32
• Optional: false

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).

character_inventory_slots_bonus

• Read: uint32
• Write: uint32
• Optional: false

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).

character_trash_slot_count_bonus

• Read: uint32
• Write: uint32
• Optional: false

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).

character_maximum_following_robot_count_bonus

• Read: uint32
• Write: uint32
• Optional: false

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).

character_health_bonus

• Read: float
• Write: float
• Optional: false

When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).

opened_gui_type

• Read: defines.gui_type
• Write: unknown
• Optional: true

build_distance

• Read: uint32
• Write: unknown
• Optional: false

The build distance of this character or max uint when not a character or player connected to a character.

drop_item_distance

• Read: uint32
• Write: unknown
• Optional: false

The item drop distance of this character or max uint when not a character or player connected to a character.

reach_distance

• Read: uint32
• Write: unknown
• Optional: false

The reach distance of this character or max uint when not a character or player connected to a character.

item_pickup_distance

• Read: double
• Write: unknown
• Optional: false

The item pickup distance of this character or max double when not a character or player connected to a character.

loot_pickup_distance

• Read: double
• Write: unknown
• Optional: false

The loot pickup distance of this character or max double when not a character or player connected to a character.

resource_reach_distance

• Read: double
• Write: unknown
• Optional: false

The resource reach distance of this character or max double when not a character or player connected to a character.

in_combat

• Read: boolean
• Write: unknown
• Optional: false

Whether this character entity is in combat.

character_running_speed

• Read: double
• Write: unknown
• Optional: false

The current movement speed of this character, including effects from exoskeletons, tiles, stickers and shooting.

character_mining_progress

• Read: double
• Write: unknown
• Optional: false

The current mining progress between 0 and 1 of this character, or 0 if they aren't mining.

Methods

get_inventory

LuaControl.get_inventory(inventory: defines.inventory) -> LuaInventory?

Call As

player.get_inventory(inventory)

Call Convention

• takes_table: false
• table_optional: false

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.

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.

Parameters

• inventory: defines.inventory

Returns

• LuaInventory? — The inventory or nil if none with the given index was found.

get_inventory_name

LuaControl.get_inventory_name(inventory: defines.inventory) -> string?

Call As

player.get_inventory_name(inventory)

Call Convention

• takes_table: false
• table_optional: false

Get name of inventory. Names match keys of defines.inventory.

Parameters

• inventory: defines.inventory

Returns

• string?

get_max_inventory_index

LuaControl.get_max_inventory_index() -> defines.inventory

Call As

player.get_max_inventory_index()

Call Convention

• takes_table: false
• table_optional: false

The highest index of all inventories this entity can use. Allows iteration over all of them if desired.

Returns

• defines.inventory

get_main_inventory

LuaControl.get_main_inventory() -> LuaInventory?

Call As

player.get_main_inventory()

Call Convention

• takes_table: false
• table_optional: false

Gets the main inventory for this character or player if this is a character or player.

Returns

• LuaInventory? — The inventory or nil if this entity is not a character or player.

can_insert

LuaControl.can_insert(items: ItemStackIdentification) -> boolean

Call As

player.can_insert(items)

Call Convention

• takes_table: false
• table_optional: false

Can at least some items be inserted?

Parameters

• items: ItemStackIdentification — Items that would be inserted.

Returns

• boolean — true if at least a part of the given items could be inserted into this inventory.

insert

LuaControl.insert(items: ItemStackIdentification) -> uint32

Call As

player.insert(items)

Call Convention

• takes_table: false
• table_optional: false

Insert items into this entity. This works the same way as inserters or shift-clicking: the "best" inventory is chosen automatically.

Parameters

• items: ItemStackIdentification — The items to insert.

Returns

• uint32 — The number of items that were actually inserted.

set_gui_arrow

LuaControl.set_gui_arrow{ margin: uint32, type: GuiArrowType }

Call As

player.set_gui_arrow{ margin=margin, type=type }

Call Convention

• takes_table: true
• table_optional: false

Create an arrow which points at this entity. This is used in the tutorial. For examples, see control.lua in the campaign missions.

Parameters

• margin: uint32
• type: GuiArrowType — Where to point to. This field determines what other fields are mandatory.

clear_gui_arrow

LuaControl.clear_gui_arrow()

Call As

player.clear_gui_arrow()

Call Convention

• takes_table: false
• table_optional: false

Removes the arrow created by set_gui_arrow.

get_item_count

LuaControl.get_item_count(item?: ItemFilter) -> uint32

Call As

player.get_item_count()

Call Convention

• takes_table: false
• table_optional: false

Get the number of all or some items in this entity.

Parameters

• item?: ItemFilter — The item to count. If not specified, count all items.

Returns

• uint32

has_items_inside

LuaControl.has_items_inside() -> boolean

Call As

player.has_items_inside()

Call Convention

• takes_table: false
• table_optional: false

Does this entity have any item inside it?

Returns

• boolean

can_reach_entity

LuaControl.can_reach_entity(entity: LuaEntity) -> boolean

Call As

player.can_reach_entity(entity)

Call Convention

• takes_table: false
• table_optional: false

Can a given entity be opened or accessed?

Parameters

• entity: LuaEntity

Returns

• boolean

clear_items_inside

LuaControl.clear_items_inside()

Call As

player.clear_items_inside()

Call Convention

• takes_table: false
• table_optional: false

Remove all items from this entity.

remove_item

LuaControl.remove_item(items: ItemStackIdentification) -> uint32

Call As

player.remove_item(items)

Call Convention

• takes_table: false
• table_optional: false

Remove items from this entity.

Parameters

• items: ItemStackIdentification — The items to remove.

Returns

• uint32 — The number of items that were actually removed.

teleport

LuaControl.teleport(position: MapPosition, surface?: SurfaceIdentification, raise_teleported?: boolean, snap_to_grid?: boolean, build_check_type?: defines.build_check_type) -> boolean

Call As

player.teleport(position, surface)

Call Convention

• takes_table: false
• table_optional: false

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

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.

script_raised_teleported will not be raised if teleporting a player with no character.

Parameters

• position: MapPosition — Where to teleport to.
• surface?: SurfaceIdentification — 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.
• raise_teleported?: boolean — If true, defines.events.script_raised_teleported will be fired on successful entity teleportation.
• snap_to_grid?: boolean — If false the exact position given is used to instead of snapping to the normal entity grid. This only applies if the entity normally snaps to the grid.
• build_check_type?: defines.build_check_type — The build check type done when teleporting to the destination. Defaults to script. This is ignored when teleporting between surfaces.

Returns

• boolean — true if the entity was successfully teleported.

update_selected_entity

LuaControl.update_selected_entity(position: MapPosition)

Call As

player.update_selected_entity(position)

Call Convention

• takes_table: false
• table_optional: false

Select an entity, as if by hovering the mouse above it.

Parameters

• position: MapPosition — Position of the entity to select.

clear_selected_entity

LuaControl.clear_selected_entity()

Call As

player.clear_selected_entity()

Call Convention

• takes_table: false
• table_optional: false

Unselect any selected entity.

disable_flashlight

LuaControl.disable_flashlight()

Call As

player.disable_flashlight()

Call Convention

• takes_table: false
• table_optional: false

Disable the flashlight.

Applied per controller. Only supported by defines.controllers.character and defines.controllers.remote.

enable_flashlight

LuaControl.enable_flashlight()

Call As

player.enable_flashlight()

Call Convention

• takes_table: false
• table_optional: false

Enable the flashlight.

Applied per controller. Only supported by defines.controllers.character and defines.controllers.remote.

is_flashlight_enabled

LuaControl.is_flashlight_enabled() -> boolean

Call As

player.is_flashlight_enabled()

Call Convention

• takes_table: false
• table_optional: false

Is the flashlight enabled for the current controller. Only supported by defines.controllers.character and defines.controllers.remote.

Returns

• boolean

get_craftable_count

LuaControl.get_craftable_count(recipe: RecipeID) -> uint32

Call As

player.get_craftable_count(recipe)

Call Convention

• takes_table: false
• table_optional: false

Gets the count of the given recipe that can be crafted.

Parameters

• recipe: RecipeID — The recipe.

Returns

• uint32 — The count that can be crafted.

begin_crafting

LuaControl.begin_crafting{ count: uint32, recipe: RecipeID, silent?: boolean } -> uint32

Call As

player.begin_crafting{ count=count, recipe=recipe }

Call Convention

• takes_table: true
• table_optional: false

Begins crafting the given count of the given recipe.

Parameters

• count: uint32 — The count to craft.
• recipe: RecipeID — The recipe to craft.
• silent?: boolean — If false and the recipe can't be crafted the requested number of times printing the failure is skipped.

Returns

• uint32 — The count that was actually started crafting.

cancel_crafting

LuaControl.cancel_crafting{ index: uint32, count: uint32 }

Call As

player.cancel_crafting{ index=index, count=count }

Call Convention

• takes_table: true
• table_optional: false

Cancels the given amount of crafts at the given crafting queue position. If this causes any later crafts that depend on the cancelled one to have insufficient ingredients, those crafts will also be cancelled.

Parameters

• index: uint32 — The crafting queue index.
• count: uint32 — The count to cancel crafting.

mine_entity

LuaControl.mine_entity(entity: LuaEntity, force?: boolean) -> boolean

Call As

player.mine_entity(entity, true)

Call Convention

• takes_table: false
• table_optional: false

Mines the given entity as if this player (or character) mined it.

Parameters

• entity: LuaEntity — The entity to mine
• force?: boolean — Forces mining the entity even if the items can't fit in the player.

Returns

• boolean — Whether the mining succeeded.

mine_tile

LuaControl.mine_tile(tile: LuaTile) -> boolean

Call As

player.mine_tile(tile)

Call Convention

• takes_table: false
• table_optional: false

Mines the given tile as if this player (or character) mined it.

Parameters

• tile: LuaTile — The tile to mine.

Returns

• boolean — Whether the mining succeeded.

is_player

LuaControl.is_player() -> boolean

Call As

player.is_player()

Call Convention

• takes_table: false
• table_optional: false

When true control adapter is a LuaPlayer object, false for entities including characters with players.

Returns

• boolean

open_technology_gui

LuaControl.open_technology_gui(technology?: TechnologyID)

Call As

player.open_technology_gui()

Call Convention

• takes_table: false
• table_optional: false

Open the technology GUI and select a given technology.

Parameters

• technology?: TechnologyID — The technology to select after opening the GUI.

open_factoriopedia_gui

LuaControl.open_factoriopedia_gui(prototype?: FactoriopediaID)

Call As

player.open_factoriopedia_gui()

Call Convention

• takes_table: false
• table_optional: false

Open the Factoriopedia GUI and select a given entry, if any valid ID is given.

Parameters

• prototype?: FactoriopediaID

close_factoriopedia_gui

LuaControl.close_factoriopedia_gui()

Call As

player.close_factoriopedia_gui()

Call Convention

• takes_table: false
• table_optional: false

Closes the Factoriopedia GUI if it's open.

is_cursor_blueprint

LuaControl.is_cursor_blueprint() -> boolean

Call As

player.is_cursor_blueprint()

Call Convention

• takes_table: false
• table_optional: false

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 refers to the currently selected blueprint, which means that a blueprint book with a selected blueprint will return the information as well.

Returns

• boolean

is_cursor_empty

LuaControl.is_cursor_empty() -> boolean

Call As

player.is_cursor_empty()

Call Convention

• takes_table: false
• table_optional: false

Returns whether the player is holding something in the cursor. Takes into account items from the blueprint library, as well as items and ghost cursor.

Returns

• boolean

get_requester_point

LuaControl.get_requester_point() -> LuaLogisticPoint?

Call As

player.get_requester_point()

Call Convention

• takes_table: false
• table_optional: false

Gets the requester logistic point for this entity if it has one.

Returns

• LuaLogisticPoint?

set_driving

LuaControl.set_driving(driving: boolean, force?: boolean)

Call As

player.set_driving(true, true)

Call Convention

• takes_table: false
• table_optional: false

Sets if this character or player is driving. Returns if the player or character is still driving.

Parameters

• driving: boolean — True for enter-vehicle, false for leave.
• force?: boolean — If true, the player will be ejected and left at the position of the car if normal "leave" is not possible.

can_place_entity

LuaControl.can_place_entity{ name: EntityID, position: MapPosition, direction?: defines.direction } -> boolean

Call As

player.can_place_entity{ name="name", position=position }

Call Convention

• takes_table: true
• table_optional: false

Checks if this character or player can build the given entity at the given location on the surface the character or player is on.

Parameters

• name: EntityID — Name of the entity that would be built.
• position: MapPosition — Where the entity would be placed.
• direction?: defines.direction — Direction the entity would be facing. Defaults to north.

Returns

• boolean