Factorio.com|Forums|Wiki|Mod Portal|API Docs

# Factorio Runtime Docs Version 2.0.77

# LuaPlayer - Runtime Docs

## Class LuaPlayer extends LuaControl

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.

Inherits from LuaControl

## Members

set_ending_screen_data(message, file?) |  | Setup the screen to be shown when the game is finished.
Setup the screen to be shown when the game is finished.
print(message, print_settings?) |  | Print text to the chat console. [...]
Print text to the chat console. [...]
clear_console() |  | Clear the chat console.
Clear the chat console.
get_goal_description() | → LocalisedString | Get the current goal description, as a localised string.
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 the text in the goal window (top left).
set_controller{type=…, character?=…, waypoints?=…, start_position?=…, start_zoom?=…, final_transition_time?=…, chart_mode_cutoff?=…, position?=…, surface?=…} |  | Set the controller type of the player. [...]
Set the controller type of the player. [...]
drag_wire{position=…} | → boolean | Start/end wire dragging at the specified location, wire type is based on the cursor contents
Start/end wire dragging at the specified location, wire type is based on the cursor contents
disable_recipe_groups() |  | Disable recipe groups.
Disable recipe groups.
enable_recipe_groups() |  | Enable recipe groups.
Enable recipe groups.
disable_recipe_subgroups() |  | Disable recipe subgroups.
Disable recipe subgroups.
enable_recipe_subgroups() |  | Enable recipe subgroups.
Enable recipe subgroups.
print_entity_statistics(entities?) |  | Print entity statistics to the player's console.
Print entity statistics to the player's console.
print_robot_jobs() |  | Print construction robot job counts to the player's console.
Print construction robot job counts to the player's console.
print_lua_object_statistics() |  | Print LuaObject counts per mod.
Print LuaObject counts per mod.
unlock_achievement(name) |  | Unlock the achievements of the given player. [...]
Unlock the achievements of the given player. [...]
clear_cursor() | → boolean | Invokes the "clear cursor" action on the player as if the user pressed it.
Invokes the "clear cursor" action on the player as if the user pressed it.
create_character(character?) | → boolean | Creates and attaches a character entity to this player. [...]
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.
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.
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.
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[uint32 → dictionary[defines.alert_type → array[Alert]]] | Get all alerts matching the given filters, or all alerts if no filters are given.
Get all alerts matching the given filters, or all alerts if no filters are given.
mute_alert(alert_type) | → boolean | Mutes alerts for the given alert category.
Mutes alerts for the given alert category.
unmute_alert(alert_type) | → boolean | Unmutes alerts for the given alert category.
Unmutes alerts for the given alert category.
is_alert_muted(alert_type) | → boolean | If the given alert type is currently muted.
If the given alert type is currently muted.
enable_alert(alert_type) | → boolean | Enables alerts for the given alert category.
Enables alerts for the given alert category.
disable_alert(alert_type) | → boolean | Disables alerts for the given alert category.
Disables alerts for the given alert category.
is_alert_enabled(alert_type) | → boolean | If the given alert type is currently enabled.
If the given alert type is currently enabled.
add_pin{label?=…, preview_distance?=…, always_visible?=…, entity?=…, player?=…, surface?=…, position?=…} |  | Adds a pin to this player for the given pin specification. [...]
Adds a pin to this player for the given pin specification. [...]
pipette_entity(entity, allow_ghost?) | → boolean | Invokes the "smart pipette" action on the player as if the user pressed it. [...]
Invokes the "smart pipette" action on the player as if the user pressed it. [...]
pipette(id, quality?, allow_ghost?) | → boolean | Invokes the "smart pipette" action on the player as if the user pressed it.
Invokes the "smart pipette" action on the player as if the user pressed it.
can_build_from_cursor{position=…, direction?=…, flip_horizontal?=…, flip_vertical?=…, build_mode?=…, 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.
Checks if this player can build what ever is in the cursor on the surface the player is on.
build_from_cursor{position=…, direction?=…, mirror?=…, flip_horizontal?=…, flip_vertical?=…, build_mode?=…, terrain_building_size?=…, skip_fog_of_war?=…} |  | Builds whatever is in the cursor on the surface the player is on. [...]
Builds whatever is in the cursor on the surface the player is on. [...]
clear_inventory_highlights() |  | Clears the blinking of the inventory based on insertion of items
Clears the blinking of the inventory based on insertion of items
use_from_cursor(position) |  | Uses the current item in the cursor if it's a capsule or does nothing if not.
Uses the current item in the cursor if it's a capsule or does nothing if not.
play_sound(sound_specification) |  | Play a sound for this player. [...]
Play a sound for this player. [...]
get_associated_characters() | → array[LuaEntity] | The characters associated with this player. [...]
The characters associated with this player. [...]
associate_character(character) |  | Associates a character with this player. [...]
Associates a character with this player. [...]
disassociate_character(character) |  | Disassociates a character from this player. [...]
Disassociates a character from this player. [...]
swap_characters(player) | → boolean | Swaps this player's character with another player's character.
Swaps this player's character with another player's character.
create_local_flying_text{text=…, position?=…, surface?=…, create_at_cursor?=…, color?=…, time_to_live?=…, speed?=…} |  | Spawn flying text that is only visible to this player. [...]
Spawn flying text that is only visible to this player. [...]
clear_local_flying_texts() |  | Clear any active flying texts for this player.
Clear any active flying texts for this player.
get_quick_bar_slot(index) | → ItemFilter? | Gets the quick bar filter for the given slot or `nil`.
Gets the quick bar filter for the given slot or `nil`.
set_quick_bar_slot(index, filter) |  | Sets the quick bar filter for the given slot. [...]
Sets the quick bar filter for the given slot. [...]
get_active_quick_bar_page(index) | → uint8? | Gets which quick bar page is being used for the given screen page or `nil` if not known.
Gets which quick bar page is being used for the given screen page or `nil` if not known.
set_active_quick_bar_page(screen_index, page_index) |  | Sets which quick bar page is being used for the given screen page.
Sets which quick bar page is being used for the given screen page.
jump_to_cutscene_waypoint(waypoint_index) |  | Jump to the specified cutscene waypoint. [...]
Jump to the specified cutscene waypoint. [...]
exit_cutscene() |  | Exit the current cutscene. [...]
Exit the current cutscene. [...]
exit_remote_view() |  | Exit remote view if possible. [...]
Exit remote view if possible. [...]
is_shortcut_toggled(prototype_name) | → boolean | Is a custom Lua shortcut currently toggled?
Is a custom Lua shortcut currently toggled?
is_shortcut_available(prototype_name) | → boolean | Is a custom Lua shortcut currently available?
Is a custom Lua shortcut currently available?
set_shortcut_toggled(prototype_name, toggled) |  | Toggle or untoggle a custom Lua shortcut
Toggle or untoggle a custom Lua shortcut
set_shortcut_available(prototype_name, available) |  | Make a custom Lua shortcut available or unavailable.
Make a custom Lua shortcut available or unavailable.
connect_to_server{address=…, name?=…, description?=…, password?=…} |  | Asks the player if they would like to connect to the given server. [...]
Asks the player if they would like to connect to the given server. [...]
toggle_map_editor() |  | Toggles this player into or out of the map editor. [...]
Toggles this player into or out of the map editor. [...]
request_translation(localised_string) | → uint32? | Requests a translation for the given localised string. [...]
Requests a translation for the given localised string. [...]
request_translations(localised_strings) | → array[uint32]? | Requests translation for the given set of localised strings. [...]
Requests translation for the given set of localised strings. [...]
get_infinity_inventory_filter(index) | → InfinityInventoryFilter? | 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.
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.
set_infinity_inventory_filter(index, filter) |  | Sets the filter for this map editor infinity filters at the given index.
Sets the filter for this map editor infinity filters at the given index.
clear_recipe_notifications() |  | Clears all recipe notifications for this player.
Clears all recipe notifications for this player.
add_recipe_notification(recipe) |  | Adds the given recipe to the list of recipe notifications for this player.
Adds the given recipe to the list of recipe notifications for this player.
clear_recipe_notification(recipe) |  | Clears the given recipe from the list of recipe notifications for this player.
Clears the given recipe from the list of recipe notifications for this player.
get_recipe_notifications() | → array[LuaRecipePrototype] | Get all recipes that currently have recipe notifications for this player.
Get all recipes that currently have recipe notifications for this player.
add_to_clipboard(blueprint) |  | Adds the given blueprint to this player's clipboard queue.
Adds the given blueprint to this player's clipboard queue.
activate_paste() |  | Gets a copy of the currently selected blueprint in the clipboard queue into the player's cursor, as if the player activated Paste.
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(position, selection_mode) |  | Starts selection with selection tool from the specified position. [...]
Starts selection with selection tool from the specified position. [...]
clear_selection() |  | Clears the player's selection tool selection position.
Clears the player's selection tool selection position.
enter_space_platform(space_platform) | → boolean | Enters the given space platform if possible.
Enters the given space platform if possible.
leave_space_platform() |  | Ejects this player from the current space platform if in a platform. [...]
Ejects this player from the current space platform if in a platform. [...]
land_on_planet() | → boolean | Ejects this player from the current space platform and lands on the current planet.
Ejects this player from the current space platform and lands on the current planet.
set_zoom_limits(controller_type, zoom_limits) |  | Sets the zoom limits for a specific controller type. [...]
Sets the zoom limits for a specific controller type. [...]
physical_surface | :: R LuaSurface | The surface this player's physical controller is on.
The surface this player's physical controller is on.
physical_surface_index | :: R uint32 | Unique ID associated with the surface this player's physical controller is currently on.
Unique ID associated with the surface this player's physical controller is currently on.
physical_position | :: R MapPosition | The current position of this player's physical controller.
The current position of this player's physical controller.
physical_vehicle | :: R LuaEntity? | The current vehicle of this player's physical controller.
The current vehicle of this player's physical controller.
character | :: RW LuaEntity? | The character attached to this player, if any. [...]
The character attached to this player, if any. [...]
cutscene_character | :: R LuaEntity? | When in a cutscene; the character this player would be using once the cutscene is over, if any. [...]
When in a cutscene; the character this player would be using once the cutscene is over, if any. [...]
index | :: R uint32 | This player's index in LuaGameScript::players (unique ID). [...]
This player's index in LuaGameScript::players (unique ID). [...]
gui | :: R LuaGui |
opened_self | :: R boolean | `true` if the player opened itself. [...]
`true` if the player opened itself. [...]
controller_type | :: R defines.controllers |
physical_controller_type | :: R defines.controllers | The player's "physical" controller. [...]
The player's "physical" controller. [...]
stashed_controller_type | :: R defines.controllers? | The stashed controller type, if any. [...]
The stashed controller type, if any. [...]
spidertron_remote_selection | :: RW array[LuaEntity]? | All SpiderVehicles currently selected by the player, if they are holding a spidertron remote.
All SpiderVehicles currently selected by the player, if they are holding a spidertron remote.
zoom | :: RW double | The current player controller's zoom level. [...]
The current player controller's zoom level. [...]
zoom_limits | :: RW ZoomLimits | The player's current controller's zoom limits. [...]
The player's current controller's zoom limits. [...]
centered_on | :: RW LuaEntity? | The entity being centered on in remote view. [...]
The entity being centered on in remote view. [...]
game_view_settings | :: RW GameViewSettings | The player's game view settings.
The player's game view settings.
minimap_enabled | :: RW boolean | `true` if the minimap is visible.
`true` if the minimap is visible.
color | :: RW Color | The color associated with the player. [...]
The color associated with the player. [...]
chat_color | :: RW Color | The color used when this player talks in game.
The color used when this player talks in game.
name | :: R string | The player's username.
The player's username.
tag | :: RW string | The tag that is shown after the player in chat, on the map and above multiplayer selection rectangles.
The tag that is shown after the player in chat, on the map and above multiplayer selection rectangles.
connected | :: R boolean | `true` if the player is currently connected to the game.
`true` if the player is currently connected to the game.
admin | :: RW boolean | `true` if the player is an admin. [...]
`true` if the player is an admin. [...]
entity_copy_source | :: R LuaEntity? | The source entity used during entity settings copy-paste, if any.
The source entity used during entity settings copy-paste, if any.
afk_time | :: R uint32 | How many ticks since the last action of this player.
How many ticks since the last action of this player.
online_time | :: R uint32 | How many ticks did this player spend playing this save (all sessions combined).
How many ticks did this player spend playing this save (all sessions combined).
last_online | :: R uint32 | At what tick this player was last online.
At what tick this player was last online.
permission_group | :: RW LuaPermissionGroup? | The permission group this player is part of, if any.
The permission group this player is part of, if any.
mod_settings | :: R LuaCustomTable[string → ModSetting] | The current per-player settings for the this player, indexed by prototype name. [...]
The current per-player settings for the this player, indexed by prototype name. [...]
ticks_to_respawn | :: RW uint32? | The number of ticks until this player will respawn. [...]
The number of ticks until this player will respawn. [...]
display_resolution | :: R DisplayResolution | The display resolution for this player. [...]
The display resolution for this player. [...]
display_scale | :: R double | The display scale for this player. [...]
The display scale for this player. [...]
display_density_scale | :: R double | The display density scale for this player. [...]
The display density scale for this player. [...]
locale | :: R string | The active locale for this player. [...]
The active locale for this player. [...]
blueprint_to_setup | :: R LuaItemStack | The item stack containing a blueprint to be setup.
The item stack containing a blueprint to be setup.
blueprints | :: R array[LuaRecord] | Records contained in the player's blueprint library.
Records contained in the player's blueprint library.
render_mode | :: R defines.render_mode | The render mode of the player, like map or zoom to world.
The render mode of the player, like map or zoom to world.
input_method | :: R defines.input_method | The input method of the player, mouse and keyboard or game controller
The input method of the player, mouse and keyboard or game controller
spectator | :: RW boolean | 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.
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 | :: RW boolean | If `true`, circle and name of given player is rendered on the map/chart.
If `true`, circle and name of given player is rendered on the map/chart.
remove_unfiltered_items | :: RW boolean | If items not included in this map editor infinity inventory filters should be removed.
If items not included in this map editor infinity inventory filters should be removed.
infinity_inventory_filters | :: RW array[InfinityInventoryFilter] | The filters for this map editor infinity inventory settings.
The filters for this map editor infinity inventory settings.
auto_sort_main_inventory | :: R boolean | If the main inventory will be auto sorted.
If the main inventory will be auto sorted.
hand_location | :: RW ItemStackLocation? | The original location of the item in the cursor, marked with a hand. [...]
The original location of the item in the cursor, marked with a hand. [...]
cursor_stack_temporary | :: RW boolean | Returns true if the current item stack in cursor will be destroyed after clearing the cursor. [...]
Returns true if the current item stack in cursor will be destroyed after clearing the cursor. [...]
undo_redo_stack | :: R LuaUndoRedoStack | The undo and redo stack for this player.
The undo and redo stack for this player.
drag_target | :: R DragTarget? | The wire drag target for this player, if any.
The wire drag target for this player, if any.
map_view_settings | :: W MapViewSettings | The player's map view settings. [...]
The player's map view settings. [...]
valid | :: R boolean | Is this object valid? [...]
Is this object valid? [...]
object_name | :: R string | The class name of this object. [...]
The class name of this object. [...]

Inherited from LuaControl

get_inventory(inventory) | → LuaInventory? | Get an inventory belonging to this entity. [...]
Get an inventory belonging to this entity. [...]
get_inventory_name(inventory) | → string? | Get name of inventory. [...]
Get name of inventory. [...]
get_max_inventory_index() | → defines.inventory | The highest index of all inventories this entity can use. [...]
The highest index of all inventories this entity can use. [...]
get_main_inventory() | → LuaInventory? | Gets the main inventory for this character or player if this is a character or player.
Gets the main inventory for this character or player if this is a character or player.
can_insert(items) | → boolean | Can at least some items be inserted?
Can at least some items be inserted?
insert(items) | → uint32 | Insert items into this entity. [...]
Insert items into this entity. [...]
set_gui_arrow{margin=…, type=…} |  | Create an arrow which points at this entity. [...]
Create an arrow which points at this entity. [...]
clear_gui_arrow() |  | Removes the arrow created by `set_gui_arrow`.
Removes the arrow created by `set_gui_arrow`.
get_item_count(item?) | → uint32 | Get the number of all or some items in this entity.
Get the number of all or some items in this entity.
has_items_inside() | → boolean | Does this entity have any item inside it?
Does this entity have any item inside it?
can_reach_entity(entity) | → boolean | Can a given entity be opened or accessed?
Can a given entity be opened or accessed?
clear_items_inside() |  | Remove all items from this entity.
Remove all items from this entity.
remove_item(items) | → uint32 | Remove items from this entity.
Remove items from this entity.
teleport(position, surface?, raise_teleported?, snap_to_grid?, build_check_type?) | → boolean | Teleport the entity to a given position, possibly on another surface. [...]
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.
Select an entity, as if by hovering the mouse above it.
clear_selected_entity() |  | Unselect any selected entity.
Unselect any selected entity.
disable_flashlight() |  | Disable the flashlight. [...]
Disable the flashlight. [...]
enable_flashlight() |  | Enable the flashlight. [...]
Enable the flashlight. [...]
is_flashlight_enabled() | → boolean | Is the flashlight enabled for the current controller. [...]
Is the flashlight enabled for the current controller. [...]
get_craftable_count(recipe) | → uint32 | Gets the count of the given recipe that can be crafted.
Gets the count of the given recipe that can be crafted.
begin_crafting{count=…, recipe=…, silent?=…} | → uint32 | Begins crafting the given count of the given recipe.
Begins crafting the given count of the given recipe.
cancel_crafting{index=…, count=…} |  | Cancels the given amount of crafts at the given crafting queue position. [...]
Cancels the given amount of crafts at the given crafting queue position. [...]
mine_entity(entity, force?) | → boolean | Mines the given entity as if this player (or character) mined it.
Mines the given entity as if this player (or character) mined it.
mine_tile(tile) | → boolean | Mines the given tile as if this player (or character) mined it.
Mines the given tile as if this player (or character) mined it.
is_player() | → boolean | When `true` control adapter is a LuaPlayer object, `false` for entities including characters with players.
When `true` control adapter is a LuaPlayer object, `false` for entities including characters with players.
open_technology_gui(technology?) |  | Open the technology GUI and select a given technology.
Open the technology GUI and select a given technology.
open_factoriopedia_gui(prototype?) |  | Open the Factoriopedia GUI and select a given entry, if any valid ID is given.
Open the Factoriopedia GUI and select a given entry, if any valid ID is given.
close_factoriopedia_gui() |  | Closes the Factoriopedia GUI if it's open.
Closes the Factoriopedia GUI if it's open.
is_cursor_blueprint() | → boolean | Returns whether the player is holding a blueprint. [...]
Returns whether the player is holding a blueprint. [...]
is_cursor_empty() | → boolean | Returns whether the player is holding something in the cursor. [...]
Returns whether the player is holding something in the cursor. [...]
get_requester_point() | → LuaLogisticPoint? | Gets the requester logistic point for this entity if it has one.
Gets the requester logistic point for this entity if it has one.
set_driving(driving, force?) |  | Sets if this character or player is driving. [...]
Sets if this character or player is driving. [...]
can_place_entity{name=…, position=…, direction?=…} | → boolean | Checks if this character or player can build the given entity at the given location on the surface the character or player is on.
Checks if this character or player can build the given entity at the given location on the surface the character or player is on.
surface | :: R LuaSurface | The surface this entity is currently on.
The surface this entity is currently on.
surface_index | :: R uint32 | Unique index (ID) associated with the surface this entity is currently on.
Unique index (ID) associated with the surface this entity is currently on.
position | :: R MapPosition | The current position of the entity.
The current position of the entity.
render_position | :: R MapPosition | The current render position of the entity.
The current render position of the entity.
is_flying | :: R boolean | If this player or character entity is flying. [...]
If this player or character entity is flying. [...]
flight_height | :: R double | The current flight height for this player or character entity. [...]
The current flight height for this player or character entity. [...]
vehicle | :: R LuaEntity? | The vehicle the player is currently sitting in.
The vehicle the player is currently sitting in.
cargo_pod | :: R LuaEntity? | The cargo pod the player is currently sitting in or the cargo pod attached to this rocket silo.
The cargo pod the player is currently sitting in or the cargo pod attached to this rocket silo.
hub | :: R LuaEntity? | The space platform hub the player is currently sitting in.
The space platform hub the player is currently sitting in.
force | :: R LuaForce| W ForceID | The force of this entity. [...]
The force of this entity. [...]
force_index | :: R uint32 | Unique index (ID) associated with the force of this entity.
Unique index (ID) associated with the force of this entity.
selected | :: RW LuaEntity? | The currently selected entity. [...]
The currently selected entity. [...]
opened | :: RW LuaEntity or LuaItemStack or LuaEquipment or LuaEquipmentGrid or LuaPlayer or LuaGuiElement or LuaInventory or LuaLogisticNetwork or LuaItemStack or defines.gui_type? | The GUI the player currently has open. [...]
The GUI the player currently has open. [...]
crafting_queue_size | :: R uint32 | Size of the crafting queue.
Size of the crafting queue.
crafting_queue_progress | :: RW double | The crafting queue progress in the range `[0-1]`. [...]
The crafting queue progress in the range `[0-1]`. [...]
walking_state | :: RW table | Current walking state of the player, or the spider-vehicle the character is driving.
Current walking state of the player, or the spider-vehicle the character is driving.
riding_state | :: RW RidingState | Current riding state of this car, or of the car this player is riding in.
Current riding state of this car, or of the car this player is riding in.
mining_state | :: RW table | Current mining state. [...]
Current mining state. [...]
shooting_state | :: RW table | Current shooting state.
Current shooting state.
picking_state | :: RW boolean | Current item-picking state.
Current item-picking state.
repair_state | :: RW table | Current repair state.
Current repair state.
cursor_stack | :: R LuaItemStack? | The player's cursor stack. [...]
The player's cursor stack. [...]
cursor_ghost | :: R ItemIDAndQualityIDPair| W ItemWithQualityID? | The ghost prototype in the player's cursor. [...]
The ghost prototype in the player's cursor. [...]
cursor_record | :: R LuaRecord? | The blueprint record in the player's cursor.
The blueprint record in the player's cursor.
driving | :: RW boolean | `true` if the player is in a vehicle. [...]
`true` if the player is in a vehicle. [...]
crafting_queue | :: R array[CraftingQueueItem]? | The current crafting queue items.
The current crafting queue items.
following_robots | :: R array[LuaEntity] | The current combat robots following the character. [...]
The current combat robots following the character. [...]
cheat_mode | :: RW boolean | When `true` hand crafting is free and instant.
When `true` hand crafting is free and instant.
character_crafting_speed_modifier | :: RW double | When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
character_mining_speed_modifier | :: RW double | When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
character_additional_mining_categories | :: RW array[string] | When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
character_running_speed_modifier | :: RW double | Modifies the running speed of this character by the given value as a percentage. [...]
Modifies the running speed of this character by the given value as a percentage. [...]
character_build_distance_bonus | :: RW uint32 | When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
character_item_drop_distance_bonus | :: RW uint32 | When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
character_reach_distance_bonus | :: RW uint32 | When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
character_resource_reach_distance_bonus | :: RW uint32 | When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
character_item_pickup_distance_bonus | :: RW uint32 | When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
character_loot_pickup_distance_bonus | :: RW uint32 | When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
character_inventory_slots_bonus | :: RW uint32 | When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
character_trash_slot_count_bonus | :: RW uint32 | When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
character_maximum_following_robot_count_bonus | :: RW uint32 | When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
character_health_bonus | :: RW float | When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
When called on a LuaPlayer, it must be associated with a character (see LuaPlayer::character).
opened_gui_type | :: R defines.gui_type? |
build_distance | :: R uint32 | The build distance of this character or max uint when not a character or player connected to a character.
The build distance of this character or max uint when not a character or player connected to a character.
drop_item_distance | :: R uint32 | The item drop distance of this character or max uint when not a character or player connected to a character.
The item drop distance of this character or max uint when not a character or player connected to a character.
reach_distance | :: R uint32 | The reach distance of this character or max uint when not a character or player connected to a character.
The reach distance of this character or max uint when not a character or player connected to a character.
item_pickup_distance | :: R double | The item pickup distance of this character or max double when not a character or player connected to a character.
The item pickup distance of this character or max double when not a character or player connected to a character.
loot_pickup_distance | :: R double | The loot pickup distance of this character or max double when not a character or player connected to a character.
The loot pickup distance of this character or max double when not a character or player connected to a character.
resource_reach_distance | :: R double | The resource reach distance of this character or max double when not a character or player connected to a character.
The resource reach distance of this character or max double when not a character or player connected to a character.
in_combat | :: R boolean | Whether this character entity is in combat.
Whether this character entity is in combat.
character_running_speed | :: R double | The current movement speed of this character, including effects from exoskeletons, tiles, stickers and shooting.
The current movement speed of this character, including effects from exoskeletons, tiles, stickers and shooting.
character_mining_progress | :: R double | The current mining progress between 0 and 1 of this character, or 0 if they aren't mining.
The current mining progress between 0 and 1 of this character, or 0 if they aren't mining.

## Methods

### set_ending_screen_data(message, file?)

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

#### Parameters

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

### print(message, print_settings?)

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()

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? | 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.
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.
When `true`, won't play the "goal updated" sound.

### set_controller{type=…, character?=…, waypoints?=…, start_position?=…, start_zoom?=…, final_transition_time?=…, chart_mode_cutoff?=…, position?=…, surface?=…}

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

Table with the following fields:

type | :: defines.controllers | Which controller to use.
Which controller to use.
character | :: LuaEntity? | Entity to control. Mandatory when `type` is defines.controllers.character, ignored otherwise.
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.
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.
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.
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.
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.
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.
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.
If specified and `type` is defines.controllers.remote, the surface the remote controller will be put on.

### drag_wire{position=…} → boolean

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

#### Parameters

Table with the following fields:

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.
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.

#### Return values

→ boolean | `true` if the action did something

### 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[EntityWithQualityID]? | Entity prototypes to get statistics for. If not specified or empty, display statistics for all entities.
Entity prototypes to get statistics for. If not specified or empty, display statistics for all entities.

### print_robot_jobs()

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

### print_lua_object_statistics()

Print LuaObject counts per mod.

### 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
name of the achievement to unlock

### clear_cursor() → boolean

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

#### Return values

→ boolean | Whether the cursor is now empty.

#### Raised events

on_player_cursor_stack_changed? current_tick | Raised when the cursor was successfully cleared.

### create_character(character?) → boolean

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.
The character to create else the default is used.

#### Return values

→ boolean | Whether the character was created.

### add_alert(entity, type)

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(entity, icon, message, show_on_map)

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.
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{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:

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

### get_alerts{entity?=…, prototype?=…, position?=…, type?=…, surface?=…} → dictionary[uint32 → dictionary[defines.alert_type → array[Alert]]]

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

#### Parameters

Table with the following fields:

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

#### Return values

→ dictionary[uint32 → dictionary[defines.alert_type → array[Alert]]] | A mapping of surface index to an array of arrays of alerts indexed by the alert type.

### mute_alert(alert_type) → boolean

Mutes alerts for the given alert category.

#### Parameters

alert_type | :: defines.alert_type |

#### Return values

→ boolean | Whether 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 values

→ boolean | Whether 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 values

→ boolean | Whether 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 values

→ boolean | Whether 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 |

### add_pin{label?=…, preview_distance?=…, always_visible?=…, entity?=…, player?=…, surface?=…, position?=…}

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

#### Parameters

Table with the following fields:

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

### pipette_entity(entity, allow_ghost?) → boolean

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.
Defaults to false.

#### Return values

→ boolean | Whether the smart pipette found something to place.

#### Raised events

on_player_pipette? instantly | Raised if the entity was successfully pipetted.

### pipette(id, quality?, allow_ghost?) → boolean

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.
Defaults to false.

#### Return values

→ boolean | Whether the smart pipette found something to put into the cursor.

#### Raised events

on_player_pipette? instantly | Raised if an item was successfully put into the cursor.

### can_build_from_cursor{position=…, direction?=…, flip_horizontal?=…, flip_vertical?=…, build_mode?=…, 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 | :: MapPosition | Where the entity would be placed
Where the entity would be placed
direction | :: defines.direction? | Direction the entity would be placed
Direction the entity would be placed
flip_horizontal | :: boolean? | Whether to flip the blueprint horizontally. Defaults to `false`.
Whether to flip the blueprint horizontally. Defaults to `false`.
flip_vertical | :: boolean? | Whether to flip the blueprint vertically. Defaults to `false`.
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`.
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`.
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`.
If chunks covered by fog-of-war are skipped. Defaults to `false`.

### build_from_cursor{position=…, direction?=…, mirror?=…, flip_horizontal?=…, flip_vertical?=…, build_mode?=…, terrain_building_size?=…, skip_fog_of_war?=…}

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

Table with the following fields:

position | :: MapPosition | Where the entity would be placed
Where the entity would be placed
direction | :: defines.direction? | Direction the entity would be placed
Direction the entity would be placed
mirror | :: boolean? | Whether to mirror the entity
Whether to mirror the entity
flip_horizontal | :: boolean? | Whether to flip the blueprint horizontally. Defaults to `false`.
Whether to flip the blueprint horizontally. Defaults to `false`.
flip_vertical | :: boolean? | Whether to flip the blueprint vertically. Defaults to `false`.
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`.
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`.
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`.
If chunks covered by fog-of-war are skipped. Defaults to `false`.

#### Raised events

on_pre_build? instantly | Raised if the cursor was successfully built.
on_built_entity? instantly | Raised if the cursor was successfully built.

### clear_inventory_highlights()

Clears the blinking of the inventory based on insertion of items

### use_from_cursor(position)

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.
Where the item would be used.

### play_sound(sound_specification)

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.
The sound to play.

### get_associated_characters() → array[LuaEntity]

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.

### associate_character(character)

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.
The character entity.

### disassociate_character(character)

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
The character entity

### swap_characters(player) → boolean

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

#### Parameters

player | :: PlayerIdentification | The player to swap characters with.
The player to swap characters with.

#### Return values

→ boolean | `true` if the swap was successful.

### create_local_flying_text{text=…, position?=…, surface?=…, create_at_cursor?=…, color?=…, time_to_live?=…, speed?=…}

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

Table with the following fields:

text | :: LocalisedString | The flying text to show.
The flying text to show.
position | :: MapPosition? | The location on the map at which to show the flying text.
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.
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`.
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.
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`.
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.
The speed at which the text rises upwards in tiles/second. Can't be a negative value.

### clear_local_flying_texts()

Clear any active flying texts for this player.

### get_quick_bar_slot(index) → ItemFilter?

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.
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.

### set_quick_bar_slot(index, filter)

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.
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 or ItemWithQualityID or nil | The filter or `nil` to clear it.
The filter or `nil` to clear it.

### get_active_quick_bar_page(index) → uint8?

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.
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.

### set_active_quick_bar_page(screen_index, page_index)

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.
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.
The new quick bar page.

### jump_to_cutscene_waypoint(waypoint_index)

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

#### Parameters

waypoint_index | :: uint32 |

### exit_cutscene()

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

#### Raised events

on_cutscene_cancelled? instantly | Raised if the cutscene was successfully cancelled.

### exit_remote_view()

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

### is_shortcut_toggled(prototype_name) → boolean

Is a custom Lua shortcut currently toggled?

#### Parameters

prototype_name | :: string | Prototype name of the custom shortcut.
Prototype name of the custom shortcut.

### is_shortcut_available(prototype_name) → boolean

Is a custom Lua shortcut currently available?

#### Parameters

prototype_name | :: string | Prototype name of the custom shortcut.
Prototype name of the custom shortcut.

### set_shortcut_toggled(prototype_name, toggled)

Toggle or untoggle a custom Lua shortcut

#### Parameters

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

### set_shortcut_available(prototype_name, available)

Make a custom Lua shortcut available or unavailable.

#### Parameters

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

### connect_to_server{address=…, name?=…, description?=…, password?=…}

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

Table with the following fields:

address | :: string | The server (address:port) if port is not given the default Factorio port is used.
The server (address:port) if port is not given the default Factorio port is used.
name | :: LocalisedString? | The name of the server.
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.
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()

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.

#### Raised events

on_pre_player_toggled_map_editor? instantly | Raised if the map editor was successfully toggled.
on_player_toggled_map_editor? instantly | Raised if the map editor was successfully toggled.

### request_translation(localised_string) → uint32?

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 |

#### Return values

→ uint32? | The unique ID for the requested translation.

#### Raised events

on_string_translated? future_tick | Raised if the request was successfully sent.

### request_translations(localised_strings) → array[uint32]?

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] |

#### Return values

→ array[uint32]? | The unique IDs for the requested translations.

#### Raised events

on_string_translated? future_tick | Raised if the request was successfully sent.

### get_infinity_inventory_filter(index) → InfinityInventoryFilter?

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.
The index to get.

### set_infinity_inventory_filter(index, filter)

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

#### Parameters

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

### clear_recipe_notifications()

Clears all recipe notifications for this player.

### add_recipe_notification(recipe)

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

#### Parameters

recipe | :: RecipeID | Recipe to add.
Recipe to add.

### clear_recipe_notification(recipe)

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

#### Parameters

recipe | :: RecipeID | Recipe to clear.
Recipe to clear.

### get_recipe_notifications() → array[LuaRecipePrototype]

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

### add_to_clipboard(blueprint)

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

#### Parameters

blueprint | :: LuaItemStack | The blueprint to add.
The blueprint to add.

### activate_paste()

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(position, selection_mode)

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.
The position to start selection from.
selection_mode | :: defines.selection_mode | The type of selection to start.
The type of selection to start.

### clear_selection()

Clears the player's selection tool selection position.

### enter_space_platform(space_platform) → boolean

Enters the given space platform if possible.

#### Parameters

space_platform | :: LuaSpacePlatform |

#### Return values

→ boolean | If the player entered the platform.

### leave_space_platform()

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() → boolean

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

#### Return values

→ boolean | If the player successfully landed on the planet.

### set_zoom_limits(controller_type, zoom_limits)

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.
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.
The new zoom limits. See LuaPlayer::zoom_limits for usage information.

## Attributes

### physical_surface :: Read LuaSurface

The surface this player's physical controller is on.

### physical_surface_index :: Read uint32

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

### physical_position :: Read MapPosition

The current position of this player's physical controller.

### physical_vehicle :: Read LuaEntity?

The current vehicle of this player's physical controller.

### character :: Read|Write LuaEntity?

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

### cutscene_character :: Read LuaEntity?

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

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

### opened_self :: Read boolean

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

### controller_type :: Read defines.controllers

### physical_controller_type :: Read defines.controllers

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?

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

### spidertron_remote_selection :: Read|Write array[LuaEntity]?

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

### zoom :: Read|Write double

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|Write ZoomLimits

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.

#### Examples

    -- Lets the player zoom in to 4x the standard zoom level. (3x is the default for most controllers.)
    -- Increases the player zoom out level so that they can view approximately 800 tiles across.
    -- Sets furthest_game_view to furthest so that all zoom levels are rendered in game view, never chart (map) view.
    game.player.zoom_limits = {
      closest = { zoom = 4 },
      furthest = { distance = 800, max_distance = 1000 },
      furthest_game_view = { distance = 800, max_distance = 1000 }
    }

    -- Resets the closest and furthest_game_view limits to their defaults.
    -- Increases the furthest a player can zoom out to approximately 400 tiles across. There's a hard zoom limit at
    -- 800 tiles (either vertically or horizontally, whichever is more).
    game.player.zoom_limits = {
      furthest = { distance = 400, max_distance = 800 }
    }

    -- Sets the closest that the player can zoom in to 3x (the default for most controllers).
    -- Sets the furthest that the player can view in game view to some number GREATER than
    -- closest, guaranteeing that the player can only view the chart. However, this does NOT mean that the player
    -- can interact with the game as if in remote view if they are not explicitly using remote view.
    game.player.zoom_limits = {
      closest = { zoom = 3 },
      furthest_game_view = { zoom = 4 }
    }

    -- Save a copy of whatever zoom limits any script has previously set.
    local custom_limits = game.player.zoom_limits
    -- Resets all zoom limits to default.
    game.player.zoom_limits = {}
    -- Save a copy of whatever the default zoom limits are for the current controller.
    local default_limits = game.player.zoom_limits
    -- Set the zoom limits to a modification of the engine-default closest zoom limit (or 6 if the engine-default is
    -- not a fixed zoom value), the furthest limit previously defined by script (or the engine default if not
    -- previously set by a script), and some arbitrary value for `furthest_game_view`.
    game.player.zoom_limits = {
      closest = { zoom = (default_limits.furthest.zoom or 3.0) * 2 },
      furthest = custom_limits.furthest,
      furthest_game_view = { zoom = 0.25 }
    }

### centered_on :: Read|Write LuaEntity?

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|Write GameViewSettings

The player's game view settings.

### minimap_enabled :: Read|Write boolean

`true` if the minimap is visible.

### color :: Read|Write Color

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|Write Color

The color used when this player talks in game.

### name :: Read string

The player's username.

### tag :: Read|Write string

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

### connected :: Read boolean

`true` if the player is currently connected to the game.

### admin :: Read|Write boolean

`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?

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

### afk_time :: Read uint32

How many ticks since the last action of this player.

### online_time :: Read uint32

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

### last_online :: Read uint32

At what tick this player was last online.

### permission_group :: Read|Write LuaPermissionGroup?

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

### mod_settings :: Read LuaCustomTable[string → ModSetting]

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.

#### Example

    -- Change the value of the "active_lifestyle" setting
    player.mod_settings["active_lifestyle"] = {value = true}

### ticks_to_respawn :: Read|Write uint32?

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

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

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

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

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

The item stack containing a blueprint to be setup.

### blueprints :: Read array[LuaRecord]

Records contained in the player's blueprint library.

### render_mode :: Read defines.render_mode

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

### input_method :: Read defines.input_method

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

### spectator :: Read|Write boolean

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|Write boolean

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

### remove_unfiltered_items :: Read|Write boolean

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

### infinity_inventory_filters :: Read|Write array[InfinityInventoryFilter]

The filters for this map editor infinity inventory settings.

### auto_sort_main_inventory :: Read boolean

If the main inventory will be auto sorted.

### hand_location :: Read|Write ItemStackLocation?

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|Write boolean

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

The undo and redo stack for this player.

### drag_target :: Read DragTarget?

The wire drag target for this player, if any.

### map_view_settings :: Write MapViewSettings

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

### valid :: Read boolean

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

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.

Class used in

- LuaControl::opened
- LuaCustomChartTag::last_user
- LuaEntity::get_driver()
- LuaEntity::get_passenger()
- LuaEntity::player
- LuaEntity::last_user
- LuaEntity::associated_player
- LuaEntity::render_player
- LuaEquipmentGrid::player_owner
- LuaForce::players
- LuaForce::connected_players
- LuaGameScript::get_player()
- LuaGameScript::player
- LuaGameScript::players
- LuaGameScript::connected_players
- LuaGui::player
- LuaInventory::player_owner
- LuaPermissionGroup::players
- LuaRenderObject::players
- LuaSimulation::create_test_player()
- LuaTrain::passengers
- ItemLocationData
- PlayerIdentification
- RegistrationTarget
- on_gui_closed
- on_gui_opened