LuaPlayer

class LuaPlayer extends LuaControl - sort
set_ending_screen_data(message, file) Setup the screen to be shown when the game is finished.
print(message, color) 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.
disable_recipe_groups() Disable recipe groups.
enable_recipe_groups() Enable recipe groups.
disable_recipe_subgroups() Disable recipe subgroups.
enable_recipe_subgroups() Enable recipe subgroups.
print_entity_statistics(entities) Print entity statistics to the player's console.
unlock_achievement(name) Unlock the achievements of the given player.
clean_cursor() → boolean Invokes the "clean cursor" action on the player as if the user pressed it.
create_character(character) Creates and attaches a character entity to this player.
add_alert(entity, type) Adds an alert to this player for the given entity of the given alert type.
add_custom_alert(entity, icon, message, show_on_map) Adds a custom alert to this player.
remove_alert{entity=…, prototype=…, position=…, type=…, surface=…, icon=…, message=…} Removes all alerts matching the given filters or if an empty filters table is given all alerts are removed.
get_alerts{entity=…, prototype=…, position=…, type=…, surface=…} → dictionary uintdictionary defines.alert_typearray of alert Gets all alerts matching the given filters or if no filters are given all alerts are returned.
mute_alert(alert_type) → boolean Mutes alerts for the given alert category.
unmute_alert(alert_type) → boolean Unmutes alerts for the given alert category.
is_alert_muted(alert_type) → boolean If the given alert type is currently muted.
enable_alert(alert_type) → boolean Enables alerts for the given alert category.
disable_alert(alert_type) → boolean Disables alerts for the given alert category.
is_alert_enabled(alert_type) → boolean If the given alert type is currently enabled.
pipette_entity(entity) → boolean Invokes the "smart pipette" action on the player as if the user pressed it.
can_place_entity{name=…, position=…, direction=…} → boolean Checks if this player can build the give entity at the given location on the surface the player is on.
can_build_from_cursor{position=…, direction=…, alt=…, terrain_building_size=…, skip_fog_of_war=…} → boolean Checks if this player can build what ever is in the cursor on the surface the player is on.
build_from_cursor{position=…, direction=…, alt=…, terrain_building_size=…, skip_fog_of_war=…} Builds what ever is in the cursor on the surface the player is on.
play_sound{path=…, position=…, volume_modifier=…} → boolean Plays a sound for this player
get_associated_characters() The characters associated with this player.
associate_character(character) Associates a character with this player.
disassociate_character(character) Disassociates a character from this player.
character :: LuaEntity [RW] The character attached to this player, or nil if no character.
index :: uint [R] This player's index in LuaGameScript::players.
gui :: LuaGui [R]
opened_self :: boolean [R] true if the player opened itself.
controller_type :: defines.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 color associated with the player.
chat_color :: Color [RW] The color used when this player talks in game.
name :: string [RW] The player's username.
tag :: string [RW] The tag that is shown after the player in chat and on the map.
connected :: boolean [R] true if the player is currently connected to the game.
admin :: boolean [RW] true if the player is an admin.
entity_copy_source :: LuaEntity [R] The source entity used during entity settings copy-paste if any.
afk_time :: uint [R] How many ticks since the last action of this player
online_time :: uint [R] How many ticks did this player spend playing this save (all sessions combined)
permission_group :: LuaPermissionGroup [RW] The permission group this player is part of or nil if not part of any group.
mod_settings [R]
ticks_to_respawn :: uint [RW] The number of ticks until this player will respawn or nil if not waiting to respawn.
display_resolution :: DisplayResolution [R] The display resolution for this player.
display_scale :: double [R] The display scale for this player.
blueprint_to_setup :: LuaItemStack [R] The item stack containing a blueprint to be setup.
spectator :: boolean [RW] If true, zoom-to-world noise effect will be disabled and environmental sounds will be based on zoom-to-world view instead of position of player's character.
zoom :: double [W] The player's zoom-level.
valid :: boolean [R] Is this object valid?
help() → string All methods, and properties that this object supports.

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, color)

Print text to the chat console.

Parameters
message :: LocalisedString
color :: Color (optional)
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:
disable_recipe_groups()

Disable recipe groups.

enable_recipe_groups()

Enable recipe groups.

disable_recipe_subgroups()

Disable recipe subgroups.

enable_recipe_subgroups()

Enable recipe subgroups.

print_entity_statistics(entities)

Print entity statistics to the player's console.

Parameters
entities :: array of string (optional): Entity prototypes to get statistics for. If not specified or empty, display statistics for all entities.
unlock_achievement(name)

Unlock the achievements of the given player. This has any effect only when this is the local player, the achievement isn't unlocked so far and the achievement is of the type "achievement".

Parameters
name :: string: name of the achievement to unlock
clean_cursor() → boolean

Invokes the "clean cursor" action on the player as if the user pressed it.

Return value
If the cursor is now empty.
create_character(character)

Creates and attaches a character entity to this player.

Parameters
character :: string (optional): The character to create else the default is used.
Note: The player must not have a character already connected and must be online (see LuaPlayer::connected).
add_alert(entity, type)

Adds an alert to this player for the given entity of the given alert type.

Parameters
entity :: LuaEntity
add_custom_alert(entity, icon, message, show_on_map)

Adds a custom alert to this player.

Parameters
entity :: LuaEntity
icon :: SignalID
message :: LocalisedString
show_on_map :: boolean
remove_alert{entity=…, prototype=…, position=…, type=…, surface=…, icon=…, message=…}

Removes all alerts matching the given filters or if an empty filters table is given all alerts are removed.

Parameters
Table with the following fields:
get_alerts{entity=…, prototype=…, position=…, type=…, surface=…} → dictionary uintdictionary defines.alert_typearray of alert

Gets all alerts matching the given filters or if no filters are given all alerts are returned.

A mapping of surface index to an array of arrays of alerts indexed by the alert type. An alert is a table:

  • target :: LuaEntity (optional)
  • prototype :: LuaEntityPrototype (optional)
  • position :: Position (optional)
  • tick :: uint: The tick this alert was created
  • icon :: SignalID (optional): The SignalID used for a custom alert. Only present for custom alerts.
  • message :: LocalisedString (optional): The message for a custom alert. Only present for custom alerts.

Parameters
Table with the following fields:
mute_alert(alert_type) → boolean

Mutes alerts for the given alert category.

Parameters
alert_type :: defines.alert_type
Return value
If the alert type was muted (false if it was already muted).
unmute_alert(alert_type) → boolean

Unmutes alerts for the given alert category.

Parameters
alert_type :: defines.alert_type
Return value
If the alert type was unmuted (false if it was wasn't muted).
is_alert_muted(alert_type) → boolean

If the given alert type is currently muted.

Parameters
alert_type :: defines.alert_type
enable_alert(alert_type) → boolean

Enables alerts for the given alert category.

Parameters
alert_type :: defines.alert_type
Return value
If the alert type was enabled (false if it was already enabled).
disable_alert(alert_type) → boolean

Disables alerts for the given alert category.

Parameters
alert_type :: defines.alert_type
Return value
If the alert type was disabled (false if it was already disabled).
is_alert_enabled(alert_type) → boolean

If the given alert type is currently enabled.

Parameters
alert_type :: defines.alert_type
pipette_entity(entity) → boolean

Invokes the "smart pipette" action on the player as if the user pressed it.

Parameters
Return value
If the smart pipette found something to place
can_place_entity{name=…, position=…, direction=…} → boolean

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

Parameters
Table with the following fields:
  • name :: string: Name of the entity to check
  • position :: Position: Where the entity would be placed
  • direction :: defines.direction (optional): Direction the entity would be placed
can_build_from_cursor{position=…, direction=…, alt=…, terrain_building_size=…, skip_fog_of_war=…} → boolean

Checks if this player can build what ever is in the cursor on the surface the player is on.

Parameters
Table with the following fields:
  • position :: Position: Where the entity would be placed
  • direction :: defines.direction (optional): Direction the entity would be placed
  • alt :: boolean (optional): If alt build should be used instead of normal build. Defaults to normal.
  • terrain_building_size :: uint (optional): The size for building terrain if building terrain. Defaults to 2.
  • skip_fog_of_war :: boolean (optional): If chunks covered by fog-of-war are skipped.
build_from_cursor{position=…, direction=…, alt=…, terrain_building_size=…, skip_fog_of_war=…}

Builds what ever is in the cursor on the surface the player is on.

Parameters
Table with the following fields:
  • position :: Position: Where the entity would be placed
  • direction :: defines.direction (optional): Direction the entity would be placed
  • alt :: boolean (optional): If alt build should be used instead of normal build. Defaults to normal.
  • terrain_building_size :: uint (optional): The size for building terrain if building terrain. Defaults to 2.
  • skip_fog_of_war :: boolean (optional): If chunks covered by fog-of-war are skipped.
Note: Anything built will fire normal player-built events.
Note: The cursor stack will automatically be reduced as if the player built normally.
play_sound{path=…, position=…, volume_modifier=…} → boolean

Plays a sound for this player

Parameters
Table with the following fields:
  • path :: SoundPath: The sound to play
  • position :: Position (optional): Where the sound should be played. If not given it's played 'everywhere'.
  • volume_modifier :: double (optional): Must be between 0 and 1 inclusive.
get_associated_characters()

The characters associated with this player.

Note: The array will always be empty when the player is disconnected (see LuaPlayer::connected) regardless of there being associated characters.
Note: Characters associated with this player will be logged off when this player disconnects but are not controlled by any player.
associate_character(character)

Associates a character with this player.

Parameters
character :: LuaEntity: The character entity.
Note: The character must not be connected to any controller.
Note: If this player is currently disconnected (see LuaPlayer::connected) the character will be immediately "logged off".
Note: See LuaPlayer::get_associated_characters for more information.
disassociate_character(character)

Disassociates a character from this player. This is functionally the same as setting LuaEntity::associated_player to nil.

Parameters
character :: LuaEntity: The character entity
Note: See LuaPlayer::get_associated_characters for more information.
character :: LuaEntity [Read-Write]

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

Note: Will also return nil when the player is disconnected (see LuaPlayer::connected).
index :: uint [Read-only]

This player's index in LuaGameScript::players.

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 :: defines.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 color associated with the player. This will be used to tint the player's character as well as their buildings and vehicles.

chat_color :: Color [Read-Write]

The color used when this player talks in game.

name :: string [Read-Write]

The player's username.

tag :: string [Read-Write]

The tag that is shown after the player in chat and on the map.

connected :: boolean [Read-only]

true if the player is currently connected to the game.

admin :: boolean [Read-Write]

true if the player is an admin.

Note: Trying to change player admin status from the console when you aren't an admin does nothing.
entity_copy_source :: LuaEntity [Read-only]

The source entity used during entity settings copy-paste if any.

nil if there isn't currently a source entity.

afk_time :: uint [Read-only]

How many ticks since the last action of this player

online_time :: uint [Read-only]

How many ticks did this player spend playing this save (all sessions combined)

permission_group :: LuaPermissionGroup [Read-Write]

The permission group this player is part of or nil if not part of any group.

mod_settings [Read-only]

Note: This can become invalid if during operation this player becomes invalid.
ticks_to_respawn :: uint [Read-Write]

The number of ticks until this player will respawn or nil if not waiting to respawn.

Note: Set to nil to immediately respawn the player.
Note: Set to any positive value to trigger the respawn state for this player.
display_resolution :: DisplayResolution [Read-only]

The display resolution for this player.

display_scale :: double [Read-only]

The display scale for this player.

blueprint_to_setup :: LuaItemStack [Read-only]

The item stack containing a blueprint to be setup.

spectator :: boolean [Read-Write]

If true, zoom-to-world noise effect will be disabled and environmental sounds will be based on zoom-to-world view instead of position of player's character.

zoom :: double [Write-only]

The player's zoom-level.