Factorio » Classes » LuaGameScriptFactorio 1.1.39

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.

class LuaGameScript - sort
set_game_state{game_finished = …, player_won = …, next_level = …, can_continue = …, victorious_force = …} Set scenario state.
get_entity_by_tag(tag) → LuaEntity
show_message_dialog{text = …, image = …, point_to = …, style = …, wrapper_frame_style = …} Show an in-game message dialog.
is_demo() → boolean Is this the demo version of Factorio?
reload_script() Forces a reload of the scenario script from the original scenario location.
reload_mods() Forces a reload of all mods.
save_atlas() Saves the current configuration of Atlas to a file.
check_consistency() Run internal consistency checks.
regenerate_entity(entities) 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 and save it to a file.
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 = …}
table_to_json(data) → string Convert a table to a JSON string
json_to_table(json) → AnyBasic Convert a JSON string to a table.
write_file(filename, data, append, for_player) Write a string to a file.
remove_path(path) Remove file or directory.
remove_offline_players(players) Remove players who are currently not connected from the map.
force_crc() Force a CRC check.
create_force(force) → LuaForce Create a new force.
merge_forces(source, destination) Marks two forces to be merge together.
create_surface(name, settings) → LuaSurface Create a new surface
server_save(name) Instruct the server to save the map.
auto_save(name) Instruct the game to perform an auto-save.
delete_surface(surface) Deletes the given surface and all entities on it.
disable_replay() Disables replay saving for the current save file.
disable_tutorial_triggers() Disables tutorial triggers, that unlock new tutorials and show notices about unlocked tutorials.
direction_to_string(direction) Converts the given direction into the string version of the direction.
print(message, color) 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.
check_prototype_translations() 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.
is_valid_sound_path(sound_path) → boolean 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.
kick_player(player, reason) Kicks the given player from this multiplayer game.
ban_player(player, reason) Bans the given player from this multiplayer game.
unban_player(player) Unbans the given player from this multiplayer game.
purge_player(player) Purges the given players messages from the game.
mute_player(player) Mutes the given player.
unmute_player(player) Unmutes the given player.
count_pipe_groups() Counts how many distinct groups of pipes exist in the world.
is_multiplayer() → boolean Is the map loaded is multiplayer?
get_active_entities_count(surface) → uint 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.
parse_map_exchange_string(map_exchange_string) → MapExchangeStringData 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.
get_player(player) → LuaPlayer 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.
create_profiler(stopped) → LuaProfiler Creates a LuaProfiler, which is used for measuring script performance.
evaluate_expression(expression, variables) → double 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.
get_filtered_item_prototypes(filters) → LuaCustomTable[string → LuaItemPrototype] 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.
get_filtered_mod_setting_prototypes(filters) → LuaCustomTable[string → LuaModSettingPrototype] 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.
get_filtered_tile_prototypes(filters) → LuaCustomTable[string → LuaTilePrototype] 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.
get_filtered_fluid_prototypes(filters) → LuaCustomTable[string → LuaFluidPrototype] 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.
get_filtered_technology_prototypes(filters) → LuaCustomTable[string → LuaTechnologyPrototype] 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.
get_script_inventories(mod) → dictionary[string → array[LuaInventory]] Gets the inventories created through LuaGameScript::create_inventory
reset_time_played() Resets the amount of time played for this map.
encode_string(string) → string Deflates and base64 encodes the given string.
decode_string(string) → string Base64 decodes and inflates the given string.
object_name :: string [R] This object's name.
player :: LuaPlayer [R] The player typing at the console - nil in all other instances.
players :: LuaCustomTable[uint or string → LuaPlayer] [R] Get a table of all the players that currently exist.
map_settings :: MapSettings [R]
difficulty_settings :: DifficultySettings [R] The currently active set of difficulty settings.
difficulty :: defines.difficulty [R] Current scenario difficulty.
forces :: LuaCustomTable[uint or string → LuaForce] [R] Get a table of all the forces that currently exist.
entity_prototypes :: LuaCustomTable[string → LuaEntityPrototype] [R] A dictionary containing every LuaEntityPrototype indexed by name.
item_prototypes :: LuaCustomTable[string → LuaItemPrototype] [R] A dictionary containing every LuaItemPrototype indexed by name.
fluid_prototypes :: LuaCustomTable[string → LuaFluidPrototype] [R] A dictionary containing every LuaFluidPrototype indexed by name.
tile_prototypes :: LuaCustomTable[string → LuaTilePrototype] [R] A dictionary containing every LuaTilePrototype indexed by name.
equipment_prototypes :: LuaCustomTable[string → LuaEquipmentPrototype] [R] A dictionary containing every LuaEquipmentPrototype indexed by name.
damage_prototypes :: LuaCustomTable[string → LuaDamagePrototype] [R] A dictionary containing every LuaDamagePrototype indexed by name.
virtual_signal_prototypes :: LuaCustomTable[string → LuaVirtualSignalPrototype] [R] A dictionary containing every LuaVirtualSignalPrototype indexed by name.
equipment_grid_prototypes :: LuaCustomTable[string → LuaEquipmentGridPrototype] [R] A dictionary containing every LuaEquipmentGridPrototype indexed by name.
recipe_prototypes :: LuaCustomTable[string → LuaRecipePrototype] [R] A dictionary containing every LuaRecipePrototype indexed by name.
technology_prototypes :: LuaCustomTable[string → LuaTechnologyPrototype] [R] A dictionary containing every LuaTechnologyPrototype indexed by name.
decorative_prototypes :: LuaCustomTable[string → LuaDecorativePrototype] [R] A dictionary containing every LuaDecorativePrototype indexed by name.
particle_prototypes :: LuaCustomTable[string → LuaParticlePrototype] [R] A dictionary containing every LuaParticlePrototype indexed by name.
autoplace_control_prototypes :: LuaCustomTable[string → LuaAutoplaceControlPrototype] [R] A dictionary containing every LuaAutoplaceControlPrototype indexed by name.
noise_layer_prototypes :: LuaCustomTable[string → LuaNoiseLayerPrototype] [R] A dictionary containing every LuaNoiseLayerPrototype indexed by name.
mod_setting_prototypes :: LuaCustomTable[string → LuaModSettingPrototype] [R] A dictionary containing every LuaModSettingPrototype indexed by name.
custom_input_prototypes :: LuaCustomTable[string → LuaCustomInputPrototype] [R] A dictionary containing every LuaCustomInputPrototype indexed by name.
ammo_category_prototypes :: LuaCustomTable[string → LuaAmmoCategoryPrototype] [R] A dictionary containing every LuaAmmoCategoryPrototype indexed by name.
named_noise_expressions :: LuaCustomTable[string → LuaNamedNoiseExpression] [R] A dictionary containing every LuaNamedNoiseExpression indexed by name.
item_subgroup_prototypes :: LuaCustomTable[string → LuaGroup] [R] A dictionary containing every ItemSubgroup indexed by name.
item_group_prototypes :: LuaCustomTable[string → LuaGroup] [R] A dictionary containing every ItemGroup indexed by name.
fuel_category_prototypes :: LuaCustomTable[string → LuaFuelCategoryPrototype] [R] A dictionary containing every LuaFuelCategoryPrototype indexed by name.
resource_category_prototypes :: LuaCustomTable[string → LuaResourceCategoryPrototype] [R] A dictionary containing every LuaResourceCategoryPrototype indexed by name.
achievement_prototypes :: LuaCustomTable[string → LuaAchievementPrototype] [R] A dictionary containing every LuaAchievementPrototype indexed by name.
module_category_prototypes :: LuaCustomTable[string → LuaModuleCategoryPrototype] [R] A dictionary containing every LuaModuleCategoryPrototype indexed by name.
equipment_category_prototypes :: LuaCustomTable[string → LuaEquipmentCategoryPrototype] [R] A dictionary containing every LuaEquipmentCategoryPrototype indexed by name.
trivial_smoke_prototypes :: LuaCustomTable[string → LuaTrivialSmokePrototype] [R] A dictionary containing every LuaTrivialSmokePrototype indexed by name.
shortcut_prototypes :: LuaCustomTable[string → LuaShortcutPrototype] [R] A dictionary containing every LuaShortcutPrototype indexed by name.
recipe_category_prototypes :: LuaCustomTable[string → LuaRecipeCategoryPrototype] [R] A dictionary containing every LuaRecipeCategoryPrototype indexed by name.
font_prototypes :: LuaCustomTable[string → LuaFontPrototype] [R] A dictionary containing every LuaFontPrototype indexed by name.
map_gen_presets :: LuaCustomTable[string → MapGenPreset] [R] A dictionary containing every MapGenPreset indexed by name.
styles :: LuaCustomTable[string → string] [R] The styles that LuaGuiElement can use, indexed by name.
tick :: uint [R] Current map tick.
ticks_played :: uint [R] The number of ticks since this game was 'created'.
tick_paused :: boolean [RW] If the tick has been paused.
ticks_to_run :: uint [RW] The number of ticks to be run while the tick is paused.
finished :: boolean [R] Is the scenario finished?
speed :: float [RW] Speed to update the map at.
surfaces :: LuaCustomTable[uint or string → LuaSurface] [R] Get a table of all the surfaces that currently exist.
active_mods :: dictionary[string → string] [R] The active mods versions.
connected_players :: array[LuaPlayer] [R] The players that are currently online.
permissions :: LuaPermissionGroups [R]
backer_names :: LuaCustomTable[uint → string] [R] Array of the names of all the backers that supported the game development early on.
default_map_gen_settings :: MapGenSettings [R] The default map gen settings for this save.
enemy_has_vision_on_land_mines :: boolean [RW] Determines if enemy land mines are completely invisible or not.
autosave_enabled :: boolean [RW] True by default.
draw_resource_selection :: boolean [RW] True by default.
pollution_statistics :: LuaFlowStatistics [R] The pollution statistics for this map.
max_force_distraction_distance :: double [R]
max_force_distraction_chunk_distance :: uint [R]
max_electric_pole_supply_area_distance :: float [R]
max_electric_pole_connection_distance :: double [R]
max_beacon_supply_area_distance :: double [R]
max_gate_activation_distance :: double [R]
max_inserter_reach_distance :: double [R]
max_pipe_to_ground_distance :: uint8 [R]
max_underground_belt_distance :: uint8 [R]
set_game_state{game_finished = …, player_won = …, next_level = …, can_continue = …, victorious_force = …}

Set scenario state.

Parameters
Table with the following fields:
get_entity_by_tag(tag) → LuaEntity

Parameters
tag :: string
show_message_dialog{text = …, image = …, point_to = …, style = …, wrapper_frame_style = …}

Show an in-game message dialog.

Parameters
Table with the following fields:
  • text :: LocalisedString: What the dialog should say
  • image :: string (optional): Path to an image to show on the dialog
  • point_to :: GuiArrowSpecification (optional): 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 (optional): The gui style to use for this speech bubble. Must be of type speech_bubble.
  • wrapper_frame_style :: string (optional): Must be of type flow_style.
Note: Can only be used when the map contains exactly one player.
is_demo() → boolean

Is this the demo version of Factorio?

reload_script()

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

Note: This disables the replay if replay is enabled.
reload_mods()

Forces a reload of all mods.

Note: This will act like saving and loading from the mod(s) perspective.
Note: This will do nothing if run in multiplayer.
Note: 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.

Note: Exists mainly for debugging reasons.
check_consistency()

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

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

Parameters
entities :: string or array[string]: Prototype names of entity or entities to autoplace.
Note: All specified entity prototypes must be autoplacable.
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 and save it to a file.

Parameters
Table with the following fields:
  • player :: PlayerIdentification (optional)
  • by_player :: PlayerIdentification (optional): If defined, the screenshot will only be taken for this player.
  • surface :: SurfaceIdentification (optional): If defined, the screenshot will be taken on this surface.
  • position :: Position (optional): If defined, the screenshot will be centered on this position.
  • resolution :: Position (optional): Maximum allowed resolution is 16384x16384 (resp. 8192x8192 when anti_alias is true), but maximum recommended resolution is 4096x4096 (resp. 2048x2048).
  • zoom :: double (optional)
  • path :: string (optional): Path to save the screenshot in
  • show_gui :: boolean (optional): Include game GUI in the screenshot?
  • show_entity_info :: boolean (optional): Include entity info (alt-mode)?
  • show_cursor_building_preview :: boolean (optional): When true, and player is specified, building preview for item in player's cursor will be rendered also.
  • anti_alias :: boolean (optional): Render in double resolution and scale down (including GUI)?
  • quality :: int (optional): The render quality if using jpg format (0-100 inclusive).
  • allow_in_replay :: boolean (optional): If true, the screenshot will be saved even during replay playback, otherwise this function call does nothing in replays.
  • daytime :: double (optional): Overrides current surface daytime for duration of screenshot rendering.
  • water_tick :: uint (optional): Overrides tick of water animation (if animated water is enabled).
  • force_render :: boolean (optional): Screenshot requests are processed in between update and render. The game may skip rendering (drop frames) if previous frame has not finished rendering or the game simulation starts to fall under 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.
Note: If Factorio is running headless, this function will do nothing.
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 = …}

Parameters
Table with the following fields:
  • force :: ForceIdentification (optional): The force to use. If not given the "player" force is used.
  • path :: string (optional): Path to save the screenshot in.
  • by_player :: PlayerIdentification (optional): If defined, the screenshot will only be taken for this player.
  • selected_technology :: TechnologyIdentification (optional): The technology to highlight.
  • skip_disabled :: boolean (optional): If true, disabled technologies will be skipped. Their successors will be attached to the disabled technology's parents. Defaults to false.
  • quality :: int (optional): The render quality if using jpg format (0-100 inclusive).
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.
Return value
The returned object, or nil if the json was invalid.
write_file(filename, data, append, for_player)

Write a string to a file.

Parameters
filename :: string: Path to the file to write to.
data :: LocalisedString: File content
append :: boolean (optional): When true, this will append to the end of the file. Defaults to false, which will overwrite any pre-existing file with the new data.
for_player :: uint (optional): If given, the file will only be written for this player_index. 0 means only the server if one exists.
remove_path(path)

Remove file or directory. Given path is taken relative to the script output directory. Can be used to remove files created by LuaGameScript::write_file.

Parameters
path :: string: Path to remove, relative to the script output directory
remove_offline_players(players)

Remove players who are currently not connected from the map.

Parameters
players :: array[LuaPlayer or string] (optional): List of players to remove. If not specified, remove all offline players.
force_crc()

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

create_force(force) → LuaForce

Create a new force.

Parameters
force :: string: Name of the new force
Return value
The force that was just created
Note: 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.
Note: Force names must be unique.
merge_forces(source, destination)

Marks two forces to be merge together. All entities in the source force will be reassigned to the target force. The source force will then be destroyed.

Parameters
source :: ForceIdentification: The force to remove
destination :: ForceIdentification: The force to reassign all entities to
Note: The three built-in forces -- player, enemy and neutral -- can't be destroyed. I.e. they can't be used as the source argument to this function.
Note: The source force is not merged until the end of the current tick or if called during the on_forces_merging event or on_forces_merged event the end of the next tick.
create_surface(name, settings) → LuaSurface

Create a new surface

Parameters
name :: string: Name of the new surface
settings :: MapGenSettings (optional): Map generation settings
Return value
The surface that was just created
Note: The game currently supports a maximum of 4,294,967,295 surfaces, including the default surface.
Note: Surface names must be unique
server_save(name)

Instruct the server to save the map.

Parameters
name :: string (optional): Save name. If not specified, writes into the currently-running save.
auto_save(name)

Instruct the game to perform an auto-save.

Parameters
name :: string (optional): The autosave name if any. Saves will be named _autosave-*name* when provided.
Note: Only the server will save in multiplayer. In single player a standard auto-save is triggered.
delete_surface(surface)

Deletes the given surface and all entities on it.

Parameters
surface :: string or LuaSurface: The surface to be deleted. Currently the primary surface (1, 'nauvis') cannot be deleted.
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)

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

Parameters
direction :: defines.direction
print(message, color)

Print text to the chat console all players.

Parameters
message :: LocalisedString
color :: Color (optional)
Note: Messages that are identical to a message sent in the last 60 ticks are not printed again.
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.

Parameters
seed :: uint (optional)
Note: *Make sure* you actually want to use this over math.random(...) as this provides entirely different functionality over math.random(...).
check_prototype_translations()

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

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

Parameters
Table with the following fields:
  • path :: SoundPath: The sound to play.
  • position :: Position (optional): Where the sound should be played. If not given, it's played at the current position of each player.
  • volume_modifier :: double (optional): The volume of the sound to play. Must be between 0 and 1 inclusive.
  • override_sound_type :: SoundType (optional): 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.
is_valid_sprite_path(sprite_path) → boolean

Checks if the given SpritePath is valid and contains a loaded sprite.

Parameters
sprite_path :: SpritePath: Path to the image.
Note: The existence of the image is not checked for paths of type file.
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.
reason :: LocalisedString (optional): The reason given if any.
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.
reason :: LocalisedString (optional): The reason given if any.
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.
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.
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.
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.
count_pipe_groups()

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

is_multiplayer() → boolean

Is the map loaded is multiplayer?

get_active_entities_count(surface) → uint

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

Parameters
surface :: SurfaceIdentification (optional): If give, only the entities active on this surface are counted.
Note: This is very expensive to calculate.
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:
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.
Note: This is a shortcut for game.players[...]
get_surface(surface) → LuaSurface

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

Parameters
surface :: uint or string: The surface index or name.
Note: This is a shortcut for game.surfaces[...]
create_profiler(stopped) → LuaProfiler

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

Parameters
stopped :: boolean (optional): Create the timer stopped
Note: LuaProfiler cannot be serialized.
evaluate_expression(expression, variables) → double

Evaluate an expression, substituting variables as provided. For details on the formula, see the relevant page on the Factorio wiki.

Parameters
expression :: string: The expression to evaluate.
variables :: dictionary[string → double] (optional): 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.

Parameters
size :: uint16: The number of slots the inventory initially has.
Note: Make sure to destroy it when you are done with it with LuaInventory::destroy.
get_script_inventories(mod) → dictionary[string → array[LuaInventory]]

Gets the inventories created through LuaGameScript::create_inventory

Parameters
mod :: string (optional): The mod who's inventories to get. If not provided all inventories are returned.
Return value
A mapping of mod name to array of inventories owned by that mod.
Note: Inventories created through console commands will be owned by "core".
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.
Return value
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.
Return value
The decoded string or nil if the decode failed.
object_name :: string [Read-only]

This object's name.

player :: LuaPlayer [Read-only]

The player typing at the console - nil in all other instances. See LuaGameScript::players for accessing all players.

players :: LuaCustomTable[uint or string → LuaPlayer] [Read-only]

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.

map_settings :: MapSettings [Read-only]

difficulty_settings :: DifficultySettings [Read-only]

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.difficulty [Read-only]

Current scenario difficulty.

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

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 only iterate the array part of the table. Iterating with ipairs() will not work at all.

entity_prototypes :: LuaCustomTable[string → LuaEntityPrototype] [Read-only]

A dictionary containing every LuaEntityPrototype indexed by name.

item_prototypes :: LuaCustomTable[string → LuaItemPrototype] [Read-only]

A dictionary containing every LuaItemPrototype indexed by name.

fluid_prototypes :: LuaCustomTable[string → LuaFluidPrototype] [Read-only]

A dictionary containing every LuaFluidPrototype indexed by name.

tile_prototypes :: LuaCustomTable[string → LuaTilePrototype] [Read-only]

A dictionary containing every LuaTilePrototype indexed by name.

equipment_prototypes :: LuaCustomTable[string → LuaEquipmentPrototype] [Read-only]

A dictionary containing every LuaEquipmentPrototype indexed by name.

damage_prototypes :: LuaCustomTable[string → LuaDamagePrototype] [Read-only]

A dictionary containing every LuaDamagePrototype indexed by name.

virtual_signal_prototypes :: LuaCustomTable[string → LuaVirtualSignalPrototype] [Read-only]

A dictionary containing every LuaVirtualSignalPrototype indexed by name.

equipment_grid_prototypes :: LuaCustomTable[string → LuaEquipmentGridPrototype] [Read-only]

A dictionary containing every LuaEquipmentGridPrototype indexed by name.

recipe_prototypes :: LuaCustomTable[string → LuaRecipePrototype] [Read-only]

A dictionary containing every LuaRecipePrototype indexed by name.

technology_prototypes :: LuaCustomTable[string → LuaTechnologyPrototype] [Read-only]

A dictionary containing every LuaTechnologyPrototype indexed by name.

decorative_prototypes :: LuaCustomTable[string → LuaDecorativePrototype] [Read-only]

A dictionary containing every LuaDecorativePrototype indexed by name.

particle_prototypes :: LuaCustomTable[string → LuaParticlePrototype] [Read-only]

A dictionary containing every LuaParticlePrototype indexed by name.

autoplace_control_prototypes :: LuaCustomTable[string → LuaAutoplaceControlPrototype] [Read-only]

A dictionary containing every LuaAutoplaceControlPrototype indexed by name.

noise_layer_prototypes :: LuaCustomTable[string → LuaNoiseLayerPrototype] [Read-only]

A dictionary containing every LuaNoiseLayerPrototype indexed by name.

mod_setting_prototypes :: LuaCustomTable[string → LuaModSettingPrototype] [Read-only]

A dictionary containing every LuaModSettingPrototype indexed by name.

custom_input_prototypes :: LuaCustomTable[string → LuaCustomInputPrototype] [Read-only]

A dictionary containing every LuaCustomInputPrototype indexed by name.

ammo_category_prototypes :: LuaCustomTable[string → LuaAmmoCategoryPrototype] [Read-only]

A dictionary containing every LuaAmmoCategoryPrototype indexed by name.

named_noise_expressions :: LuaCustomTable[string → LuaNamedNoiseExpression] [Read-only]

A dictionary containing every LuaNamedNoiseExpression indexed by name.

item_subgroup_prototypes :: LuaCustomTable[string → LuaGroup] [Read-only]

A dictionary containing every ItemSubgroup indexed by name.

item_group_prototypes :: LuaCustomTable[string → LuaGroup] [Read-only]

A dictionary containing every ItemGroup indexed by name.

fuel_category_prototypes :: LuaCustomTable[string → LuaFuelCategoryPrototype] [Read-only]

A dictionary containing every LuaFuelCategoryPrototype indexed by name.

resource_category_prototypes :: LuaCustomTable[string → LuaResourceCategoryPrototype] [Read-only]

A dictionary containing every LuaResourceCategoryPrototype indexed by name.

achievement_prototypes :: LuaCustomTable[string → LuaAchievementPrototype] [Read-only]

A dictionary containing every LuaAchievementPrototype indexed by name.

module_category_prototypes :: LuaCustomTable[string → LuaModuleCategoryPrototype] [Read-only]

A dictionary containing every LuaModuleCategoryPrototype indexed by name.

equipment_category_prototypes :: LuaCustomTable[string → LuaEquipmentCategoryPrototype] [Read-only]

A dictionary containing every LuaEquipmentCategoryPrototype indexed by name.

trivial_smoke_prototypes :: LuaCustomTable[string → LuaTrivialSmokePrototype] [Read-only]

A dictionary containing every LuaTrivialSmokePrototype indexed by name.

shortcut_prototypes :: LuaCustomTable[string → LuaShortcutPrototype] [Read-only]

A dictionary containing every LuaShortcutPrototype indexed by name.

recipe_category_prototypes :: LuaCustomTable[string → LuaRecipeCategoryPrototype] [Read-only]

A dictionary containing every LuaRecipeCategoryPrototype indexed by name.

font_prototypes :: LuaCustomTable[string → LuaFontPrototype] [Read-only]

A dictionary containing every LuaFontPrototype indexed by name.

map_gen_presets :: LuaCustomTable[string → MapGenPreset] [Read-only]

A dictionary containing every MapGenPreset indexed by name.

Note: A MapGenPreset is an exact copy of the prototype table provided from the data stage.
styles :: LuaCustomTable[string → string] [Read-only]

The styles that LuaGuiElement can use, indexed by name.

tick :: uint [Read-only]

Current map tick.

ticks_played :: uint [Read-only]

The number of ticks since this game was 'created'. A game is 'created' either by using "new game" or "new game from scenario".

Note: This differs over LuaGameScript::tick in that making a game from a scenario always starts with ticks_played value at 0 even if the scenario has its own level data where the LuaGameScript::tick is > 0.
Note: This value has no relation with LuaGameScript::tick and can be completely different values.
tick_paused :: boolean [Read-Write]

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

ticks_to_run :: uint [Read-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 :: boolean [Read-only]

Is the scenario finished?

speed :: float [Read-Write]

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

Note: Minimum value is 0.01.
surfaces :: LuaCustomTable[uint or string → LuaSurface] [Read-only]

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 only iterate the array part of the table. Iterating with ipairs() will not work at all.

active_mods :: dictionary[string → string] [Read-only]

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

The players that are currently online.

This is primarily useful when you want to do some action against all online players.

Note: This does *not* index using player index. See LuaPlayer::index on each player instance for the player index.
permissions :: LuaPermissionGroups [Read-only]

backer_names :: LuaCustomTable[uint → string] [Read-only]

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 :: MapGenSettings [Read-only]

The default map gen settings for this save.

enemy_has_vision_on_land_mines :: boolean [Read-Write]

Determines if enemy land mines are completely invisible or not.

autosave_enabled :: boolean [Read-Write]

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

draw_resource_selection :: boolean [Read-Write]

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

pollution_statistics :: LuaFlowStatistics [Read-only]

The pollution statistics for this map.

max_force_distraction_distance :: double [Read-only]

max_force_distraction_chunk_distance :: uint [Read-only]

max_electric_pole_supply_area_distance :: float [Read-only]

max_electric_pole_connection_distance :: double [Read-only]

max_beacon_supply_area_distance :: double [Read-only]

max_gate_activation_distance :: double [Read-only]

max_inserter_reach_distance :: double [Read-only]

max_pipe_to_ground_distance :: uint8 [Read-only]

max_underground_belt_distance :: uint8 [Read-only]