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

# Factorio Runtime Docs Version 2.0.77

# LuaGameScript - Runtime Docs

## Class LuaGameScript

Main toplevel type, provides access to most of the API though its members. An instance of LuaGameScript is available as the global object named `game`.

## Members

set_game_state{game_finished?=…, player_won?=…, next_level?=…, can_continue?=…} |  | Set scenario state. [...]
Set scenario state. [...]
reset_game_state() |  | Reset scenario state (game_finished, player_won, etc.).
Reset scenario state (game_finished, player_won, etc.).
set_win_ending_info{title=…, message?=…, bullet_points?=…, final_message?=…, image_path?=…} |  | Set winning ending information for the current scenario.
Set winning ending information for the current scenario.
set_lose_ending_info{title=…, message?=…, bullet_points?=…, final_message?=…, image_path?=…} |  | Set losing ending information for the current scenario.
Set losing ending information for the current scenario.
get_entity_by_tag(tag) | → LuaEntity? | Gets an entity by its name tag. [...]
Gets an entity by its name tag. [...]
show_message_dialog{text=…, image?=…, point_to?=…, style?=…, wrapper_frame_style?=…} |  | Show an in-game message dialog. [...]
Show an in-game message dialog. [...]
is_demo() | → boolean | Is this the demo version of Factorio?
Is this the demo version of Factorio?
reload_script() |  | Forces a reload of the scenario script from the original scenario location. [...]
Forces a reload of the scenario script from the original scenario location. [...]
reload_mods() |  | Forces a reload of all mods. [...]
Forces a reload of all mods. [...]
save_atlas() |  | Saves the current configuration of Atlas to a file. [...]
Saves the current configuration of Atlas to a file. [...]
check_consistency() |  | Run internal consistency checks. [...]
Run internal consistency checks. [...]
regenerate_entity(entities) |  | Regenerate autoplacement of some entities on all surfaces. [...]
Regenerate autoplacement of some entities on all surfaces. [...]
take_screenshot{player?=…, by_player?=…, surface?=…, position?=…, resolution?=…, zoom?=…, path?=…, show_gui?=…, show_entity_info?=…, show_cursor_building_preview?=…, anti_alias?=…, hide_clouds?=…, hide_fog?=…, quality?=…, allow_in_replay?=…, daytime?=…, water_tick?=…, force_render?=…} |  | Take a screenshot of the game and save it to the `script-output` folder, located in the game's user data directory. [...]
Take a screenshot of the game and save it to the `script-output` folder, located in the game's user data directory. [...]
set_wait_for_screenshots_to_finish() |  | Forces the screenshot saving system to wait until all queued screenshots have been written to disk.
Forces the screenshot saving system to wait until all queued screenshots have been written to disk.
take_technology_screenshot{path?=…, player=…, selected_technology?=…, skip_disabled?=…, quality?=…} |  | Take a screenshot of the technology screen and save it to the `script-output` folder, located in the game's user data directory. [...]
Take a screenshot of the technology screen and save it to the `script-output` folder, located in the game's user data directory. [...]
remove_offline_players(players?) |  | Remove players who are currently not connected from the map.
Remove players who are currently not connected from the map.
force_crc() |  | Force a CRC check. [...]
Force a CRC check. [...]
create_force(force) | → LuaForce | Create a new force. [...]
Create a new force. [...]
merge_forces(source, destination) |  | Marks two forces to be merged together. [...]
Marks two forces to be merged together. [...]
create_surface(name, settings?) | → LuaSurface | Create a new surface. [...]
Create a new surface. [...]
server_save(name?) |  | Instruct the server to save the map. [...]
Instruct the server to save the map. [...]
auto_save(name?) |  | Instruct the game to perform an auto-save. [...]
Instruct the game to perform an auto-save. [...]
delete_surface(surface) | → boolean | Deletes the given surface and all entities on it if possible.
Deletes the given surface and all entities on it if possible.
disable_replay() |  | Disables replay saving for the current save file. [...]
Disables replay saving for the current save file. [...]
print(message, print_settings?) |  | Print text to the chat console all players. [...]
Print text to the chat console all players. [...]
create_random_generator(seed?) | → LuaRandomGenerator | Creates a deterministic standalone random generator with the given seed or if a seed is not provided the initial map seed is used. [...]
Creates a deterministic standalone random generator with the given seed or if a seed is not provided the initial map seed is used. [...]
play_sound(sound_specification) |  | Play a sound for every player in the game. [...]
Play a sound for every player in the game. [...]
kick_player(player, reason?) |  | Kicks the given player from this multiplayer game. [...]
Kicks the given player from this multiplayer game. [...]
ban_player(player, reason?) |  | Bans the given player from this multiplayer game. [...]
Bans the given player from this multiplayer game. [...]
unban_player(player) |  | Unbans the given player from this multiplayer game. [...]
Unbans the given player from this multiplayer game. [...]
purge_player(player) |  | Purges the given players messages from the game. [...]
Purges the given players messages from the game. [...]
mute_player(player) |  | Mutes the given player. [...]
Mutes the given player. [...]
unmute_player(player) |  | Unmutes the given player. [...]
Unmutes the given player. [...]
is_multiplayer() | → boolean | Whether the save is loaded as a multiplayer map.
Whether the save is loaded as a multiplayer map.
get_map_exchange_string() | → string | Gets the map exchange string for the map generation settings that were used to create this map.
Gets the map exchange string for the map generation settings that were used to create this map.
get_player(player) | → LuaPlayer? | Gets the given player or returns `nil` if no player is found.
Gets the given player or returns `nil` if no player is found.
get_surface(surface) | → LuaSurface? | Gets the given surface or returns `nil` if no surface is found. [...]
Gets the given surface or returns `nil` if no surface is found. [...]
create_profiler(stopped?) | → LuaProfiler | Creates a LuaProfiler, which is used for measuring script performance. [...]
Creates a LuaProfiler, which is used for measuring script performance. [...]
create_inventory(size, gui_title?) | → LuaInventory | Creates an inventory that is not owned by any game object. [...]
Creates an inventory that is not owned by any game object. [...]
get_script_inventories(mod?) | → dictionary[string → array[LuaInventory]] | Gets the inventories created through LuaGameScript::create_inventory. [...]
Gets the inventories created through LuaGameScript::create_inventory. [...]
reset_time_played() |  | Resets the amount of time played for this map.
Resets the amount of time played for this map.
get_pollution_statistics(surface) | → LuaFlowStatistics | The pollution statistics for this the given surface.
The pollution statistics for this the given surface.
get_vehicles{unit_number?=…, force?=…, surface?=…, type?=…, is_moving?=…, has_passenger?=…} | → array[LuaEntity] | Returns vehicles in game.
Returns vehicles in game.
get_entity_by_unit_number(unit_number) | → LuaEntity? | Returns entity with a specified unit number or nil if entity with such number was not found or prototype does not have EntityPrototypeFlags::get-by-unit-number flag set.
Returns entity with a specified unit number or nil if entity with such number was not found or prototype does not have EntityPrototypeFlags::get-by-unit-number flag set.
allow_debug_settings | :: RW boolean | Whether players who are not admins can access all debug settings. [...]
Whether players who are not admins can access all debug settings. [...]
object_name | :: R string | The class name of this object. [...]
The class name of this object. [...]
player | :: R LuaPlayer? | This property is only populated inside custom command handlers and when writing Lua console commands. [...]
This property is only populated inside custom command handlers and when writing Lua console commands. [...]
players | :: R LuaCustomTable[uint32 or string → LuaPlayer] | Get a table of all the players that currently exist. [...]
Get a table of all the players that currently exist. [...]
map_settings | :: R MapSettings | The currently active set of map settings. [...]
The currently active set of map settings. [...]
difficulty_settings | :: R DifficultySettings | The currently active set of difficulty settings. [...]
The currently active set of difficulty settings. [...]
difficulty | :: R defines.difficulty | Current scenario difficulty.
Current scenario difficulty.
forces | :: R LuaCustomTable[uint32 or string → LuaForce] | Get a table of all the forces that currently exist. [...]
Get a table of all the forces that currently exist. [...]
console_command_used | :: R boolean | Whether a console command has been used.
Whether a console command has been used.
simulation | :: R LuaSimulation | Simulation-related functions, or `nil` if the current game is not a simulation.
Simulation-related functions, or `nil` if the current game is not a simulation.
tick | :: R MapTick | Current map tick.
Current map tick.
ticks_played | :: R MapTick | The number of ticks since this game was created using either "new game" or "new game from scenario". [...]
The number of ticks since this game was created using either "new game" or "new game from scenario". [...]
tick_paused | :: RW boolean | If the tick has been paused. [...]
If the tick has been paused. [...]
ticks_to_run | :: RW uint32 | The number of ticks to be run while the tick is paused. [...]
The number of ticks to be run while the tick is paused. [...]
finished | :: R boolean | True while the victory screen is shown.
True while the victory screen is shown.
finished_but_continuing | :: R boolean | True after players finished the game and clicked "continue".
True after players finished the game and clicked "continue".
speed | :: RW float | Speed to update the map at. [...]
Speed to update the map at. [...]
surfaces | :: R LuaCustomTable[uint32 or string → LuaSurface] | Get a table of all the surfaces that currently exist. [...]
Get a table of all the surfaces that currently exist. [...]
planets | :: R LuaCustomTable[string → LuaPlanet] |
connected_players | :: R array[LuaPlayer] | The players that are currently online. [...]
The players that are currently online. [...]
permissions | :: R LuaPermissionGroups |
backer_names | :: R LuaCustomTable[uint32 → string] | Array of the names of all the backers that supported the game development early on. [...]
Array of the names of all the backers that supported the game development early on. [...]
default_map_gen_settings | :: R MapGenSettings | The default map gen settings for this save.
The default map gen settings for this save.
enemy_has_vision_on_land_mines | :: RW boolean | Determines if enemy land mines are completely invisible or not.
Determines if enemy land mines are completely invisible or not.
autosave_enabled | :: RW boolean | True by default. [...]
True by default. [...]
draw_resource_selection | :: RW boolean | True by default. [...]
True by default. [...]
train_manager | :: R LuaTrainManager |
blueprints | :: R array[LuaRecord] | Records contained in the "game blueprints" tab of the blueprint library.
Records contained in the "game blueprints" tab of the blueprint library.
technology_notifications_enabled | :: RW boolean | True by default. [...]
True by default. [...]
allow_tip_activation | :: RW boolean | If the tips are allowed to be activated in this scenario, it is false by default. [...]
If the tips are allowed to be activated in this scenario, it is false by default. [...]

## Methods

### set_game_state{game_finished?=…, player_won?=…, next_level?=…, can_continue?=…}

Set scenario state. Any parameters not provided do not change the current state.

#### Parameters

Table with the following fields:

game_finished | :: boolean? |
player_won | :: boolean? |
next_level | :: string? |
can_continue | :: boolean? |

### reset_game_state()

Reset scenario state (game_finished, player_won, etc.).

### set_win_ending_info{title=…, message?=…, bullet_points?=…, final_message?=…, image_path?=…}

Set winning ending information for the current scenario.

#### Parameters

Table with the following fields:

title | :: LocalisedString |
message | :: LocalisedString? |
bullet_points | :: array[LocalisedString]? |
final_message | :: LocalisedString? |
image_path | :: string? |

### set_lose_ending_info{title=…, message?=…, bullet_points?=…, final_message?=…, image_path?=…}

Set losing ending information for the current scenario.

#### Parameters

Table with the following fields:

title | :: LocalisedString |
message | :: LocalisedString? |
bullet_points | :: array[LocalisedString]? |
final_message | :: LocalisedString? |
image_path | :: string? |

### get_entity_by_tag(tag) → LuaEntity?

Gets an entity by its name tag. Entity name tags can also be set in the entity "extra settings" GUI in the map editor.

#### Parameters

tag | :: string |

### show_message_dialog{text=…, image?=…, point_to?=…, style?=…, wrapper_frame_style?=…}

Show an in-game message dialog.

Can only be used when the map contains exactly one player.

#### Parameters

Table with the following fields:

text | :: LocalisedString | What the dialog should say
What the dialog should say
image | :: string? | Path to an image to show on the dialog
Path to an image to show on the dialog
point_to | :: GuiArrowSpecification? | If specified, dialog will show an arrow pointing to this place. When not specified, the arrow will point to the player's position. (Use `point_to={type="nowhere"}` to remove the arrow entirely.) The dialog itself will be placed near the arrow's target.
If specified, dialog will show an arrow pointing to this place. When not specified, the arrow will point to the player's position. (Use `point_to={type="nowhere"}` to remove the arrow entirely.) The dialog itself will be placed near the arrow's target.
style | :: string? | The gui style to use for this speech bubble. Must be of type speech_bubble.
The gui style to use for this speech bubble. Must be of type speech_bubble.
wrapper_frame_style | :: string? | Must be of type flow_style.
Must be of type flow_style.

### is_demo() → boolean

Is this the demo version of Factorio?

### reload_script()

Forces a reload of the scenario script from the original scenario location.

This disables the replay if replay is enabled.

### reload_mods()

Forces a reload of all mods.

This will act like saving and loading from the mod(s) perspective.

This will do nothing if run in multiplayer.

This disables the replay if replay is enabled.

### save_atlas()

Saves the current configuration of Atlas to a file. This will result in huge file containing all of the game graphics moved to as small space as possible.

Exists mainly for debugging reasons.

### check_consistency()

Run internal consistency checks. Allegedly prints any errors it finds.

Exists mainly for debugging reasons.

### regenerate_entity(entities)

Regenerate autoplacement of some entities on all surfaces. This can be used to autoplace newly-added entities.

All specified entity prototypes must be autoplacable.

#### Parameters

entities | :: string or array[string] | Prototype names of entity or entities to autoplace.
Prototype names of entity or entities to autoplace.

### take_screenshot{player?=…, by_player?=…, surface?=…, position?=…, resolution?=…, zoom?=…, path?=…, show_gui?=…, show_entity_info?=…, show_cursor_building_preview?=…, anti_alias?=…, hide_clouds?=…, hide_fog?=…, quality?=…, allow_in_replay?=…, daytime?=…, water_tick?=…, force_render?=…}

Take a screenshot of the game and save it to the `script-output` folder, located in the game's user data directory. The name of the image file can be specified via the `path` parameter.

If Factorio is running headless, this function will do nothing.

#### Parameters

Table with the following fields:

player | :: PlayerIdentification? | The player to focus on. Defaults to the local player.
The player to focus on. Defaults to the local player.
by_player | :: PlayerIdentification? | If defined, the screenshot will only be taken for this player.
If defined, the screenshot will only be taken for this player.
surface | :: SurfaceIdentification? | If defined, the screenshot will be taken on this surface.
If defined, the screenshot will be taken on this surface.
position | :: MapPosition? | If defined, the screenshot will be centered on this position. Otherwise, the screenshot will center on `player`.
If defined, the screenshot will be centered on this position. Otherwise, the screenshot will center on `player`.
resolution | :: TilePosition? | The maximum allowed resolution is 16384x16384 (8192x8192 when `anti_alias` is `true`), but the maximum recommended resolution is 4096x4096 (resp. 2048x2048). The `x` value of the position is used as the width, the `y` value as the height.
The maximum allowed resolution is 16384x16384 (8192x8192 when `anti_alias` is `true`), but the maximum recommended resolution is 4096x4096 (resp. 2048x2048). The `x` value of the position is used as the width, the `y` value as the height.
zoom | :: double? | The map zoom to take the screenshot at. Defaults to `1`.
The map zoom to take the screenshot at. Defaults to `1`.
path | :: string? | The name of the image file. It should include a file extension indicating the desired format. Supports `.png`, `.jpg` /`.jpeg`, `.tga` and `.bmp`. Providing a directory path (ex. `"save/here/screenshot.png"`) will create the necessary folder structure in `script-output`. Defaults to `"screenshot.png"`.
The name of the image file. It should include a file extension indicating the desired format. Supports `.png`, `.jpg` /`.jpeg`, `.tga` and `.bmp`. Providing a directory path (ex. `"save/here/screenshot.png"`) will create the necessary folder structure in `script-output`. Defaults to `"screenshot.png"`.
show_gui | :: boolean? | Whether to include GUIs in the screenshot or not. Defaults to `false`.
Whether to include GUIs in the screenshot or not. Defaults to `false`.
show_entity_info | :: boolean? | Whether to include entity info ("Alt mode") or not. Defaults to `false`.
Whether to include entity info ("Alt mode") or not. Defaults to `false`.
show_cursor_building_preview | :: boolean? | When `true` and when `player` is specified, the building preview for the item in the player's cursor will also be rendered. Defaults to `false`.
When `true` and when `player` is specified, the building preview for the item in the player's cursor will also be rendered. Defaults to `false`.
anti_alias | :: boolean? | Whether to render in double resolution and downscale the result (including GUI). Defaults to `false`.
Whether to render in double resolution and downscale the result (including GUI). Defaults to `false`.
hide_clouds | :: boolean? | If `true` cloud shadows on ground won't be rendered. Defaults to `false`.
If `true` cloud shadows on ground won't be rendered. Defaults to `false`.
hide_fog | :: boolean? | If `true` fog effect and foreground space dust effect won't be rendered. Defaults to `false`.
If `true` fog effect and foreground space dust effect won't be rendered. Defaults to `false`.
quality | :: int32? | The `.jpg` render quality as a percentage (from 0% to 100% inclusive), if used. A lower value means a more compressed image. Defaults to `80`.
The `.jpg` render quality as a percentage (from 0% to 100% inclusive), if used. A lower value means a more compressed image. Defaults to `80`.
allow_in_replay | :: boolean? | Whether to save the screenshot even during replay playback. Defaults to `false`.
Whether to save the screenshot even during replay playback. Defaults to `false`.
daytime | :: double? | Overrides the current surface daytime for the duration of screenshot rendering.
Overrides the current surface daytime for the duration of screenshot rendering.
water_tick | :: uint32? | Overrides the tick of water animation, if animated water is enabled.
Overrides the tick of water animation, if animated water is enabled.
force_render | :: boolean? | Screenshot requests are processed in between game update and render. The game may skip rendering (ie. drop frames) if the previous frame has not finished rendering or the game simulation starts to fall below 60 updates per second. If `force_render` is set to `true`, the game won't drop frames and process the screenshot request at the end of the update in which the request was created. This is not honored on multiplayer clients that are catching up to server. Defaults to `false`.
Screenshot requests are processed in between game update and render. The game may skip rendering (ie. drop frames) if the previous frame has not finished rendering or the game simulation starts to fall below 60 updates per second. If `force_render` is set to `true`, the game won't drop frames and process the screenshot request at the end of the update in which the request was created. This is not honored on multiplayer clients that are catching up to server. Defaults to `false`.

### set_wait_for_screenshots_to_finish()

Forces the screenshot saving system to wait until all queued screenshots have been written to disk.

### take_technology_screenshot{path?=…, player=…, selected_technology?=…, skip_disabled?=…, quality?=…}

Take a screenshot of the technology screen and save it to the `script-output` folder, located in the game's user data directory. The name of the image file can be specified via the `path` parameter.

#### Parameters

Table with the following fields:

path | :: string? | The name of the image file. It should include a file extension indicating the desired format. Supports `.png`, `.jpg` /`.jpeg`, `.tga` and `.bmp`. Providing a directory path (ex. `"save/here/screenshot.png"`) will create the necessary folder structure in `script-output`. Defaults to `"technology-screenshot.png"`.
The name of the image file. It should include a file extension indicating the desired format. Supports `.png`, `.jpg` /`.jpeg`, `.tga` and `.bmp`. Providing a directory path (ex. `"save/here/screenshot.png"`) will create the necessary folder structure in `script-output`. Defaults to `"technology-screenshot.png"`.
player | :: PlayerIdentification | The screenshot will be taken for this player.
The screenshot will be taken for this player.
selected_technology | :: TechnologyID? | The technology to highlight.
The technology to highlight.
skip_disabled | :: boolean? | If `true`, disabled technologies will be skipped. Their successors will be attached to the disabled technology's parents. Defaults to `false`.
If `true`, disabled technologies will be skipped. Their successors will be attached to the disabled technology's parents. Defaults to `false`.
quality | :: int32? | The `.jpg` render quality as a percentage (from 0% to 100% inclusive), if used. A lower value means a more compressed image. Defaults to `80`.
The `.jpg` render quality as a percentage (from 0% to 100% inclusive), if used. A lower value means a more compressed image. Defaults to `80`.

### remove_offline_players(players?)

Remove players who are currently not connected from the map.

#### Parameters

players | :: array[PlayerIdentification]? | List of players to remove. If not specified, remove all offline players.
List of players to remove. If not specified, remove all offline players.

#### Raised events

on_pre_player_removed instantly |
on_player_removed instantly |

### force_crc()

Force a CRC check. Tells all peers to calculate their current CRC, which are then compared to each other. If a mismatch is detected, the game desyncs and some peers are forced to reconnect.

### create_force(force) → LuaForce

Create a new force.

The game currently supports a maximum of 64 forces, including the three built-in forces. This means that a maximum of 61 new forces may be created. Force names must be unique.

#### Parameters

force | :: string | Name of the new force
Name of the new force

#### Return values

→ LuaForce | The force that was just created

#### Raised events

on_force_created instantly |

### merge_forces(source, destination)

Marks two forces to be merged together. All players and entities in the source force will be reassigned to the target force. The source force will then be destroyed. Importantly, this does not merge technologies or bonuses, which are instead retained from the target force.

The three built-in forces (player, enemy and neutral) can't be destroyed, meaning they can't be used as the source argument to this function.

The source force is not removed until the end of the current tick, or if called during the on_forces_merging or on_forces_merged event, the end of the next tick.

#### Parameters

source | :: ForceID | The force to remove.
The force to remove.
destination | :: ForceID | The force to reassign all entities to.
The force to reassign all entities to.

#### Raised events

on_forces_merging future_tick |
on_forces_merged future_tick |

### create_surface(name, settings?) → LuaSurface

Create a new surface.

The game currently supports a maximum of 4 294 967 295 surfaces, including the default surface. Surface names must be unique.

#### Parameters

name | :: string | Name of the new surface.
Name of the new surface.
settings | :: MapGenSettings? | Map generation settings.
Map generation settings.

#### Return values

→ LuaSurface | The surface that was just created.

#### Raised events

on_surface_created instantly |

### server_save(name?)

Instruct the server to save the map. Only actually saves when in multiplayer.

#### Parameters

name | :: string? | Save file name. If not specified, the currently running save is overwritten. If there is no current save, no save is made.
Save file name. If not specified, the currently running save is overwritten. If there is no current save, no save is made.

### auto_save(name?)

Instruct the game to perform an auto-save.

Only the server will save in multiplayer. In single player a standard auto-save is triggered.

#### Parameters

name | :: string? | The autosave name if any. Saves will be named _autosave-name when provided.
The autosave name if any. Saves will be named _autosave-name when provided.

### delete_surface(surface) → boolean

Deletes the given surface and all entities on it if possible.

#### Parameters

surface | :: SurfaceIdentification | The surface to be deleted. Currently the primary surface (1, 'nauvis') cannot be deleted.
The surface to be deleted. Currently the primary surface (1, 'nauvis') cannot be deleted.

#### Return values

→ boolean | If the surface was queued to be deleted.

#### Raised events

on_pre_surface_deleted future_tick |
on_surface_deleted future_tick |

### disable_replay()

Disables replay saving for the current save file. Once done there's no way to re-enable replay saving for the save file without loading an old save.

### print(message, print_settings?)

Print text to the chat console all players.

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

### create_random_generator(seed?) → LuaRandomGenerator

Creates a deterministic standalone random generator with the given seed or if a seed is not provided the initial map seed is used.

Make sure you actually want to use this over math.random(...) as this provides entirely different functionality over math.random(...).

#### Parameters

seed | :: uint32? |

### play_sound(sound_specification)

Play a sound for every player in the game.

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

#### Parameters

sound_specification | :: PlaySoundSpecification | The sound to play.
The sound to play.

### kick_player(player, reason?)

Kicks the given player from this multiplayer game. Does nothing if this is a single player game or if the player running this isn't an admin.

#### Parameters

player | :: PlayerIdentification | The player to kick.
The player to kick.
reason | :: string? | The reason given if any.
The reason given if any.

#### Raised events

on_player_kicked instantly |
on_console_command instantly |

### ban_player(player, reason?)

Bans the given player from this multiplayer game. Does nothing if this is a single player game of if the player running this isn't an admin.

#### Parameters

player | :: PlayerIdentification or string | The player to ban.
The player to ban.
reason | :: string? | The reason given if any.
The reason given if any.

#### Raised events

on_player_banned instantly |
on_console_command instantly |

### unban_player(player)

Unbans the given player from this multiplayer game. Does nothing if this is a single player game of if the player running this isn't an admin.

#### Parameters

player | :: PlayerIdentification or string | The player to unban.
The player to unban.

#### Raised events

on_player_unbanned instantly |
on_console_command instantly |

### purge_player(player)

Purges the given players messages from the game. Does nothing if the player running this isn't an admin.

#### Parameters

player | :: PlayerIdentification | The player to purge.
The player to purge.

#### Raised events

on_console_command instantly |

### mute_player(player)

Mutes the given player. Does nothing if the player running this isn't an admin.

#### Parameters

player | :: PlayerIdentification | The player to mute.
The player to mute.

#### Raised events

on_player_muted instantly |
on_console_command instantly |

### unmute_player(player)

Unmutes the given player. Does nothing if the player running this isn't an admin.

#### Parameters

player | :: PlayerIdentification | The player to unmute.
The player to unmute.

#### Raised events

on_player_unmuted instantly |
on_console_command instantly |

### is_multiplayer() → boolean

Whether the save is loaded as a multiplayer map.

### get_map_exchange_string() → string

Gets the map exchange string for the map generation settings that were used to create this map.

### get_player(player) → LuaPlayer?

Gets the given player or returns `nil` if no player is found.

#### Parameters

player | :: uint32 or string | The player index or name.
The player index or name.

### get_surface(surface) → LuaSurface?

Gets the given surface or returns `nil` if no surface is found.

This is a shortcut for LuaGameScript::surfaces.

#### Parameters

surface | :: uint32 or string | The surface index or name.
The surface index or name.

### create_profiler(stopped?) → LuaProfiler

Creates a LuaProfiler, which is used for measuring script performance.

LuaProfiler cannot be serialized.

#### Parameters

stopped | :: boolean? | Create the timer stopped
Create the timer stopped

### create_inventory(size, gui_title?) → LuaInventory

Creates an inventory that is not owned by any game object.

It can be resized later with LuaInventory::resize.

Make sure to destroy it when you are done with it using LuaInventory::destroy.

#### Parameters

size | :: uint16 | The number of slots the inventory initially has.
The number of slots the inventory initially has.
gui_title | :: LocalisedString? | The title of the GUI that is shown when this inventory is opened.
The title of the GUI that is shown when this inventory is opened.

### get_script_inventories(mod?) → dictionary[string → array[LuaInventory]]

Gets the inventories created through LuaGameScript::create_inventory.

Inventories created through console commands will be owned by `"core"`.

#### Parameters

mod | :: string? | The mod whose inventories to get. If not provided all inventories are returned.
The mod whose inventories to get. If not provided all inventories are returned.

#### Return values

→ dictionary[string → array[LuaInventory]] | A mapping of mod name to array of inventories owned by that mod.

### reset_time_played()

Resets the amount of time played for this map.

### get_pollution_statistics(surface) → LuaFlowStatistics

The pollution statistics for this the given surface.

#### Parameters

surface | :: SurfaceIdentification |

### get_vehicles{unit_number?=…, force?=…, surface?=…, type?=…, is_moving?=…, has_passenger?=…} → array[LuaEntity]

Returns vehicles in game.

#### Parameters

Table with the following fields:

unit_number | :: uint32? |
force | :: ForceID? |
surface | :: SurfaceIdentification? |
type | :: EntityID or array[EntityID]? |
is_moving | :: boolean? |
has_passenger | :: boolean? |

### get_entity_by_unit_number(unit_number) → LuaEntity?

Returns entity with a specified unit number or nil if entity with such number was not found or prototype does not have EntityPrototypeFlags::get-by-unit-number flag set.

#### Parameters

unit_number | :: uint32 |

## Attributes

### allow_debug_settings :: Read|Write boolean

Whether players who are not admins can access all debug settings. Set this to false to disallow access to most debug settings for non-admins.

The following debug settings are always available to all players: `"show-fps"`, `"show-clock"`, `"show-time-to-next-autosave"`, `"show-detailed-info"`, `"show-time-usage"`, `"show-entity-time-usage"`, `"show-gpu-time-usage"`, `"show-sprite-counts"`, `"show-particle-counts"`, `"show-collector-navmesh-time-usage"`, `"show-lua-object-statistics"`, `"show-heat-buffer-info"`, `"show-multiplayer-waiting-icon"`, `"show-multiplayer-statistics"`, `"show-multiplayer-server-name"`, `"show-debug-info-in-tooltips"`, `"show-resistances-in-tooltips-always"`, `"hide-mod-guis"`, `"show-tile-grid"`, `"show-blueprint-grid"`, `"show-intermediate-volume-of-working-sounds"`, `"show-decorative-names"`, `"allow-increased-zoom"`, `"show-train-no-path-details"`, `"show-entity-tick"`, `"show-update-tick"`

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

### player :: Read LuaPlayer?

This property is only populated inside custom command handlers and when writing Lua console commands. Returns the player that is typing the command, `nil` in all other instances.

See LuaGameScript::players for accessing all players.

### players :: Read LuaCustomTable[uint32 or string → LuaPlayer]

Get a table of all the players that currently exist. This sparse table allows you to find players by indexing it with either their `name` or `index`. Iterating this table with `pairs()` will provide the `index`es as the keys. Iterating with `ipairs()` will not work at all.

If only a single player is required, LuaGameScript::get_player should be used instead, as it avoids the unnecessary overhead of passing the whole table to Lua.

### map_settings :: Read MapSettings

The currently active set of map settings. Even though this property is marked as read-only, the members of the dictionary that is returned can be modified mid-game.

This does not contain difficulty settings, use LuaGameScript::difficulty_settings instead.

### difficulty_settings :: Read DifficultySettings

The currently active set of difficulty settings. Even though this property is marked as read-only, the members of the dictionary that is returned can be modified mid-game.

#### Example

    -- This will set the technology price multiplier to 12.
    game.difficulty_settings.technology_price_multiplier = 12

### difficulty :: Read defines.difficulty

Current scenario difficulty.

### forces :: Read LuaCustomTable[uint32 or string → LuaForce]

Get a table of all the forces that currently exist. This sparse table allows you to find forces by indexing it with either their `name` or `index`. Iterating this table with `pairs()` will provide the `name`s as the keys. Iterating with `ipairs()` will not work at all.

### console_command_used :: Read boolean

Whether a console command has been used.

### simulation :: Read LuaSimulation

Simulation-related functions, or `nil` if the current game is not a simulation.

### tick :: Read MapTick

Current map tick.

### ticks_played :: Read MapTick

The number of ticks since this game was created using either "new game" or "new game from scenario". Notably, this number progresses even when the game is tick_paused.

This differs from LuaGameScript::tick in that creating a game from a scenario always starts with this value at `0`, even if the scenario has its own level data where the `tick` has progressed past `0`.

### tick_paused :: Read|Write boolean

If the tick has been paused. This means that entity update has been paused.

### ticks_to_run :: Read|Write uint32

The number of ticks to be run while the tick is paused.

When LuaGameScript::tick_paused is true, ticks_to_run behaves the following way: While this is > 0, the entity update is running normally and this value is decremented every tick. When this reaches 0, the game will pause again.

### finished :: Read boolean

True while the victory screen is shown.

### finished_but_continuing :: Read boolean

True after players finished the game and clicked "continue".

### speed :: Read|Write float

Speed to update the map at. 1.0 is normal speed -- 60 UPS. Minimum value is 0.01.

### surfaces :: Read LuaCustomTable[uint32 or string → LuaSurface]

Get a table of all the surfaces that currently exist. This sparse table allows you to find surfaces by indexing it with either their `name` or `index`. Iterating this table with `pairs()` will provide the `name`s as the keys. Iterating with `ipairs()` will not work at all.

### planets :: Read LuaCustomTable[string → LuaPlanet]

### connected_players :: Read array[LuaPlayer]

The players that are currently online.

This does not index using player index. See LuaPlayer::index on each player instance for the player index. This is primarily useful when you want to do some action against all online players.

### permissions :: Read LuaPermissionGroups

### backer_names :: Read LuaCustomTable[uint32 → string]

Array of the names of all the backers that supported the game development early on. These are used as names for labs, locomotives, radars, roboports, and train stops.

### default_map_gen_settings :: Read MapGenSettings

The default map gen settings for this save.

### enemy_has_vision_on_land_mines :: Read|Write boolean

Determines if enemy land mines are completely invisible or not.

### autosave_enabled :: Read|Write boolean

True by default. Can be used to disable autosaving. Make sure to turn it back on soon after.

### draw_resource_selection :: Read|Write boolean

True by default. Can be used to disable the highlighting of resource patches when they are hovered on the map.

### train_manager :: Read LuaTrainManager

### blueprints :: Read array[LuaRecord]

Records contained in the "game blueprints" tab of the blueprint library.

### technology_notifications_enabled :: Read|Write boolean

True by default. Can be used to prevent the game engine from printing certain messages.

Prevented messages: "player-started-research" "player-queued-research" "player-cancelled-research" "technology-researched"

### allow_tip_activation :: Read|Write boolean

If the tips are allowed to be activated in this scenario, it is false by default.

Can't be modified in a simulation (menu screen, tips and tricks simulation, factoriopedia simulation etc.)