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.
freeze_daytime(freeze)	Freeze or unfreeze time of day at the current value.
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_tiles()	Regenerate all tiles.
regenerate_entity(entitites)	Regenerate autoplacement of some entities.
take_screenshot{player=…, position=…, resolution=…, zoom=…, path=…, show_gui=…, show_entity_info=…}	Take a screenshot and save it to a file.
write_file(filename, data, append)	Write a string to a file.
remove_path(path)	Remove file or directory.
get_player(player) → LuaPlayer	Get the LuaPlayer for a player.
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.
get_surface(surface)
create_surface(name, settings)	Create a new surface
server_save(name)	Instruct the server to save the map.
get_item_prototype(item) → LuaItemPrototype	Get the prototype of an item.
always_day :: boolean [RW]	When set to true, the sun will always shine.
player :: LuaPlayer [R]	The player playing the game.
local_player :: LuaPlayer [R]	The player typing at the console.
players :: array of LuaPlayer [R]
evolution_factor :: float [RW]	Evolution factor of enemies.
map_settings :: MapSettings [R]
difficulty :: difficulty [R]	Current scenario difficulty.
forces :: dictionary string → LuaForce [R]
entity_prototypes :: dictionary string → LuaEntityPrototype [R]
item_prototypes :: dictionary string → LuaItemPrototype [R]
fluid_prototypes :: dictionary string → LuaFluidPrototype [R]
tick :: uint [R]	Current map tick.
finished :: boolean [R]	Is the scenario finished?
speed :: float [RW]	Speed to update the map at.
daytime :: float [RW]	Current time of day, as a number in range [0, 1).
darkness :: float [R]	Amount of darkness at the current time.
peaceful_mode :: boolean [RW]	Is peaceful mode enabled?
wind_speed :: float [RW]	Current wind speed.
wind_orientation :: float [RW]	Current wind direction.
wind_orientation_change :: float [RW]	Change in wind orientation per tick.
surfaces :: dictionary string → LuaSurface [R]

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:

game_finished :: boolean
player_won :: boolean
next_level :: string
can_continue :: boolean

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.

freeze_daytime(freeze)

Freeze or unfreeze time of day at the current value.

Parameters

freeze :: boolean

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_tiles()

Regenerate all tiles. This will correct tile transitions and variations on all chunks of the map.

regenerate_entity(entitites)

Regenerate autoplacement of some entities. 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=…, position=…, resolution=…, zoom=…, path=…, show_gui=…, show_entity_info=…}

Take a screenshot and save it to a file.

Parameters

Table with the following fields:

player :: LuaPlayer (optional)
position :: Position (optional)
resolution :: Position (optional)
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)?

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

write_file(filename, data, append)

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

get_player(player) → LuaPlayer

Get the LuaPlayer for a player. The player can be specified as either by their number or username.

Parameters

player :: uint or string

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.

get_surface(surface)

Parameters

surface :: string or LuaSurface

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.

get_item_prototype(item) → LuaItemPrototype

Get the prototype of an item.

Parameters

item :: string: Name of the item prototype to get.

Note: This function may offer better performance than LuaGameScript::item_prototypes for getting the prototype of a single item.

always_day :: boolean [Read-Write]

When set to true, the sun will always shine.

player :: LuaPlayer [Read-only]

The player playing the game.

Note: This attribute is only usable in single-player maps. If the map contains multiple players, it will fail. See LuaGameScript::players.

local_player :: LuaPlayer [Read-only]

The player typing at the console.

players :: array of LuaPlayer [Read-only]

evolution_factor :: float [Read-Write]

Evolution factor of enemies.

map_settings :: MapSettings [Read-only]

difficulty :: difficulty [Read-only]

Current scenario difficulty.

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

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

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