LuaGameScript - Runtime Docs

ClassLuaGameScript

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?=…, victorious_force?=…}		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.).
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?=…, 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{force?=…, path?=…, by_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. [...]
table_to_json(data)	→ string	Convert a table to a JSON string
Convert a table to a JSON string
json_to_table(json)	→ AnyBasic?	Convert a JSON string to a table.
Convert a JSON string to a table.
write_file(filename, data, append?, for_player?)		Write a file to the `script-output` folder, located in the game's user data directory. [...]
Write a file to the `script-output` folder, located in the game's user data directory. [...]
remove_path(path)		Remove a file or directory in the `script-output` folder, located in the game's user data directory. [...]
Remove a file or directory in 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)		Deletes the given surface and all entities on it.
Deletes the given surface and all entities on it.
disable_replay()		Disables replay saving for the current save file. [...]
Disables replay saving for the current save file. [...]
disable_tutorial_triggers()		Disables tutorial triggers, that unlock new tutorials and show notices about unlocked tutorials.
Disables tutorial triggers, that unlock new tutorials and show notices about unlocked tutorials.
direction_to_string(direction)	→ string	Converts the given direction into the string version of the direction.
Converts the given direction into the string version of the direction.
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. [...]
check_prototype_translations()		Goes over all items, entities, tiles, recipes, technologies among other things and logs if the locale is incorrect. [...]
Goes over all items, entities, tiles, recipes, technologies among other things and logs if the locale is incorrect. [...]
play_sound{path=…, position?=…, volume_modifier?=…, override_sound_type?=…}		Play a sound for every player in the game. [...]
Play a sound for every player in the game. [...]
is_valid_sound_path(sound_path)	→ boolean	Checks if the given SoundPath is valid.
Checks if the given SoundPath is valid.
is_valid_sprite_path(sprite_path)	→ boolean	Checks if the given SpritePath is valid and contains a loaded sprite. [...]
Checks if the given SpritePath is valid and contains a loaded sprite. [...]
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. [...]
count_pipe_groups()		Counts how many distinct groups of pipes exist in the world.
Counts how many distinct groups of pipes exist in the world.
is_multiplayer()	→ boolean	Whether the save is loaded as a multiplayer map.
Whether the save is loaded as a multiplayer map.
get_active_entities_count(surface?)	→ uint	Gets the number of entities that are active (updated each tick). [...]
Gets the number of entities that are active (updated each tick). [...]
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.
parse_map_exchange_string(map_exchange_string)	→ MapExchangeStringData	Convert a map exchange string to map gen settings and map settings.
Convert a map exchange string to map gen settings and map settings.
get_train_stops{name?=…, surface?=…, force?=…}	→ array[LuaEntity]	Gets train stops matching the given filters.
Gets train stops matching the given filters.
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. [...]
evaluate_expression(expression, variables?)	→ double	Evaluate an expression, substituting variables as provided. [...]
Evaluate an expression, substituting variables as provided. [...]
get_filtered_entity_prototypes(filters)	→ LuaCustomTable[string → LuaEntityPrototype]	Returns a dictionary of all LuaEntityPrototypes that fit the given filters. [...]
Returns a dictionary of all LuaEntityPrototypes that fit the given filters. [...]
get_filtered_item_prototypes(filters)	→ LuaCustomTable[string → LuaItemPrototype]	Returns a dictionary of all LuaItemPrototypes that fit the given filters. [...]
Returns a dictionary of all LuaItemPrototypes that fit the given filters. [...]
get_filtered_equipment_prototypes(filters)	→ LuaCustomTable[string → LuaEquipmentPrototype]	Returns a dictionary of all LuaEquipmentPrototypes that fit the given filters. [...]
Returns a dictionary of all LuaEquipmentPrototypes that fit the given filters. [...]
get_filtered_mod_setting_prototypes(filters)	→ LuaCustomTable[string → LuaModSettingPrototype]	Returns a dictionary of all LuaModSettingPrototypes that fit the given filters. [...]
Returns a dictionary of all LuaModSettingPrototypes that fit the given filters. [...]
get_filtered_achievement_prototypes(filters)	→ LuaCustomTable[string → LuaAchievementPrototype]	Returns a dictionary of all LuaAchievementPrototypes that fit the given filters. [...]
Returns a dictionary of all LuaAchievementPrototypes that fit the given filters. [...]
get_filtered_tile_prototypes(filters)	→ LuaCustomTable[string → LuaTilePrototype]	Returns a dictionary of all LuaTilePrototypes that fit the given filters. [...]
Returns a dictionary of all LuaTilePrototypes that fit the given filters. [...]
get_filtered_decorative_prototypes(filters)	→ LuaCustomTable[string → LuaDecorativePrototype]	Returns a dictionary of all LuaDecorativePrototypes that fit the given filters. [...]
Returns a dictionary of all LuaDecorativePrototypes that fit the given filters. [...]
get_filtered_fluid_prototypes(filters)	→ LuaCustomTable[string → LuaFluidPrototype]	Returns a dictionary of all LuaFluidPrototypes that fit the given filters. [...]
Returns a dictionary of all LuaFluidPrototypes that fit the given filters. [...]
get_filtered_recipe_prototypes(filters)	→ LuaCustomTable[string → LuaRecipePrototype]	Returns a dictionary of all LuaRecipePrototypes that fit the given filters. [...]
Returns a dictionary of all LuaRecipePrototypes that fit the given filters. [...]
get_filtered_technology_prototypes(filters)	→ LuaCustomTable[string → LuaTechnologyPrototype]	Returns a dictionary of all LuaTechnologyPrototypes that fit the given filters. [...]
Returns a dictionary of all LuaTechnologyPrototypes that fit the given filters. [...]
create_inventory(size)	→ 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.
encode_string(string)	→ string?	Deflates and base64 encodes the given string.
Deflates and base64 encodes the given string.
decode_string(string)	→ string?	Base64 decodes and inflates the given string.
Base64 decodes and inflates the given string.
get_train_by_id(train_id)	→ LuaTrain?	Searches for a train with given ID.
Searches for a train with given ID.
request_train_path{goals=…, in_chain_signal_section?=…, train?=…, type?=…, return_path?=…, from_front?=…, allow_path_within_segment_front?=…, from_back?=…, allow_path_within_segment_back?=…, search_direction?=…, steps_limit?=…}	→ TrainPathFinderPathResult or TrainPathAnyGoalResult or TrainPathAllGoalsResult	Direct access to Trains Pathfinder. [...]
Direct access to Trains Pathfinder. [...]
help()	→ string	All methods and properties that this object supports.
All methods and properties that this object supports.
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[uint 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[uint or string → LuaForce]	Get a table of all the forces that currently exist. [...]
Get a table of all the forces that currently exist. [...]
entity_prototypes [R]	:: LuaCustomTable[string → LuaEntityPrototype]	A dictionary containing every LuaEntityPrototype indexed by `name`.
A dictionary containing every LuaEntityPrototype indexed by `name`.
item_prototypes [R]	:: LuaCustomTable[string → LuaItemPrototype]	A dictionary containing every LuaItemPrototype indexed by `name`.
A dictionary containing every LuaItemPrototype indexed by `name`.
fluid_prototypes [R]	:: LuaCustomTable[string → LuaFluidPrototype]	A dictionary containing every LuaFluidPrototype indexed by `name`.
A dictionary containing every LuaFluidPrototype indexed by `name`.
tile_prototypes [R]	:: LuaCustomTable[string → LuaTilePrototype]	A dictionary containing every LuaTilePrototype indexed by `name`.
A dictionary containing every LuaTilePrototype indexed by `name`.
equipment_prototypes [R]	:: LuaCustomTable[string → LuaEquipmentPrototype]	A dictionary containing every LuaEquipmentPrototype indexed by `name`.
A dictionary containing every LuaEquipmentPrototype indexed by `name`.
damage_prototypes [R]	:: LuaCustomTable[string → LuaDamagePrototype]	A dictionary containing every LuaDamagePrototype indexed by `name`.
A dictionary containing every LuaDamagePrototype indexed by `name`.
virtual_signal_prototypes [R]	:: LuaCustomTable[string → LuaVirtualSignalPrototype]	A dictionary containing every LuaVirtualSignalPrototype indexed by `name`.
A dictionary containing every LuaVirtualSignalPrototype indexed by `name`.
equipment_grid_prototypes [R]	:: LuaCustomTable[string → LuaEquipmentGridPrototype]	A dictionary containing every LuaEquipmentGridPrototype indexed by `name`.
A dictionary containing every LuaEquipmentGridPrototype indexed by `name`.
recipe_prototypes [R]	:: LuaCustomTable[string → LuaRecipePrototype]	A dictionary containing every LuaRecipePrototype indexed by `name`.
A dictionary containing every LuaRecipePrototype indexed by `name`.
technology_prototypes [R]	:: LuaCustomTable[string → LuaTechnologyPrototype]	A dictionary containing every LuaTechnologyPrototype indexed by `name`.
A dictionary containing every LuaTechnologyPrototype indexed by `name`.
decorative_prototypes [R]	:: LuaCustomTable[string → LuaDecorativePrototype]	A dictionary containing every LuaDecorativePrototype indexed by `name`.
A dictionary containing every LuaDecorativePrototype indexed by `name`.
particle_prototypes [R]	:: LuaCustomTable[string → LuaParticlePrototype]	A dictionary containing every LuaParticlePrototype indexed by `name`.
A dictionary containing every LuaParticlePrototype indexed by `name`.
autoplace_control_prototypes [R]	:: LuaCustomTable[string → LuaAutoplaceControlPrototype]	A dictionary containing every LuaAutoplaceControlPrototype indexed by `name`.
A dictionary containing every LuaAutoplaceControlPrototype indexed by `name`.
noise_layer_prototypes [R]	:: LuaCustomTable[string → LuaNoiseLayerPrototype]	A dictionary containing every LuaNoiseLayerPrototype indexed by `name`.
A dictionary containing every LuaNoiseLayerPrototype indexed by `name`.
mod_setting_prototypes [R]	:: LuaCustomTable[string → LuaModSettingPrototype]	A dictionary containing every LuaModSettingPrototype indexed by `name`.
A dictionary containing every LuaModSettingPrototype indexed by `name`.
custom_input_prototypes [R]	:: LuaCustomTable[string → LuaCustomInputPrototype]	A dictionary containing every LuaCustomInputPrototype indexed by `name`.
A dictionary containing every LuaCustomInputPrototype indexed by `name`.
ammo_category_prototypes [R]	:: LuaCustomTable[string → LuaAmmoCategoryPrototype]	A dictionary containing every LuaAmmoCategoryPrototype indexed by `name`.
A dictionary containing every LuaAmmoCategoryPrototype indexed by `name`.
named_noise_expressions [R]	:: LuaCustomTable[string → LuaNamedNoiseExpression]	A dictionary containing every LuaNamedNoiseExpression indexed by `name`.
A dictionary containing every LuaNamedNoiseExpression indexed by `name`.
item_subgroup_prototypes [R]	:: LuaCustomTable[string → LuaGroup]	A dictionary containing every ItemSubgroup indexed by `name`.
A dictionary containing every ItemSubgroup indexed by `name`.
item_group_prototypes [R]	:: LuaCustomTable[string → LuaGroup]	A dictionary containing every ItemGroup indexed by `name`.
A dictionary containing every ItemGroup indexed by `name`.
fuel_category_prototypes [R]	:: LuaCustomTable[string → LuaFuelCategoryPrototype]	A dictionary containing every LuaFuelCategoryPrototype indexed by `name`.
A dictionary containing every LuaFuelCategoryPrototype indexed by `name`.
resource_category_prototypes [R]	:: LuaCustomTable[string → LuaResourceCategoryPrototype]	A dictionary containing every LuaResourceCategoryPrototype indexed by `name`.
A dictionary containing every LuaResourceCategoryPrototype indexed by `name`.
achievement_prototypes [R]	:: LuaCustomTable[string → LuaAchievementPrototype]	A dictionary containing every LuaAchievementPrototype indexed by `name`.
A dictionary containing every LuaAchievementPrototype indexed by `name`.
module_category_prototypes [R]	:: LuaCustomTable[string → LuaModuleCategoryPrototype]	A dictionary containing every LuaModuleCategoryPrototype indexed by `name`.
A dictionary containing every LuaModuleCategoryPrototype indexed by `name`.
equipment_category_prototypes [R]	:: LuaCustomTable[string → LuaEquipmentCategoryPrototype]	A dictionary containing every LuaEquipmentCategoryPrototype indexed by `name`.
A dictionary containing every LuaEquipmentCategoryPrototype indexed by `name`.
trivial_smoke_prototypes [R]	:: LuaCustomTable[string → LuaTrivialSmokePrototype]	A dictionary containing every LuaTrivialSmokePrototype indexed by `name`.
A dictionary containing every LuaTrivialSmokePrototype indexed by `name`.
shortcut_prototypes [R]	:: LuaCustomTable[string → LuaShortcutPrototype]	A dictionary containing every LuaShortcutPrototype indexed by `name`.
A dictionary containing every LuaShortcutPrototype indexed by `name`.
recipe_category_prototypes [R]	:: LuaCustomTable[string → LuaRecipeCategoryPrototype]	A dictionary containing every LuaRecipeCategoryPrototype indexed by `name`.
A dictionary containing every LuaRecipeCategoryPrototype indexed by `name`.
font_prototypes [R]	:: LuaCustomTable[string → LuaFontPrototype]	A dictionary containing every LuaFontPrototype indexed by `name`.
A dictionary containing every LuaFontPrototype indexed by `name`.
map_gen_presets [R]	:: LuaCustomTable[string → MapGenPreset]	A dictionary containing every MapGenPreset indexed by `name`. [...]
A dictionary containing every MapGenPreset indexed by `name`. [...]
console_command_used [R]	:: boolean	Whether a console command has been used.
Whether a console command has been used.
styles [R]	:: LuaCustomTable[string → string]	The styles that LuaGuiElement can use, indexed by `name`.
The styles that LuaGuiElement can use, indexed by `name`.
tick [R]	:: uint	Current map tick.
Current map tick.
ticks_played [R]	:: uint	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]	:: uint	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[uint or string → LuaSurface]	Get a table of all the surfaces that currently exist. [...]
Get a table of all the surfaces that currently exist. [...]
active_mods [R]	:: dictionary[string → string]	The active mods versions. [...]
The active mods versions. [...]
connected_players [R]	:: array[LuaPlayer]	The players that are currently online. [...]
The players that are currently online. [...]
permissions [R]	:: LuaPermissionGroups
backer_names [R]	:: LuaCustomTable[uint → 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. [...]
pollution_statistics [R]	:: LuaFlowStatistics	The pollution statistics for this map.
The pollution statistics for this map.
max_force_distraction_distance [R]	:: double
max_force_distraction_chunk_distance [R]	:: uint
max_electric_pole_supply_area_distance [R]	:: float
max_electric_pole_connection_distance [R]	:: double
max_beacon_supply_area_distance [R]	:: double
max_gate_activation_distance [R]	:: double
max_inserter_reach_distance [R]	:: double
max_pipe_to_ground_distance [R]	:: uint8
max_underground_belt_distance [R]	:: uint8

Methods

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

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?
victorious_force	:: ForceIdentification?

reset_game_state()

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

get_entity_by_tag(tag) → LuaEntity?

Gets an entity by its name tag. Entity name tags can 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?=…, 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`.
quality	:: int?	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	:: uint?	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{force?=…, path?=…, by_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:

force	:: ForceIdentification?	The force whose technology to screenshot. If not given, the `"player`" force is used.
The force whose technology to screenshot. If not given, the `"player`" force is used.
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"`.
by_player	:: PlayerIdentification?	If given, the screenshot will only be taken for this player.
If given, the screenshot will only be taken for this player.
selected_technology	:: TechnologyIdentification?	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	:: int?	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`.

table_to_json(data) → string

Convert a table to a JSON string

Parameters

data

:: table

json_to_table(json) → AnyBasic?

Convert a JSON string to a table.

Parameters

json	:: string	The string to convert.
The string to convert.

Return values

→ AnyBasic?

The returned object, or nil if the JSON string was invalid.

write_file(filename, data, append?, for_player?)

Write a file to the script-output folder, located in the game's user data directory. The name and file extension of the file can be specified via the filename parameter.

Parameters

filename	:: string	The name of the file. Providing a directory path (ex. `"save/here/example.txt"`) will create the necessary folder structure in `script-output`.
The name of the file. Providing a directory path (ex. `"save/here/example.txt"`) will create the necessary folder structure in `script-output`.
data	:: LocalisedString	The content to write to the file.
The content to write to the file.
append	:: boolean?	If `true`, `data` will be appended to the end of the file. Defaults to `false`, which will overwrite any pre-existing file with the new `data`.
If `true`, `data` will be appended to the end of the file. Defaults to `false`, which will overwrite any pre-existing file with the new `data`.
for_player	:: uint?	If given, the file will only be written for this `player_index`. Providing `0` will only write to the server's output if present.
If given, the file will only be written for this `player_index`. Providing `0` will only write to the server's output if present.

remove_path(path)

Remove a file or directory in the script-output folder, located in the game's user data directory. Can be used to remove files created by LuaGameScript::write_file.

Parameters

path	:: string	The path to the file or directory to remove, relative to `script-output`.
The path to the file or directory to remove, relative to `script-output`.

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	:: ForceIdentification	The force to remove.
The force to remove.
destination	:: ForceIdentification	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.
Save file name. If not specified, the currently running save is overwritten.

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)

Deletes the given surface and all entities on it.

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.

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.

disable_tutorial_triggers()

Disables tutorial triggers, that unlock new tutorials and show notices about unlocked tutorials.

direction_to_string(direction) → string

Converts the given direction into the string version of the direction.

Parameters

direction

:: defines.direction

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	:: Color or 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

:: uint?

check_prototype_translations()

Goes over all items, entities, tiles, recipes, technologies among other things and logs if the locale is incorrect.

Also prints true/false if called from the console.

play_sound{path=…, position?=…, volume_modifier?=…, override_sound_type?=…}

Play a sound for every player in the game.

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

Parameters

Table with the following fields:

path	:: SoundPath	The sound to play.
The sound to play.
position	:: MapPosition?	Where the sound should be played. If not given, it's played at the current position of each player.
Where the sound should be played. If not given, it's played at the current position of each player.
volume_modifier	:: double?	The volume of the sound to play. Must be between 0 and 1 inclusive.
The volume of the sound to play. Must be between 0 and 1 inclusive.
override_sound_type	:: SoundType?	The volume mixer to play the sound through. Defaults to the default mixer for the given sound type.
The volume mixer to play the sound through. Defaults to the default mixer for the given sound type.

is_valid_sound_path(sound_path) → boolean

Checks if the given SoundPath is valid.

Parameters

sound_path	:: SoundPath	Path to the sound.
Path to the sound.

is_valid_sprite_path(sprite_path) → boolean

Checks if the given SpritePath is valid and contains a loaded sprite. The existence of the image is not checked for paths of type file.

Parameters

sprite_path	:: SpritePath	Path to the image.
Path to the image.

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

count_pipe_groups()

Counts how many distinct groups of pipes exist in the world.

is_multiplayer() → boolean

Whether the save is loaded as a multiplayer map.

get_active_entities_count(surface?) → uint

Gets the number of entities that are active (updated each tick).

This is very expensive to determine.

Parameters

surface	:: SurfaceIdentification?	If given, only the entities active on this surface are counted.
If given, only the entities active on this surface are counted.

get_map_exchange_string() → string

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

parse_map_exchange_string(map_exchange_string) → MapExchangeStringData

Convert a map exchange string to map gen settings and map settings.

Parameters

map_exchange_string

:: string

get_train_stops{name?=…, surface?=…, force?=…} → array[LuaEntity]

Gets train stops matching the given filters.

Parameters

Table (optional) with the following fields:

name	:: string or array[string]?	The name(s) of the train stops. Not providing names will match any stop.
The name(s) of the train stops. Not providing names will match any stop.
surface	:: SurfaceIdentification?	The surface to search. Not providing a surface will match stops on any surface.
The surface to search. Not providing a surface will match stops on any surface.
force	:: ForceIdentification?	The force to search. Not providing a force will match stops in any force.
The force to search. Not providing a force will match stops in any force.

get_player(player) → LuaPlayer?

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

Parameters

player	:: uint 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	:: uint 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

evaluate_expression(expression, variables?) → double

Evaluate an expression, substituting variables as provided.

For details on the formula, see TechnologyPrototype::unit.

Parameters

expression	:: string	The expression to evaluate.
The expression to evaluate.
variables	:: dictionary[string → double]?	Variables to be substituted.
Variables to be substituted.

Example

-- Calculate the number of research units required to unlock mining productivity level 10
local formula = game.forces["player"].technologies["mining-productivity-4"].research_unit_count_formula
local units = game.evaluate_expression(formula, { L = 10, l = 10 })

get_filtered_entity_prototypes(filters) → LuaCustomTable[string → LuaEntityPrototype]

Returns a dictionary of all LuaEntityPrototypes that fit the given filters. The prototypes are indexed by name.

Parameters

filters

:: array[EntityPrototypeFilter]

Example

-- Get every entity prototype that can craft recipes involving fluids in the way some assembling machines can
local prototypes = game.get_filtered_entity_prototypes{{filter="crafting-category", crafting_category="crafting-with-fluid"}}

get_filtered_item_prototypes(filters) → LuaCustomTable[string → LuaItemPrototype]

Returns a dictionary of all LuaItemPrototypes that fit the given filters. The prototypes are indexed by name.

Parameters

filters

:: array[ItemPrototypeFilter]

Example

-- Get every item prototype that, when launched with a rocket, produces a result.
local prototypes = game.get_filtered_item_prototypes{{filter="has-rocket-launch-products"}}

get_filtered_equipment_prototypes(filters) → LuaCustomTable[string → LuaEquipmentPrototype]

Returns a dictionary of all LuaEquipmentPrototypes that fit the given filters. The prototypes are indexed by name.

Parameters

filters

:: array[EquipmentPrototypeFilter]

Example

-- Get every equipment prototype that functions as a battery.
local prototypes = game.get_filtered_equipment_prototypes{{filter="type", type="battery-equipment"}}

get_filtered_mod_setting_prototypes(filters) → LuaCustomTable[string → LuaModSettingPrototype]

Returns a dictionary of all LuaModSettingPrototypes that fit the given filters. The prototypes are indexed by name.

Parameters

filters

:: array[ModSettingPrototypeFilter]

Example

-- Get every mod setting prototype that belongs to the specified mod.
local prototypes = game.get_filtered_mod_setting_prototypes{{filter="mod", mod="space-exploration"}}

get_filtered_achievement_prototypes(filters) → LuaCustomTable[string → LuaAchievementPrototype]

Returns a dictionary of all LuaAchievementPrototypes that fit the given filters. The prototypes are indexed by name.

Parameters

filters

:: array[AchievementPrototypeFilter]

Example

-- Get every achievement prototype that is not allowed to be completed on the peaceful difficulty setting.
local prototypes = game.get_filtered_achievement_prototypes{{filter="allowed-without-fight", invert=true}}

get_filtered_tile_prototypes(filters) → LuaCustomTable[string → LuaTilePrototype]

Returns a dictionary of all LuaTilePrototypes that fit the given filters. The prototypes are indexed by name.

Parameters

filters

:: array[TilePrototypeFilter]

Example

-- Get every tile prototype that improves a player's walking speed by at least 50%.
local prototypes = game.get_filtered_tile_prototypes{{filter="walking-speed-modifier", comparison="≥", value=1.5}}

get_filtered_decorative_prototypes(filters) → LuaCustomTable[string → LuaDecorativePrototype]

Returns a dictionary of all LuaDecorativePrototypes that fit the given filters. The prototypes are indexed by name.

Parameters

filters

:: array[DecorativePrototypeFilter]

Example

-- Get every decorative prototype that is auto-placed.
local prototypes = game.get_filtered_decorative_prototypes{{filter="autoplace"}}

get_filtered_fluid_prototypes(filters) → LuaCustomTable[string → LuaFluidPrototype]

Returns a dictionary of all LuaFluidPrototypes that fit the given filters. The prototypes are indexed by name.

Parameters

filters

:: array[FluidPrototypeFilter]

Example

-- Get every fluid prototype that has a heat capacity of exactly `100`.
local prototypes = game.get_filtered_fluid_prototypes{{filter="heat-capacity", comparison="=", value=100}}

get_filtered_recipe_prototypes(filters) → LuaCustomTable[string → LuaRecipePrototype]

Returns a dictionary of all LuaRecipePrototypes that fit the given filters. The prototypes are indexed by name.

Parameters

filters

:: array[RecipePrototypeFilter]

Example

-- Get every recipe prototype that takes less than half a second to craft (at crafting speed `1`).
local prototypes = game.get_filtered_recipe_prototypes{{filter="energy", comparison="<", value=0.5}}

get_filtered_technology_prototypes(filters) → LuaCustomTable[string → LuaTechnologyPrototype]

Returns a dictionary of all LuaTechnologyPrototypes that fit the given filters. The prototypes are indexed by name.

Parameters

filters

:: array[TechnologyPrototypeFilter]

Example

-- Get every technology prototype that can be researched at the start of the game.
local prototypes = game.get_filtered_technology_prototypes{{filter="has-prerequisites", invert=true}}

create_inventory(size) → 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.

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.

encode_string(string) → string?

Deflates and base64 encodes the given string.

Parameters

string	:: string	The string to encode.
The string to encode.

Return values

→ string?

The encoded string or nil if the encode failed.

decode_string(string) → string?

Base64 decodes and inflates the given string.

Parameters

string	:: string	The string to decode.
The string to decode.

Return values

→ string?

The decoded string or nil if the decode failed.

get_train_by_id(train_id) → LuaTrain?

Searches for a train with given ID.

Parameters

train_id	:: uint	Train ID to search
Train ID to search

Return values

→ LuaTrain?

Train if found

request_train_path{goals=…, in_chain_signal_section?=…, train?=…, type?=…, return_path?=…, from_front?=…, allow_path_within_segment_front?=…, from_back?=…, allow_path_within_segment_back?=…, search_direction?=…, steps_limit?=…} → TrainPathFinderPathResult or TrainPathAnyGoalResult or TrainPathAllGoalsResult

Direct access to Trains Pathfinder. Allows to search rail paths or querying which stops are accessible

Parameters

Table with the following fields:

goals	:: array[TrainStopGoal or RailEnd]
in_chain_signal_section	:: boolean?	Defaults to `false`. If set to true, pathfinder will not return a path that cannot have its beginning immediately reserved. A path that cannot have its beginning immediately reserved could cause a train to stop inside of an intersection.
Defaults to `false`. If set to true, pathfinder will not return a path that cannot have its beginning immediately reserved. A path that cannot have its beginning immediately reserved could cause a train to stop inside of an intersection.
train	:: LuaTrain?	Mandatory if `from_front` and `from_back` are not provided, optional otherwise. Selects a context for the pathfinder to decide which train to exclude from penalties and which signals are considered possible to reacquire. If `from_front` and `from_back` are not provided, then it is also used to collect front and back ends for the search
Mandatory if `from_front` and `from_back` are not provided, optional otherwise. Selects a context for the pathfinder to decide which train to exclude from penalties and which signals are considered possible to reacquire. If `from_front` and `from_back` are not provided, then it is also used to collect front and back ends for the search
type	:: TrainPathRequestType?	Request type. Determines the return type of the method. Defaults to `"path"`.
Request type. Determines the return type of the method. Defaults to `"path"`.
return_path	:: boolean?	Only relevant if request type is `"path"`. Returning a full path is expensive due to multiple LuaEntity created. In order for path to be returned, true must be provided here. Defaults to false in which case a path will not be provided.
Only relevant if request type is `"path"`. Returning a full path is expensive due to multiple LuaEntity created. In order for path to be returned, true must be provided here. Defaults to false in which case a path will not be provided.
from_front	:: RailEnd?	Manually provided starting front of the train.
Manually provided starting front of the train.
allow_path_within_segment_front	:: boolean?	Only relevant if `from_front` is given. Defaults to `true`. Providing false will cause the pathfinder to reject a path that starts on front and ends within the same segment as the path would be too short to provide correct alignment with a goal.
Only relevant if `from_front` is given. Defaults to `true`. Providing false will cause the pathfinder to reject a path that starts on front and ends within the same segment as the path would be too short to provide correct alignment with a goal.
from_back	:: RailEnd?	Manually provided starting back of the train.
Manually provided starting back of the train.
allow_path_within_segment_back	:: boolean?	Only relevant if `from_back` is given. Defaults to `true`. Providing false will cause the pathfinder to reject a path that starts on back and ends within the same segment as the path would be too short to provide correct alignment with a goal.
Only relevant if `from_back` is given. Defaults to `true`. Providing false will cause the pathfinder to reject a path that starts on back and ends within the same segment as the path would be too short to provide correct alignment with a goal.
search_direction	:: `"respect-movement-direction"` or `"any-direction-with-locomotives"`?	Only relevant if none of `from_front`/`from_back` was provided in which case `from_front` and `from_back` are deduced from the train. Selects which train ends should be considered as starts. Defaults to `"any-direction-with-locomotives"`.
Only relevant if none of `from_front`/`from_back` was provided in which case `from_front` and `from_back` are deduced from the train. Selects which train ends should be considered as starts. Defaults to `"any-direction-with-locomotives"`.
steps_limit	:: uint?	Maximum amount of steps pathfinder is allowed to perform.
Maximum amount of steps pathfinder is allowed to perform.

Return values

→ TrainPathFinderPathResult or TrainPathAnyGoalResult or TrainPathAllGoalsResult

The type of the returned value depends on type.

help() → string

All methods and properties that this object supports.

Attributes

object_name :: stringRead

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 :: LuaPlayer? Read

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 :: LuaCustomTable[uint or string → LuaPlayer] Read

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 only iterate the array part of the table. 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 :: MapSettingsRead

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 :: DifficultySettingsRead

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. This is however not recommended as different difficulties can have differing technology and recipe trees, which can cause problems for players.

Example

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

difficulty :: defines.difficultyRead

Current scenario difficulty.

forces :: LuaCustomTable[uint or string → LuaForce] Read

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.

entity_prototypes :: LuaCustomTable[string → LuaEntityPrototype] Read

A dictionary containing every LuaEntityPrototype indexed by name.

item_prototypes :: LuaCustomTable[string → LuaItemPrototype] Read

A dictionary containing every LuaItemPrototype indexed by name.

fluid_prototypes :: LuaCustomTable[string → LuaFluidPrototype] Read

A dictionary containing every LuaFluidPrototype indexed by name.

tile_prototypes :: LuaCustomTable[string → LuaTilePrototype] Read

A dictionary containing every LuaTilePrototype indexed by name.

equipment_prototypes :: LuaCustomTable[string → LuaEquipmentPrototype] Read

A dictionary containing every LuaEquipmentPrototype indexed by name.

damage_prototypes :: LuaCustomTable[string → LuaDamagePrototype] Read

A dictionary containing every LuaDamagePrototype indexed by name.

virtual_signal_prototypes :: LuaCustomTable[string → LuaVirtualSignalPrototype] Read

A dictionary containing every LuaVirtualSignalPrototype indexed by name.

equipment_grid_prototypes :: LuaCustomTable[string → LuaEquipmentGridPrototype] Read

A dictionary containing every LuaEquipmentGridPrototype indexed by name.

recipe_prototypes :: LuaCustomTable[string → LuaRecipePrototype] Read

A dictionary containing every LuaRecipePrototype indexed by name.

technology_prototypes :: LuaCustomTable[string → LuaTechnologyPrototype] Read

A dictionary containing every LuaTechnologyPrototype indexed by name.

decorative_prototypes :: LuaCustomTable[string → LuaDecorativePrototype] Read

A dictionary containing every LuaDecorativePrototype indexed by name.

particle_prototypes :: LuaCustomTable[string → LuaParticlePrototype] Read

A dictionary containing every LuaParticlePrototype indexed by name.

autoplace_control_prototypes :: LuaCustomTable[string → LuaAutoplaceControlPrototype] Read

A dictionary containing every LuaAutoplaceControlPrototype indexed by name.

noise_layer_prototypes :: LuaCustomTable[string → LuaNoiseLayerPrototype] Read

A dictionary containing every LuaNoiseLayerPrototype indexed by name.

mod_setting_prototypes :: LuaCustomTable[string → LuaModSettingPrototype] Read

A dictionary containing every LuaModSettingPrototype indexed by name.

custom_input_prototypes :: LuaCustomTable[string → LuaCustomInputPrototype] Read

A dictionary containing every LuaCustomInputPrototype indexed by name.

ammo_category_prototypes :: LuaCustomTable[string → LuaAmmoCategoryPrototype] Read

A dictionary containing every LuaAmmoCategoryPrototype indexed by name.

named_noise_expressions :: LuaCustomTable[string → LuaNamedNoiseExpression] Read

A dictionary containing every LuaNamedNoiseExpression indexed by name.

item_subgroup_prototypes :: LuaCustomTable[string → LuaGroup] Read

A dictionary containing every ItemSubgroup indexed by name.

item_group_prototypes :: LuaCustomTable[string → LuaGroup] Read

A dictionary containing every ItemGroup indexed by name.

fuel_category_prototypes :: LuaCustomTable[string → LuaFuelCategoryPrototype] Read

A dictionary containing every LuaFuelCategoryPrototype indexed by name.

resource_category_prototypes :: LuaCustomTable[string → LuaResourceCategoryPrototype] Read

A dictionary containing every LuaResourceCategoryPrototype indexed by name.

achievement_prototypes :: LuaCustomTable[string → LuaAchievementPrototype] Read

A dictionary containing every LuaAchievementPrototype indexed by name.

module_category_prototypes :: LuaCustomTable[string → LuaModuleCategoryPrototype] Read

A dictionary containing every LuaModuleCategoryPrototype indexed by name.

equipment_category_prototypes :: LuaCustomTable[string → LuaEquipmentCategoryPrototype] Read

A dictionary containing every LuaEquipmentCategoryPrototype indexed by name.

trivial_smoke_prototypes :: LuaCustomTable[string → LuaTrivialSmokePrototype] Read

A dictionary containing every LuaTrivialSmokePrototype indexed by name.

shortcut_prototypes :: LuaCustomTable[string → LuaShortcutPrototype] Read

A dictionary containing every LuaShortcutPrototype indexed by name.

recipe_category_prototypes :: LuaCustomTable[string → LuaRecipeCategoryPrototype] Read

A dictionary containing every LuaRecipeCategoryPrototype indexed by name.

font_prototypes :: LuaCustomTable[string → LuaFontPrototype] Read

A dictionary containing every LuaFontPrototype indexed by name.

map_gen_presets :: LuaCustomTable[string → MapGenPreset] Read

A dictionary containing every MapGenPreset indexed by name.

A MapGenPreset is an exact copy of the prototype table provided from the data stage.

console_command_used :: booleanRead

Whether a console command has been used.

styles :: LuaCustomTable[string → string] Read

The styles that LuaGuiElement can use, indexed by name.

tick :: uintRead

Current map tick.

ticks_played :: uintRead

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 :: booleanRead/Write

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

ticks_to_run :: uintRead/Write

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 :: booleanRead

True while the victory screen is shown.

finished_but_continuing :: booleanRead

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

speed :: floatRead/Write

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

surfaces :: LuaCustomTable[uint or string → LuaSurface] Read

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.

active_mods :: dictionary[string → string] Read

The active mods versions. The keys are mod names, the values are the versions.

Example

-- This will print the names and versions of active mods to player p's console.
for name, version in pairs(game.active_mods) do
  p.print(name .. " version " .. version)
end

connected_players :: array[LuaPlayer] Read

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 :: LuaPermissionGroupsRead

backer_names :: LuaCustomTable[uint → string] Read

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 :: MapGenSettingsRead

The default map gen settings for this save.

enemy_has_vision_on_land_mines :: booleanRead/Write

Determines if enemy land mines are completely invisible or not.

autosave_enabled :: booleanRead/Write

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

draw_resource_selection :: booleanRead/Write

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

Factorio Runtime DocsVersion 1.1.110

ClassLuaGameScript

Members

Methods

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

Parameters

reset_game_state()

get_entity_by_tag(tag) → LuaEntity?

Parameters

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

Parameters

is_demo() → boolean

reload_script()

reload_mods()

save_atlas()

check_consistency()

regenerate_entity(entities)

Parameters

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

Parameters

set_wait_for_screenshots_to_finish()

take_technology_screenshot{force?=…, path?=…, by_player?=…, selected_technology?=…, skip_disabled?=…, quality?=…}

Parameters

table_to_json(data) → string

Parameters

json_to_table(json) → AnyBasic?

Parameters

Return values

write_file(filename, data, append?, for_player?)

Parameters

remove_path(path)

Parameters

remove_offline_players(players?)

Parameters

Raised events

force_crc()

create_force(force) → LuaForce

Parameters

Return values

Raised events

merge_forces(source, destination)

Parameters

Raised events

create_surface(name, settings?) → LuaSurface

Parameters

Return values

Raised events

server_save(name?)

Parameters

auto_save(name?)

Parameters

delete_surface(surface)

Parameters

Raised events

disable_replay()

disable_tutorial_triggers()

direction_to_string(direction) → string

Parameters

print(message, print_settings?)

Parameters

create_random_generator(seed?) → LuaRandomGenerator

Parameters

check_prototype_translations()

play_sound{path=…, position?=…, volume_modifier?=…, override_sound_type?=…}

Parameters

is_valid_sound_path(sound_path) → boolean

Parameters

is_valid_sprite_path(sprite_path) → boolean

Parameters

kick_player(player, reason?)

Parameters

Raised events

ban_player(player, reason?)

Parameters

Raised events

unban_player(player)

Parameters

Raised events

purge_player(player)

Parameters

Factorio Runtime Docs Version 1.1.110