Home

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.

Attributes

allow_debug_settings

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

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

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

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

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

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.

difficulty

Current scenario difficulty.

forces

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 names as the keys. Iterating with ipairs() will not work at all.

console_command_used

Whether a console command has been used.

simulation

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

tick

Current map tick.

ticks_played

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

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

ticks_to_run

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

True while the victory screen is shown.

finished_but_continuing

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

speed

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

surfaces

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 names as the keys. Iterating with ipairs() will not work at all.

planets

connected_players

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

backer_names

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

The default map gen settings for this save.

enemy_has_vision_on_land_mines

Determines if enemy land mines are completely invisible or not.

autosave_enabled

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

draw_resource_selection

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

train_manager

blueprints

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

technology_notifications_enabled

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

allow_tip_activation

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

Methods

set_game_state

LuaGameScript.set_game_state{ game_finished?: boolean, player_won?: boolean, next_level?: string, can_continue?: boolean }

Call As

game.set_game_state{ game_finished=true }

Call Convention

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

Parameters

reset_game_state

LuaGameScript.reset_game_state()

Call As

game.reset_game_state()

Call Convention

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

set_win_ending_info

LuaGameScript.set_win_ending_info{ title: LocalisedString, message?: LocalisedString, bullet_points?: Array<LocalisedString>, final_message?: LocalisedString, image_path?: string }

Call As

game.set_win_ending_info{ title=title }

Call Convention

Set winning ending information for the current scenario.

Parameters

set_lose_ending_info

LuaGameScript.set_lose_ending_info{ title: LocalisedString, message?: LocalisedString, bullet_points?: Array<LocalisedString>, final_message?: LocalisedString, image_path?: string }

Call As

game.set_lose_ending_info{ title=title }

Call Convention

Set losing ending information for the current scenario.

Parameters

get_entity_by_tag

LuaGameScript.get_entity_by_tag(tag: string) -> LuaEntity?

Call As

game.get_entity_by_tag(tag)

Call Convention

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

Returns

show_message_dialog

LuaGameScript.show_message_dialog{ text: LocalisedString, image?: string, point_to?: GuiArrowSpecification, style?: string, wrapper_frame_style?: string }

Call As

game.show_message_dialog{ text=text }

Call Convention

Show an in-game message dialog.

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

Parameters

is_demo

LuaGameScript.is_demo() -> boolean

Call As

game.is_demo()

Call Convention

Is this the demo version of Factorio?

Returns

reload_script

LuaGameScript.reload_script()

Call As

game.reload_script()

Call Convention

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

This disables the replay if replay is enabled.

reload_mods

LuaGameScript.reload_mods()

Call As

game.reload_mods()

Call Convention

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

LuaGameScript.save_atlas()

Call As

game.save_atlas()

Call Convention

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

LuaGameScript.check_consistency()

Call As

game.check_consistency()

Call Convention

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

Exists mainly for debugging reasons.

regenerate_entity

LuaGameScript.regenerate_entity(entities: string | Array<string>)

Call As

game.regenerate_entity(entities)

Call Convention

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

take_screenshot

LuaGameScript.take_screenshot{ player?: PlayerIdentification, by_player?: PlayerIdentification, surface?: SurfaceIdentification, position?: MapPosition, resolution?: TilePosition, zoom?: double, path?: string, show_gui?: boolean, show_entity_info?: boolean, show_cursor_building_preview?: boolean, anti_alias?: boolean, hide_clouds?: boolean, hide_fog?: boolean, quality?: int32, allow_in_replay?: boolean, daytime?: double, water_tick?: uint32, force_render?: boolean }

Call As

game.take_screenshot{ player=player }

Call Convention

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

set_wait_for_screenshots_to_finish

LuaGameScript.set_wait_for_screenshots_to_finish()

Call As

game.set_wait_for_screenshots_to_finish()

Call Convention

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

take_technology_screenshot

LuaGameScript.take_technology_screenshot{ path?: string, player: PlayerIdentification, selected_technology?: TechnologyID, skip_disabled?: boolean, quality?: int32 }

Call As

game.take_technology_screenshot{ player=player }

Call Convention

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

remove_offline_players

LuaGameScript.remove_offline_players(players?: Array<PlayerIdentification>)

Call As

game.remove_offline_players()

Call Convention

Remove players who are currently not connected from the map.

Parameters

force_crc

LuaGameScript.force_crc()

Call As

game.force_crc()

Call Convention

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

LuaGameScript.create_force(force: string) -> LuaForce

Call As

game.create_force(force)

Call Convention

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

Returns

merge_forces

LuaGameScript.merge_forces(source: ForceID, destination: ForceID)

Call As

game.merge_forces(source, destination)

Call Convention

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

create_surface

LuaGameScript.create_surface(name: string, settings?: MapGenSettings) -> LuaSurface

Call As

game.create_surface(name, settings)

Call Convention

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

Returns

server_save

LuaGameScript.server_save(name?: string)

Call As

game.server_save()

Call Convention

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

Parameters

auto_save

LuaGameScript.auto_save(name?: string)

Call As

game.auto_save()

Call Convention

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

delete_surface

LuaGameScript.delete_surface(surface: SurfaceIdentification) -> boolean

Call As

game.delete_surface(surface)

Call Convention

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

Parameters

Returns

disable_replay

LuaGameScript.disable_replay()

Call As

game.disable_replay()

Call Convention

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

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

Call As

game.print(message, print_settings)

Call Convention

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

create_random_generator

LuaGameScript.create_random_generator(seed?: uint32) -> LuaRandomGenerator

Call As

game.create_random_generator()

Call Convention

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

Returns

play_sound

LuaGameScript.play_sound(sound_specification: PlaySoundSpecification)

Call As

game.play_sound(sound_specification)

Call Convention

Play a sound for every player in the game.

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

Parameters

kick_player

LuaGameScript.kick_player(player: PlayerIdentification, reason?: string)

Call As

game.kick_player(player, reason)

Call Convention

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

ban_player

LuaGameScript.ban_player(player: PlayerIdentification | string, reason?: string)

Call As

game.ban_player(player, reason)

Call Convention

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

unban_player

LuaGameScript.unban_player(player: PlayerIdentification | string)

Call As

game.unban_player(player)

Call Convention

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

purge_player

LuaGameScript.purge_player(player: PlayerIdentification)

Call As

game.purge_player(player)

Call Convention

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

Parameters

mute_player

LuaGameScript.mute_player(player: PlayerIdentification)

Call As

game.mute_player(player)

Call Convention

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

Parameters

unmute_player

LuaGameScript.unmute_player(player: PlayerIdentification)

Call As

game.unmute_player(player)

Call Convention

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

Parameters

is_multiplayer

LuaGameScript.is_multiplayer() -> boolean

Call As

game.is_multiplayer()

Call Convention

Whether the save is loaded as a multiplayer map.

Returns

get_map_exchange_string

LuaGameScript.get_map_exchange_string() -> string

Call As

game.get_map_exchange_string()

Call Convention

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

Returns

get_player

LuaGameScript.get_player(player: uint32 | string) -> LuaPlayer?

Call As

game.get_player(player)

Call Convention

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

Parameters

Returns

get_surface

LuaGameScript.get_surface(surface: uint32 | string) -> LuaSurface?

Call As

game.get_surface(surface)

Call Convention

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

This is a shortcut for LuaGameScript::surfaces.

Parameters

Returns

create_profiler

LuaGameScript.create_profiler(stopped?: boolean) -> LuaProfiler

Call As

game.create_profiler()

Call Convention

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

LuaProfiler cannot be serialized.

Parameters

Returns

create_inventory

LuaGameScript.create_inventory(size: uint16, gui_title?: LocalisedString) -> LuaInventory

Call As

game.create_inventory(size, gui_title)

Call Convention

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

Returns

get_script_inventories

LuaGameScript.get_script_inventories(mod?: string) -> Dict<string, Array<LuaInventory>>

Call As

game.get_script_inventories()

Call Convention

Gets the inventories created through LuaGameScript::create_inventory.

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

Parameters

Returns

reset_time_played

LuaGameScript.reset_time_played()

Call As

game.reset_time_played()

Call Convention

Resets the amount of time played for this map.

get_pollution_statistics

LuaGameScript.get_pollution_statistics(surface: SurfaceIdentification) -> LuaFlowStatistics

Call As

game.get_pollution_statistics(surface)

Call Convention

The pollution statistics for this the given surface.

Parameters

Returns

get_vehicles

LuaGameScript.get_vehicles{ unit_number?: uint32, force?: ForceID, surface?: SurfaceIdentification, type?: EntityID | Array<EntityID>, is_moving?: boolean, has_passenger?: boolean } -> Array<LuaEntity>

Call As

game.get_vehicles{ unit_number=unit_number }

Call Convention

Returns vehicles in game.

Parameters

Returns

get_entity_by_unit_number

LuaGameScript.get_entity_by_unit_number(unit_number: uint32) -> LuaEntity?

Call As

game.get_entity_by_unit_number(unit_number)

Call Convention

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

Returns