LuaPlayer

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.

Parent

• LuaControl

Attributes

physical_surface

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

The surface this player's physical controller is on.

physical_surface_index

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

Unique ID associated with the surface this player's physical controller is currently on.

physical_position

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

The current position of this player's physical controller.

physical_vehicle

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

The current vehicle of this player's physical controller.

character

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

The character attached to this player, if any. Returns nil when the player is disconnected (see LuaPlayer::connected).

cutscene_character

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

When in a cutscene; the character this player would be using once the cutscene is over, if any. Returns nil when the player is disconnected (see LuaPlayer::connected).

index

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

This player's index in LuaGameScript::players (unique ID). It is assigned when a player is created, and remains so (even when the player is not connected) until the player is irreversibly removed. Indexes of removed players can be reused.

gui

• Read: LuaGui
• Write: unknown
• Optional: false

opened_self

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

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

controller_type

• Read: defines.controllers
• Write: unknown
• Optional: false

physical_controller_type

• Read: defines.controllers
• Write: unknown
• Optional: false

The player's "physical" controller. When a player is in the remote controller, this specifies the controller they will return to. When the player is not in the remote controller, this is equivalent to LuaPlayer::controller_type.

stashed_controller_type

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

The stashed controller type, if any. This is mainly useful when a player is in the map editor.

spidertron_remote_selection

• Read: Array<LuaEntity>
• Write: Array<LuaEntity>
• Optional: true

All SpiderVehicles currently selected by the player, if they are holding a spidertron remote.

zoom

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

The current player controller's zoom level. Must be positive. The baseline zoom level is 1. Values greater than 1 will zoom in closer to the world and values between 0 and 1 will zoom out away from the world.

Writing values outside the current zoom limits is always valid, but read values will always be clamped to the range defined by LuaPlayer::zoom_limits.

zoom_limits

• Read: ZoomLimits
• Write: ZoomLimits
• Optional: false

The player's current controller's zoom limits.

Reading this field creates a copy, so modifying the returned table's fields directly will not alter the player's zoom limits. To change the zoom limits for the player's current controller, set the entire field to the desired ZoomLimits table.

Zoom limits are defined and remembered per controller type. If you set the zoom limits of the character controller, then every time the player uses the character controller, it will remember and use the zoom limits previously set. However, other controller types will not use the character controller zoom limits; each controller type must have its zoom limits defined separately.

To set the zoom limits of ANY controller type, not just the currently active one, use LuaPlayer::set_zoom_limits.

centered_on

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

The entity being centered on in remote view.

When writing, the player will be switched to remote view (if not already in it) and centered on the given entity.

game_view_settings

• Read: GameViewSettings
• Write: GameViewSettings
• Optional: false

The player's game view settings.

minimap_enabled

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

true if the minimap is visible.

color

• Read: Color
• Write: Color
• Optional: false

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

• Read: Color
• Write: Color
• Optional: false

The color used when this player talks in game.

name

• Read: string
• Write: unknown
• Optional: false

The player's username.

tag

• Read: string
• Write: string
• Optional: false

The tag that is shown after the player in chat, on the map and above multiplayer selection rectangles.

connected

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

true if the player is currently connected to the game.

admin

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

true if the player is an admin.

Trying to change player admin status from the console when you aren't an admin does nothing.

entity_copy_source

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

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

afk_time

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

How many ticks since the last action of this player.

online_time

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

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

last_online

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

At what tick this player was last online.

permission_group

• Read: LuaPermissionGroup
• Write: LuaPermissionGroup
• Optional: true

The permission group this player is part of, if any.

mod_settings

• Read: LuaCustomTable<string, ModSetting>
• Write: unknown
• Optional: false

The current per-player settings for the this player, indexed by prototype name. Returns the same structure as LuaSettings::get_player_settings. This table becomes invalid if its associated player does.

Even though this attribute is marked as read-only, individual settings can be changed by overwriting their ModSetting table. Mods can only change their own settings. Using the in-game console, all player settings can be changed.

ticks_to_respawn

• Read: uint32
• Write: uint32
• Optional: true

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

Set to nil to immediately respawn the player.

Set to any positive value to trigger the respawn state for this player.

display_resolution

• Read: DisplayResolution
• Write: unknown
• Optional: false

The display resolution for this player.

During on_player_created, this attribute will always return a resolution of {width=1920, height=1080}. To get the actual resolution, listen to the on_player_display_resolution_changed event raised shortly afterwards.

display_scale

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

The display scale for this player.

During on_player_created, this attribute will always return a scale of 1. To get the actual scale, listen to the on_player_display_scale_changed event raised shortly afterwards.

display_density_scale

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

The display density scale for this player. The display density scale is the factor of LuaPlayer::display_scale that is determined by the physical DPI of the screen that Factorio is running on. In most cases, the default value is 1. If the player is playing on a high-density display, this value may be 2 or greater.

During on_player_created, this attribute will always return a scale of 1. To get the actual scale, listen to the on_player_display_density_scale_changed event raised shortly afterwards.

locale

• Read: string
• Write: unknown
• Optional: false

The active locale for this player.

During on_player_created, this attribute will be en. To get the actual value, listen to the on_player_locale_changed event raised shortly afterwards.

blueprint_to_setup

• Read: LuaItemStack
• Write: unknown
• Optional: false

The item stack containing a blueprint to be setup.

blueprints

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

Records contained in the player's blueprint library.

render_mode

• Read: defines.render_mode
• Write: unknown
• Optional: false

The render mode of the player, like map or zoom to world.

input_method

• Read: defines.input_method
• Write: unknown
• Optional: false

The input method of the player, mouse and keyboard or game controller

spectator

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

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.

show_on_map

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

If true, circle and name of given player is rendered on the map/chart.

remove_unfiltered_items

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

If items not included in this map editor infinity inventory filters should be removed.

infinity_inventory_filters

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

The filters for this map editor infinity inventory settings.

auto_sort_main_inventory

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

If the main inventory will be auto sorted.

hand_location

• Read: ItemStackLocation
• Write: ItemStackLocation
• Optional: true

The original location of the item in the cursor, marked with a hand. nil if the cursor stack is empty. When writing, the specified inventory slot must be empty and the cursor stack must not be empty.

cursor_stack_temporary

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

Returns true if the current item stack in cursor will be destroyed after clearing the cursor. Manually putting it into inventory still preserves the item. If the cursor stack is not one of the supported types (blueprint, blueprint-book, deconstruction-planner, upgrade-planner), write operation will be silently ignored.

undo_redo_stack

• Read: LuaUndoRedoStack
• Write: unknown
• Optional: false

The undo and redo stack for this player.

drag_target

• Read: DragTarget
• Write: unknown
• Optional: true

The wire drag target for this player, if any.

map_view_settings

• Read: unknown
• Write: MapViewSettings
• Optional: false

The player's map view settings. To write to this, use a table containing the fields that should be changed.

valid

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

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.

object_name

• Read: string
• Write: unknown
• Optional: false

The class name of this object. Available even when valid is false. For LuaStruct objects it may also be suffixed with a dotted path to a member of the struct.

Methods

set_ending_screen_data

LuaPlayer.set_ending_screen_data(message: LocalisedString, file?: string)

Call As

player.set_ending_screen_data(message, file)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

• message: LocalisedString — Message to be shown.
• file?: string — Path to image to be shown.

print

LuaPlayer.print(message: LocalisedString, print_settings?: PrintSettings)

Call As

player.print(message, print_settings)

Call Convention

• takes_table: false
• table_optional: false

Print text to the chat console.

By default, messages that are identical to a message sent in the last 60 ticks are not printed again.

Parameters

• message: LocalisedString
• print_settings?: PrintSettings

clear_console

LuaPlayer.clear_console()

Call As

player.clear_console()

Call Convention

• takes_table: false
• table_optional: false

Clear the chat console.

get_goal_description

LuaPlayer.get_goal_description() -> LocalisedString

Call As

player.get_goal_description()

Call Convention

• takes_table: false
• table_optional: false

Get the current goal description, as a localised string.

Returns

• LocalisedString

set_goal_description

LuaPlayer.set_goal_description(text?: LocalisedString, only_update?: boolean)

Call As

player.set_goal_description()

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

• text?: LocalisedString — The text to display. Lines can be delimited with \n. Passing an empty string or omitting this parameter entirely will make the goal window disappear.
• only_update?: boolean — When true, won't play the "goal updated" sound.

set_controller

LuaPlayer.set_controller{ type: defines.controllers, character?: LuaEntity, waypoints?: Array<CutsceneWaypoint>, start_position?: MapPosition, start_zoom?: double, final_transition_time?: uint32, chart_mode_cutoff?: double, position?: MapPosition, surface?: SurfaceIdentification }

Call As

player.set_controller{ type=type }

Call Convention

• takes_table: true
• table_optional: false

Set the controller type of the player.

Setting a player to defines.controllers.editor auto promotes the player to admin and enables cheat mode. Setting a player to defines.controllers.editor also requires the calling player be an admin.

Parameters

• type: defines.controllers — Which controller to use.
• character?: LuaEntity — Entity to control. Mandatory when type is defines.controllers.character, ignored otherwise.
• waypoints?: Array<CutsceneWaypoint> — List of waypoints for the cutscene controller. This parameter is mandatory when type is defines.controllers.cutscene.
• start_position?: MapPosition — If specified and type is defines.controllers.cutscene, the cutscene will start at this position. If not given the start position will be the player position.
• start_zoom?: double — If specified and type is defines.controllers.cutscene, the cutscene will start at this zoom level. If not given the start zoom will be the player's zoom.
• final_transition_time?: uint32 — If specified and type is defines.controllers.cutscene, it is the time in ticks it will take for the camera to pan from the final waypoint back to the starting position. If not given the camera will not pan back to the start position/zoom.
• chart_mode_cutoff?: double — If specified and type is defines.controllers.cutscene, the game will switch to chart-mode (map zoomed out) rendering when the zoom level is less than this value.
• position?: MapPosition — If specified and type is defines.controllers.remote, the position the remote controller will be centered on.
• surface?: SurfaceIdentification — If specified and type is defines.controllers.remote, the surface the remote controller will be put on.

drag_wire

LuaPlayer.drag_wire{ position: MapPosition } -> boolean

Call As

player.drag_wire{ position=position }

Call Convention

• takes_table: true
• table_optional: false

Start/end wire dragging at the specified location, wire type is based on the cursor contents

Parameters

• position: MapPosition — Position at which cursor was clicked. Used only to decide which side of arithmetic combinator, decider combinator or power switch is to be connected. Entity itself to be connected is based on the player's selected entity.

Returns

• boolean — true if the action did something

disable_recipe_groups

LuaPlayer.disable_recipe_groups()

Call As

player.disable_recipe_groups()

Call Convention

• takes_table: false
• table_optional: false

Disable recipe groups.

enable_recipe_groups

LuaPlayer.enable_recipe_groups()

Call As

player.enable_recipe_groups()

Call Convention

• takes_table: false
• table_optional: false

Enable recipe groups.

disable_recipe_subgroups

LuaPlayer.disable_recipe_subgroups()

Call As

player.disable_recipe_subgroups()

Call Convention

• takes_table: false
• table_optional: false

Disable recipe subgroups.

enable_recipe_subgroups

LuaPlayer.enable_recipe_subgroups()

Call As

player.enable_recipe_subgroups()

Call Convention

• takes_table: false
• table_optional: false

Enable recipe subgroups.

print_entity_statistics

LuaPlayer.print_entity_statistics(entities?: Array<EntityWithQualityID>)

Call As

player.print_entity_statistics()

Call Convention

• takes_table: false
• table_optional: false

Print entity statistics to the player's console.

Parameters

• entities?: Array<EntityWithQualityID> — Entity prototypes to get statistics for. If not specified or empty, display statistics for all entities.

print_robot_jobs

LuaPlayer.print_robot_jobs()

Call As

player.print_robot_jobs()

Call Convention

• takes_table: false
• table_optional: false

Print construction robot job counts to the player's console.

print_lua_object_statistics

LuaPlayer.print_lua_object_statistics()

Call As

player.print_lua_object_statistics()

Call Convention

• takes_table: false
• table_optional: false

Print LuaObject counts per mod.

unlock_achievement

LuaPlayer.unlock_achievement(name: string)

Call As

player.unlock_achievement(name)

Call Convention

• takes_table: false
• table_optional: false

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

clear_cursor

LuaPlayer.clear_cursor() -> boolean

Call As

player.clear_cursor()

Call Convention

• takes_table: false
• table_optional: false

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

Returns

• boolean — Whether the cursor is now empty.

create_character

LuaPlayer.create_character(character?: EntityWithQualityID) -> boolean

Call As

player.create_character()

Call Convention

• takes_table: false
• table_optional: false

Creates and attaches a character entity to this player.

The player must not have a character already connected and must be online (see LuaPlayer::connected).

Parameters

• character?: EntityWithQualityID — The character to create else the default is used.

Returns

• boolean — Whether the character was created.

add_alert

LuaPlayer.add_alert(entity: LuaEntity, type: defines.alert_type)

Call As

player.add_alert(entity, type)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

• entity: LuaEntity
• type: defines.alert_type

add_custom_alert

LuaPlayer.add_custom_alert(entity: LuaEntity, icon: SignalID, message: LocalisedString, show_on_map: boolean)

Call As

player.add_custom_alert(entity, icon, message, true)

Call Convention

• takes_table: false
• table_optional: false

Adds a custom alert to this player.

Parameters

• entity: LuaEntity — If the alert is clicked, the map will open at the position of this entity.
• icon: SignalID
• message: LocalisedString
• show_on_map: boolean

remove_alert

LuaPlayer.remove_alert{ entity?: LuaEntity, prototype?: EntityID, position?: MapPosition, type?: defines.alert_type, surface?: SurfaceIdentification, icon?: SignalID, message?: LocalisedString }

Call As

player.remove_alert{ entity=entity }

Call Convention

• takes_table: true
• table_optional: false

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

Parameters

• entity?: LuaEntity
• prototype?: EntityID
• position?: MapPosition
• type?: defines.alert_type
• surface?: SurfaceIdentification
• icon?: SignalID
• message?: LocalisedString

get_alerts

LuaPlayer.get_alerts{ entity?: LuaEntity, prototype?: LuaEntityPrototype, position?: MapPosition, type?: defines.alert_type, surface?: SurfaceIdentification } -> Dict<uint32, Dict<defines.alert_type, Array<Alert>>>

Call As

player.get_alerts{ entity=entity }

Call Convention

• takes_table: true
• table_optional: false

Get all alerts matching the given filters, or all alerts if no filters are given.

Parameters

• entity?: LuaEntity
• prototype?: LuaEntityPrototype
• position?: MapPosition
• type?: defines.alert_type
• surface?: SurfaceIdentification

Returns

• Dict<uint32, Dict<defines.alert_type, Array<Alert>>> — A mapping of surface index to an array of arrays of alerts indexed by the alert type.

mute_alert

LuaPlayer.mute_alert(alert_type: defines.alert_type) -> boolean

Call As

player.mute_alert(alert_type)

Call Convention

• takes_table: false
• table_optional: false

Mutes alerts for the given alert category.

Parameters

• alert_type: defines.alert_type

Returns

• boolean — Whether the alert type was muted (false if it was already muted).

unmute_alert

LuaPlayer.unmute_alert(alert_type: defines.alert_type) -> boolean

Call As

player.unmute_alert(alert_type)

Call Convention

• takes_table: false
• table_optional: false

Unmutes alerts for the given alert category.

Parameters

• alert_type: defines.alert_type

Returns

• boolean — Whether the alert type was unmuted (false if it was wasn't muted).

is_alert_muted

LuaPlayer.is_alert_muted(alert_type: defines.alert_type) -> boolean

Call As

player.is_alert_muted(alert_type)

Call Convention

• takes_table: false
• table_optional: false

If the given alert type is currently muted.

Parameters

• alert_type: defines.alert_type

Returns

• boolean

enable_alert

LuaPlayer.enable_alert(alert_type: defines.alert_type) -> boolean

Call As

player.enable_alert(alert_type)

Call Convention

• takes_table: false
• table_optional: false

Enables alerts for the given alert category.

Parameters

• alert_type: defines.alert_type

Returns

• boolean — Whether the alert type was enabled (false if it was already enabled).

disable_alert

LuaPlayer.disable_alert(alert_type: defines.alert_type) -> boolean

Call As

player.disable_alert(alert_type)

Call Convention

• takes_table: false
• table_optional: false

Disables alerts for the given alert category.

Parameters

• alert_type: defines.alert_type

Returns

• boolean — Whether the alert type was disabled (false if it was already disabled).

is_alert_enabled

LuaPlayer.is_alert_enabled(alert_type: defines.alert_type) -> boolean

Call As

player.is_alert_enabled(alert_type)

Call Convention

• takes_table: false
• table_optional: false

If the given alert type is currently enabled.

Parameters

• alert_type: defines.alert_type

Returns

• boolean

add_pin

LuaPlayer.add_pin{ label?: string, preview_distance?: uint16, always_visible?: boolean, entity?: LuaEntity, player?: PlayerIdentification, surface?: SurfaceIdentification, position?: MapPosition }

Call As

player.add_pin{ label=label }

Call Convention

• takes_table: true
• table_optional: false

Adds a pin to this player for the given pin specification. Either entity, player, or surface and position must be defined.

Parameters

• label?: string
• preview_distance?: uint16 — Defaults to 16.
• always_visible?: boolean — Defaults to true.
• entity?: LuaEntity — The entity to pin.
• player?: PlayerIdentification — The player to pin.
• surface?: SurfaceIdentification — The surface to create the pin on.
• position?: MapPosition — Where to create the pin. Required when surface is defined.

pipette_entity

LuaPlayer.pipette_entity(entity: EntityWithQualityID, allow_ghost?: boolean) -> boolean

Call As

player.pipette_entity(entity, true)

Call Convention

• takes_table: false
• table_optional: false

Invokes the "smart pipette" action on the player as if the user pressed it. This method is deprecated in favor of LuaPlayer::pipette and should not be used.

Parameters

• entity: EntityWithQualityID
• allow_ghost?: boolean — Defaults to false.

Returns

• boolean — Whether the smart pipette found something to place.

pipette

LuaPlayer.pipette(id: PipetteID, quality?: QualityID, allow_ghost?: boolean) -> boolean

Call As

player.pipette(id, quality)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

• id: PipetteID
• quality?: QualityID
• allow_ghost?: boolean — Defaults to false.

Returns

• boolean — Whether the smart pipette found something to put into the cursor.

can_build_from_cursor

LuaPlayer.can_build_from_cursor{ position: MapPosition, direction?: defines.direction, flip_horizontal?: boolean, flip_vertical?: boolean, build_mode?: defines.build_mode, terrain_building_size?: uint32, skip_fog_of_war?: boolean } -> boolean

Call As

player.can_build_from_cursor{ position=position }

Call Convention

• takes_table: true
• table_optional: false

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

Parameters

• position: MapPosition — Where the entity would be placed
• direction?: defines.direction — Direction the entity would be placed
• flip_horizontal?: boolean — Whether to flip the blueprint horizontally. Defaults to false.
• flip_vertical?: boolean — Whether to flip the blueprint vertically. Defaults to false.
• build_mode?: defines.build_mode — Which build mode should be used instead of normal build. Defaults to defines.build_mode.normal.
• terrain_building_size?: uint32 — The size for building terrain if building terrain. Defaults to 2.
• skip_fog_of_war?: boolean — If chunks covered by fog-of-war are skipped. Defaults to false.

Returns

• boolean

build_from_cursor

LuaPlayer.build_from_cursor{ position: MapPosition, direction?: defines.direction, mirror?: boolean, flip_horizontal?: boolean, flip_vertical?: boolean, build_mode?: defines.build_mode, terrain_building_size?: uint32, skip_fog_of_war?: boolean }

Call As

player.build_from_cursor{ position=position }

Call Convention

• takes_table: true
• table_optional: false

Builds whatever is in the cursor on the surface the player is on. The cursor stack will automatically be reduced as if the player built normally.

Parameters

• position: MapPosition — Where the entity would be placed
• direction?: defines.direction — Direction the entity would be placed
• mirror?: boolean — Whether to mirror the entity
• flip_horizontal?: boolean — Whether to flip the blueprint horizontally. Defaults to false.
• flip_vertical?: boolean — Whether to flip the blueprint vertically. Defaults to false.
• build_mode?: defines.build_mode — Which build mode should be used instead of normal build. Defaults to defines.build_mode.normal.
• terrain_building_size?: uint32 — The size for building terrain if building terrain. Defaults to 2.
• skip_fog_of_war?: boolean — If chunks covered by fog-of-war are skipped. Defaults to false.

clear_inventory_highlights

LuaPlayer.clear_inventory_highlights()

Call As

player.clear_inventory_highlights()

Call Convention

• takes_table: false
• table_optional: false

Clears the blinking of the inventory based on insertion of items

use_from_cursor

LuaPlayer.use_from_cursor(position: MapPosition)

Call As

player.use_from_cursor(position)

Call Convention

• takes_table: false
• table_optional: false

Uses the current item in the cursor if it's a capsule or does nothing if not.

Parameters

• position: MapPosition — Where the item would be used.

play_sound

LuaPlayer.play_sound(sound_specification: PlaySoundSpecification)

Call As

player.play_sound(sound_specification)

Call Convention

• takes_table: false
• table_optional: false

Play a sound for this player.

The sound is not played if its location is not charted for this player.

Parameters

• sound_specification: PlaySoundSpecification — The sound to play.

get_associated_characters

LuaPlayer.get_associated_characters() -> Array<LuaEntity>

Call As

player.get_associated_characters()

Call Convention

• takes_table: false
• table_optional: false

The characters associated with this player.

The array will always be empty when the player is disconnected (see LuaPlayer::connected) regardless of there being associated characters.

Characters associated with this player will be logged off when this player disconnects but are not controlled by any player.

Returns

• Array<LuaEntity>

associate_character

LuaPlayer.associate_character(character: LuaEntity)

Call As

player.associate_character(character)

Call Convention

• takes_table: false
• table_optional: false

Associates a character with this player.

The character must not be connected to any controller.

If this player is currently disconnected (see LuaPlayer::connected) the character will be immediately "logged off".

See LuaPlayer::get_associated_characters for more information.

Parameters

• character: LuaEntity — The character entity.

disassociate_character

LuaPlayer.disassociate_character(character: LuaEntity)

Call As

player.disassociate_character(character)

Call Convention

• takes_table: false
• table_optional: false

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

See LuaPlayer::get_associated_characters for more information.

Parameters

• character: LuaEntity — The character entity

swap_characters

LuaPlayer.swap_characters(player: PlayerIdentification) -> boolean

Call As

player.swap_characters(player)

Call Convention

• takes_table: false
• table_optional: false

Swaps this player's character with another player's character.

Parameters

• player: PlayerIdentification — The player to swap characters with.

Returns

• boolean — true if the swap was successful.

create_local_flying_text

LuaPlayer.create_local_flying_text{ text: LocalisedString, position?: MapPosition, surface?: SurfaceIdentification, create_at_cursor?: boolean, color?: Color, time_to_live?: uint32, speed?: double }

Call As

player.create_local_flying_text{ text=text }

Call Convention

• takes_table: true
• table_optional: false

Spawn flying text that is only visible to this player. Either position or create_at_cursor are required. When create_at_cursor is true, all parameters other than text are ignored.

If no custom speed is set and the text is longer than 25 characters, its time_to_live and speed are dynamically adjusted to give the player more time to read it.

Local flying text is not saved, which means it will disappear after a save/load-cycle.

Parameters

• text: LocalisedString — The flying text to show.
• position?: MapPosition — The location on the map at which to show the flying text.
• surface?: SurfaceIdentification — The surface which this text will be shown on. Defaults to player surface.
• create_at_cursor?: boolean — If true, the flying text is created at the player's cursor. Defaults to false.
• color?: Color — The color of the flying text. Defaults to white text.
• time_to_live?: uint32 — The amount of ticks that the flying text will be shown for. Defaults to 80.
• speed?: double — The speed at which the text rises upwards in tiles/second. Can't be a negative value.

clear_local_flying_texts

LuaPlayer.clear_local_flying_texts()

Call As

player.clear_local_flying_texts()

Call Convention

• takes_table: false
• table_optional: false

Clear any active flying texts for this player.

get_quick_bar_slot

LuaPlayer.get_quick_bar_slot(index: uint32) -> ItemFilter?

Call As

player.get_quick_bar_slot(index)

Call Convention

• takes_table: false
• table_optional: false

Gets the quick bar filter for the given slot or nil.

Parameters

• index: uint32 — The slot index. 1 for the first slot of page one, 2 for slot two of page one, 11 for the first slot of page 2, etc.

Returns

• ItemFilter?

set_quick_bar_slot

LuaPlayer.set_quick_bar_slot(index: uint32, filter: LuaItemStack | ItemWithQualityID | nil)

Call As

player.set_quick_bar_slot(index, filter)

Call Convention

• takes_table: false
• table_optional: false

Sets the quick bar filter for the given slot. If a LuaItemStack is provided, the slot will be set to that particular item instance if it has extra data, for example a specific blueprint or spidertron remote. Otherwise, it will be set to all items of that prototype, for example iron plates.

Parameters

• index: uint32 — The slot index. 1 for the first slot of page one, 2 for slot two of page one, 11 for the first slot of page 2, etc.
• filter: LuaItemStack | ItemWithQualityID | nil — The filter or nil to clear it.

get_active_quick_bar_page

LuaPlayer.get_active_quick_bar_page(index: uint32) -> uint8?

Call As

player.get_active_quick_bar_page(index)

Call Convention

• takes_table: false
• table_optional: false

Gets which quick bar page is being used for the given screen page or nil if not known.

Parameters

• index: uint32 — The screen page. Index 1 is the top row in the gui. Index can go beyond the visible number of bars on the screen to account for the interface config setting change.

Returns

• uint8?

set_active_quick_bar_page

LuaPlayer.set_active_quick_bar_page(screen_index: uint32, page_index: uint32)

Call As

player.set_active_quick_bar_page(screen_index, page_index)

Call Convention

• takes_table: false
• table_optional: false

Sets which quick bar page is being used for the given screen page.

Parameters

• screen_index: uint32 — The screen page. Index 1 is the top row in the gui. Index can go beyond the visible number of bars on the screen to account for the interface config setting change.
• page_index: uint32 — The new quick bar page.

jump_to_cutscene_waypoint

LuaPlayer.jump_to_cutscene_waypoint(waypoint_index: uint32)

Call As

player.jump_to_cutscene_waypoint(waypoint_index)

Call Convention

• takes_table: false
• table_optional: false

Jump to the specified cutscene waypoint. Only works when the player is viewing a cutscene.

Parameters

• waypoint_index: uint32

exit_cutscene

LuaPlayer.exit_cutscene()

Call As

player.exit_cutscene()

Call Convention

• takes_table: false
• table_optional: false

Exit the current cutscene. Errors if not in a cutscene.

exit_remote_view

LuaPlayer.exit_remote_view()

Call As

player.exit_remote_view()

Call Convention

• takes_table: false
• table_optional: false

Exit remote view if possible. Exiting will fail if the player is in a rocket or in a platform.

is_shortcut_toggled

LuaPlayer.is_shortcut_toggled(prototype_name: string) -> boolean

Call As

player.is_shortcut_toggled(prototype_name)

Call Convention

• takes_table: false
• table_optional: false

Is a custom Lua shortcut currently toggled?

Parameters

• prototype_name: string — Prototype name of the custom shortcut.

Returns

• boolean

is_shortcut_available

LuaPlayer.is_shortcut_available(prototype_name: string) -> boolean

Call As

player.is_shortcut_available(prototype_name)

Call Convention

• takes_table: false
• table_optional: false

Is a custom Lua shortcut currently available?

Parameters

• prototype_name: string — Prototype name of the custom shortcut.

Returns

• boolean

set_shortcut_toggled

LuaPlayer.set_shortcut_toggled(prototype_name: string, toggled: boolean)

Call As

player.set_shortcut_toggled(prototype_name, true)

Call Convention

• takes_table: false
• table_optional: false

Toggle or untoggle a custom Lua shortcut

Parameters

• prototype_name: string — Prototype name of the custom shortcut.
• toggled: boolean

set_shortcut_available

LuaPlayer.set_shortcut_available(prototype_name: string, available: boolean)

Call As

player.set_shortcut_available(prototype_name, true)

Call Convention

• takes_table: false
• table_optional: false

Make a custom Lua shortcut available or unavailable.

Parameters

• prototype_name: string — Prototype name of the custom shortcut.
• available: boolean

connect_to_server

LuaPlayer.connect_to_server{ address: string, name?: LocalisedString, description?: LocalisedString, password?: string }

Call As

player.connect_to_server{ address=address }

Call Convention

• takes_table: true
• table_optional: false

Asks the player if they would like to connect to the given server.

This only does anything when used on a multiplayer peer. Single player and server hosts will ignore the prompt.

Parameters

• address: string — The server (address:port) if port is not given the default Factorio port is used.
• name?: LocalisedString — The name of the server.
• description?: LocalisedString
• password?: string — The password if different from the one used to join this game. Note, if the current password is not empty but the one required to join the new server is an empty string should be given for this field.

toggle_map_editor

LuaPlayer.toggle_map_editor()

Call As

player.toggle_map_editor()

Call Convention

• takes_table: false
• table_optional: false

Toggles this player into or out of the map editor. Does nothing if this player isn't an admin or if the player doesn't have permission to use the map editor.

request_translation

LuaPlayer.request_translation(localised_string: LocalisedString) -> uint32?

Call As

player.request_translation(localised_string)

Call Convention

• takes_table: false
• table_optional: false

Requests a translation for the given localised string. If the request is successful, the on_string_translated event will be fired with the results.

Does nothing if this player is not connected (see LuaPlayer::connected).

Parameters

• localised_string: LocalisedString

Returns

• uint32? — The unique ID for the requested translation.

request_translations

LuaPlayer.request_translations(localised_strings: Array<LocalisedString>) -> Array<uint32>?

Call As

player.request_translations(localised_strings)

Call Convention

• takes_table: false
• table_optional: false

Requests translation for the given set of localised strings. If the request is successful, a on_string_translated event will be fired for each string with the results.

Does nothing if this player is not connected (see LuaPlayer::connected).

Parameters

• localised_strings: Array<LocalisedString>

Returns

• Array<uint32>? — The unique IDs for the requested translations.

get_infinity_inventory_filter

LuaPlayer.get_infinity_inventory_filter(index: uint32) -> InfinityInventoryFilter?

Call As

player.get_infinity_inventory_filter(index)

Call Convention

• takes_table: false
• table_optional: false

Gets the filter for this map editor infinity filters at the given index or nil if the filter index doesn't exist or is empty.

Parameters

• index: uint32 — The index to get.

Returns

• InfinityInventoryFilter?

set_infinity_inventory_filter

LuaPlayer.set_infinity_inventory_filter(index: uint32, filter: InfinityInventoryFilter | nil)

Call As

player.set_infinity_inventory_filter(index, filter)

Call Convention

• takes_table: false
• table_optional: false

Sets the filter for this map editor infinity filters at the given index.

Parameters

• index: uint32 — The index to set.
• filter: InfinityInventoryFilter | nil — The new filter or nil to clear the filter.

clear_recipe_notifications

LuaPlayer.clear_recipe_notifications()

Call As

player.clear_recipe_notifications()

Call Convention

• takes_table: false
• table_optional: false

Clears all recipe notifications for this player.

add_recipe_notification

LuaPlayer.add_recipe_notification(recipe: RecipeID)

Call As

player.add_recipe_notification(recipe)

Call Convention

• takes_table: false
• table_optional: false

Adds the given recipe to the list of recipe notifications for this player.

Parameters

• recipe: RecipeID — Recipe to add.

clear_recipe_notification

LuaPlayer.clear_recipe_notification(recipe: RecipeID)

Call As

player.clear_recipe_notification(recipe)

Call Convention

• takes_table: false
• table_optional: false

Clears the given recipe from the list of recipe notifications for this player.

Parameters

• recipe: RecipeID — Recipe to clear.

get_recipe_notifications

LuaPlayer.get_recipe_notifications() -> Array<LuaRecipePrototype>

Call As

player.get_recipe_notifications()

Call Convention

• takes_table: false
• table_optional: false

Get all recipes that currently have recipe notifications for this player.

Returns

• Array<LuaRecipePrototype>

add_to_clipboard

LuaPlayer.add_to_clipboard(blueprint: LuaItemStack)

Call As

player.add_to_clipboard(blueprint)

Call Convention

• takes_table: false
• table_optional: false

Adds the given blueprint to this player's clipboard queue.

Parameters

• blueprint: LuaItemStack — The blueprint to add.

activate_paste

LuaPlayer.activate_paste()

Call As

player.activate_paste()

Call Convention

• takes_table: false
• table_optional: false

Gets a copy of the currently selected blueprint in the clipboard queue into the player's cursor, as if the player activated Paste.

start_selection

LuaPlayer.start_selection(position: MapPosition, selection_mode: defines.selection_mode)

Call As

player.start_selection(position, selection_mode)

Call Convention

• takes_table: false
• table_optional: false

Starts selection with selection tool from the specified position. Does nothing if the player's cursor is not a selection tool.

Parameters

• position: MapPosition — The position to start selection from.
• selection_mode: defines.selection_mode — The type of selection to start.

clear_selection

LuaPlayer.clear_selection()

Call As

player.clear_selection()

Call Convention

• takes_table: false
• table_optional: false

Clears the player's selection tool selection position.

enter_space_platform

LuaPlayer.enter_space_platform(space_platform: LuaSpacePlatform) -> boolean

Call As

player.enter_space_platform(space_platform)

Call Convention

• takes_table: false
• table_optional: false

Enters the given space platform if possible.

Parameters

• space_platform: LuaSpacePlatform

Returns

• boolean — If the player entered the platform.

leave_space_platform

LuaPlayer.leave_space_platform()

Call As

player.leave_space_platform()

Call Convention

• takes_table: false
• table_optional: false

Ejects this player from the current space platform if in a platform. The player is left on the platform at the position of the hub.

land_on_planet

LuaPlayer.land_on_planet() -> boolean

Call As

player.land_on_planet()

Call Convention

• takes_table: false
• table_optional: false

Ejects this player from the current space platform and lands on the current planet.

Returns

• boolean — If the player successfully landed on the planet.

set_zoom_limits

LuaPlayer.set_zoom_limits(controller_type: defines.controllers, zoom_limits: ZoomLimits)

Call As

player.set_zoom_limits(controller_type, zoom_limits)

Call Convention

• takes_table: false
• table_optional: false

Sets the zoom limits for a specific controller type. To reset a controller's zoom limits to default, pass an empty table for zoom_limits.

Parameters

• controller_type: defines.controllers — The type of the controller to set the zoom limits for.
• zoom_limits: ZoomLimits — The new zoom limits. See LuaPlayer::zoom_limits for usage information.