Factorio » Classes » LuaGameScriptFactorio 0.14.21

LuaGameScript

class LuaGameScript
get_event_handler(event) Find the event handler for an event.
raise_event(event, table) Raise an event.
set_game_state{game_finished=…, player_won=…, next_level=…, can_continue=…} Set scenario state.
get_entity_by_tag(tag) → LuaEntity
show_message_dialog{text=…, image=…, point_to=…} Show an in-game message dialog.
disable_tips_and_tricks() Disable showing tips and tricks.
is_demo() → boolean Is this the demo version of Factorio?
save(name) Save scenario progress.
load(name) Load scenario progress.
reload_script() Forces a reload of the scenario script when the save game without the migration is loaded.
save_atlas() Saves the current configuration of Atlas to a file.
check_consistency() Run internal consistency checks.
regenerate_entity(entitites) Regenerate autoplacement of some entities on all surfaces.
take_screenshot{player=…, by_player=…, position=…, resolution=…, zoom=…, path=…, show_gui=…, show_entity_info=…, anti_alias=…} Take a screenshot and save it to a file.
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) Merge two forces together.
create_surface(name, settings) Create a new surface
server_save(name) Instruct the server to save the map.
delete_surface(surface) Deletes the given surface and all entities on it.
disable_replay() Disables replay saving for the current save file.
direction_to_string(direction) Converts the given direction into the string version of the direction.
print(message) Print text to the chat console all players.
player :: LuaPlayer [R] The player typing at the console - nil in all other instances.
players :: custom dictionary uint or string → LuaPlayer [R]
evolution_factor :: float [RW] Evolution factor of enemies.
map_settings :: MapSettings [R]
difficulty :: defines.difficulty [R] Current scenario difficulty.
forces :: custom dictionary string → LuaForce [R]
entity_prototypes :: custom dictionary string → LuaEntityPrototype [R]
item_prototypes :: custom dictionary string → LuaItemPrototype [R]
fluid_prototypes :: custom dictionary string → LuaFluidPrototype [R]
tile_prototypes :: custom dictionary string → LuaTilePrototype [R]
equipment_prototypes :: custom dictionary string → LuaEquipmentPrototype [R]
damage_prototypes :: custom dictionary string → LuaDamagePrototype [R]
virtual_signal_prototypes :: custom dictionary string → LuaVirtualSignalPrototype [R]
equipment_grid_prototypes :: custom dictionary string → LuaEquipmentGridPrototype [R]
tick :: uint [R] Current map tick.
finished :: boolean [R] Is the scenario finished?
speed :: float [RW] Speed to update the map at.
surfaces :: custom dictionary string → LuaSurface [R]
active_mods :: dictionary string → string [R] The active mods versions.
connected_players :: array of LuaPlayer [R] The online players This is primarally useful when you want to do some action against all online players.

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.

get_event_handler(event)

Find the event handler for an event.

Parameters
event :: uint: The event identifier to get a handler for
Return value
Reference to the function currently registered as the handler.
raise_event(event, table)

Raise an event.

Parameters
event :: uint: ID of the event to raise
table: Table with extra data. This table will be passed to the event handler.
set_game_state{game_finished=…, player_won=…, next_level=…, can_continue=…}

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=…}

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.
Note: Can only be used when the map contains exactly one player.
disable_tips_and_tricks()

Disable showing tips and tricks.

is_demo() → boolean

Is this the demo version of Factorio?

save(name)

Save scenario progress.

Parameters
name :: string: Save name
Note: This doesn't save the map, like the "Save" menu button would. This is to implement restarts functionality like in e.g. Tight Spot.
load(name)

Load scenario progress.

Parameters
name :: string: Name previously saved by LuaGameScript::save.
reload_script()

Forces a reload of the scenario script when the save game without the migration is loaded.

Note: Useable only in migration scripts.
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(entitites)

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

Parameters
entitites :: string or array of string: Prototype names of entity or entities to autoplace.
Note: All specified entity prototypes must be autoplacable.
take_screenshot{player=…, by_player=…, position=…, resolution=…, zoom=…, path=…, show_gui=…, show_entity_info=…, anti_alias=…}

Take a screenshot and save it to a file.

Parameters
Table with the following fields:
  • player :: string or LuaPlayer or uint (optional)
  • by_player :: string or LuaPlayer or uint (optional): If defined, the screenshot will only be taken for this player.
  • position :: Position (optional)
  • resolution :: Position (optional): Maximum allowed resolution is 16384x16384 (resp. 8196x8196 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)?
  • anti_alias :: boolean (optional): Render in double resolution and scale down (including GUI)?
Note: If Factorio is running headless, this function will do nothing.
write_file(filename, data, append, for_player)

Write a string to a file.

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

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

Parameters
source :: string: The force to remove
destination :: string: 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.
create_surface(name, settings)

Create a new surface

Parameters
name :: string: Name of the new surface
settings :: MapGenSettings (optional): Map generation settings
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.
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 (0, '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.

direction_to_string(direction)

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

Parameters
direction :: defines.direction
print(message)

Print text to the chat console all players.

Parameters
message :: LocalisedString
player :: LuaPlayer [Read-only]

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

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

Note: This is a sparse table so pairs(), a known player index, or player name should be used to access elements.
evolution_factor :: float [Read-Write]

Evolution factor of enemies.

map_settings :: MapSettings [Read-only]

difficulty :: defines.difficulty [Read-only]

Current scenario difficulty.

forces :: custom dictionary string → LuaForce [Read-only]

entity_prototypes :: custom dictionary string → LuaEntityPrototype [Read-only]

item_prototypes :: custom dictionary string → LuaItemPrototype [Read-only]

fluid_prototypes :: custom dictionary string → LuaFluidPrototype [Read-only]

tile_prototypes :: custom dictionary string → LuaTilePrototype [Read-only]

equipment_prototypes :: custom dictionary string → LuaEquipmentPrototype [Read-only]

damage_prototypes :: custom dictionary string → LuaDamagePrototype [Read-only]

virtual_signal_prototypes :: custom dictionary string → LuaVirtualSignalPrototype [Read-only]

equipment_grid_prototypes :: custom dictionary string → LuaEquipmentGridPrototype [Read-only]

tick :: uint [Read-only]

Current map tick.

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.1.
surfaces :: custom dictionary string → LuaSurface [Read-only]

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 of LuaPlayer [Read-only]

The online players

This is primarally 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.