LuaPlayer

class LuaPlayer
set_ending_screen_data(message, file) Setup the screen to be shown when the game is finished.
print(message) Print text to the chat console.
clear_console() Clear the chat console.
get_goal_description() → LocalisedString Get the current goal description, as a localised string.
set_goal_description(text, only_update) Set the text in the goal window (top left).
set_controller{type=…, character=…} Set the controller type of the player.
has_game_view() Does the player have a game view?
build_from_cursor() → boolean Build the entity in the player's cursor (hand).
rotate_for_build() → boolean Rotate the entity in cursor before building.
disable_recipe_groups() Disable recipe groups.
print_entity_statistics(entities) Print entity statistics to the player's console.
get_inventory(inventory) → LuaInventory Get an inventory belonging to this entity.
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.
valid :: boolean [R] Is this object valid?
character :: LuaEntity [RW] The character attached to this player, or nil if no character.
index :: uint [R] This player's index in LuaGameScript::players.
force :: string or LuaForce [RW] The force of this player.
gui :: LuaGui [R]
opened_self :: boolean [R] true if the player opened itself.
controller_type :: controllers [R]
game_view_settings :: GameViewSettings [RW] The player's game view settings.
minimap_enabled :: boolean [RW] true if the minimap is visible.
color :: Color [RW] The colour associated with the player.
name :: string [RW] The player's username.
connected :: boolean [R] true if the player is currently connected to the game.
cursor_position :: Position [W] Position of the player's mouse cursor.
zoom :: double [W] The player's zoom-level.
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.
selected :: LuaEntity [R] The currently selected entity; nil if none.
opened :: LuaEntity [R] The entity whose GUI the player currently has open; nil if none.
crafting_queue_size :: uint [R] Size of the crafting queue.
walking_state [RW] Current walking state.
riding_state [RW] Current riding state of the vehicle the player is currently in.
mining_state [RW] Current mining state.
cursor_stack :: LuaItemStack [R] The player's cursor stack.
driving :: boolean [RW] true if the player is in a vehicle.

A player in the game. Pay attention that a player may or may not have a character, which is the LuaEntity of the little guy running around the world doing things.

set_ending_screen_data(message, file)

Setup the screen to be shown when the game is finished.

Parameters
message :: LocalisedString: Message to be shown.
file :: string (optional): Path to image to be shown.
print(message)

Print text to the chat console.

Parameters
message :: LocalisedString
clear_console()

Clear the chat console.

get_goal_description() → LocalisedString

Get the current goal description, as a localised string.

set_goal_description(text, only_update)

Set the text in the goal window (top left).

Parameters
text :: LocalisedString (optional): The text to display. \n can be used to delimit lines. Passing empty string or omitting this parameter entirely will make the goal window disappear.
only_update :: boolean (optional): When true, won't play the "goal updated" sound.
set_controller{type=…, character=…}

Set the controller type of the player.

Parameters
Table with the following fields:
has_game_view()

Does the player have a game view?

build_from_cursor() → boolean

Build the entity in the player's cursor (hand). The effect is the same as if the player clicked the build button (left mouse).

Return value
true if the building was successfull.
rotate_for_build() → boolean

Rotate the entity in cursor before building.

Return value
true if the rotation was successful.
disable_recipe_groups()

Disable recipe groups.

Note: There is no way to undo this.
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
can_insert(items) → boolean

Can at least some items be inserted?

Parameters
items :: SimpleItemStack: 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 :: SimpleItemStack: 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
    • entity
    • position
    • crafting_queue
      • crafting_queueindex :: uint
    • item_stack
      • inventory_index :: uint
      • 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 :: SimpleItemStack: 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, walls, rail signals or entities with fluid boxes won't allow teleportation and this method will always return false when used on any such entity.
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.

valid :: boolean [Read-only]

Is this object valid? This Lua object holds a reference to an object within the game engine. It is possible that the game-engine object is removed whilst a mod still holds the corresponding Lua object. If that happens, the object becomes invalid, i.e. this attribute will be false. Mods are advised to check for object validity if any change to the game state might have occurred between the creation of the Lua object and its access.

character :: LuaEntity [Read-Write]

The character attached to this player, or nil if no character.

Note: It is not valid to access this attribute when the player is disconnected (see LuaPlayer::connected).
index :: uint [Read-only]

This player's index in LuaGameScript::players.

force :: string or LuaForce [Read-Write]

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

gui :: LuaGui [Read-only]

opened_self :: boolean [Read-only]

true if the player opened itself. I.e. if they opened the character or god-controller GUI.

controller_type :: controllers [Read-only]

game_view_settings :: GameViewSettings [Read-Write]

The player's game view settings.

minimap_enabled :: boolean [Read-Write]

true if the minimap is visible.

color :: Color [Read-Write]

The colour associated with the player. This will be used to tint the player's character as well as their buildings and vehicles.

name :: string [Read-Write]

The player's username.

connected :: boolean [Read-only]

true if the player is currently connected to the game.

cursor_position :: Position [Write-only]

Position of the player's mouse cursor. This is in screen coordinates.

zoom :: double [Write-only]

The player's zoom-level.

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.

selected :: LuaEntity [Read-only]

The currently selected entity; nil if none.

opened :: LuaEntity [Read-only]

The entity whose GUI the player currently has open; nil if none.

crafting_queue_size :: uint [Read-only]

Size of the crafting queue.

walking_state [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.local_player.walking_state = {walking = true, direction = defines.direction.north}
riding_state [Read-Write]

Current riding state of the vehicle the player is currently in. It is a table with two fields:

mining_state [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 the player is mining; not necessary when mining is false.

cursor_stack :: LuaItemStack [Read-only]

The player's cursor stack.

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.