Tutorial:Scripting

2025-08-08T05:59:35Z

DoubleThought: Update a dead link to point to the new location for the factorio lua api libraries page

{{Languages}}
== What is a script? ==
In general, you can learn the definition of a script [https://en.wikipedia.org/wiki/Scripting_language here]. Within the context of Factorio, a script refers to a Lua script, packaged with a mod or scenario.

There are 2 usages of scripts, loading of [https://lua-api.factorio.com/latest/index-prototype.html prototype data], and runtime scripting of the game and its entities.

This guide only covers usages of runtime scripts. To be more specific, we call these runtime scripts 'control scripts', as they assert direct control on the game as it runs.

== Loading a script ==
When you load a game, scenario and mod scripts are loaded. The game looks for a file called 'control.lua', in the mod directory or the scenario directory. If found, the game will then load that script, and any other scripts required in the control script.

== [https://lua-api.factorio.com/latest/auxiliary/libraries.html Factorio specifics] ==
Factorio uses Lua version 5.2.1.

Factorio uses Serpent for serialization - This comes with some big drawbacks:

* Serpent is relatively slow and inefficient
* Serpent cannot serialize a lot of Lua objects, such as functions, metatables and coroutines.

The full scripting API is generated and updated each release, and is available [https://lua-api.factorio.com/latest/index-runtime.html here]. This is the number 1 resource for scripting in the game.

== [http://lua-api.factorio.com/latest/LuaBootstrap.html Script events] ==
The Lua script has some special functions it runs outside of events:
* <code>script.on_init()</code>
* <code>script.on_configuration_changed()</code>
* <code>script.on_load()</code>

[https://lua-api.factorio.com/latest/classes/LuaBootstrap.html#on_init <code>on_init()</code>] will run when the game starts (or in mod cases, when you add it to an existing save). It is used to initialize storage variables you will need, changing game parameters, for instance:

<syntaxhighlight lang="lua">script.on_init(function()
storage.ticker = 0
storage.level = 1
storage.teams = {default_team = "johns-lads"}
game.create_surface("Scenario Surface")
game.map_settings.pollution.enabled = false
--etc.
end)</syntaxhighlight>

[https://lua-api.factorio.com/latest/classes/LuaGameScript.html <code>game</code>] namespace is available during on_init.

[https://lua-api.factorio.com/latest/classes/LuaBootstrap.html#on_configuration_changed <code>on_configuration_changed(data)</code>] will run when some configuration about this save game changes, such as a mod being added, changed or removed. This function is used to account for changes to game or prototype changes. <code>data</code> will contain information on what has changed.

So if you are dependent on some prototype for your script to work, you should check here that it still exists:

<syntaxhighlight lang="lua">script.on_configuration_changed(function(data)
local turret_name = "gun-turret"
if not prototypes.entity[turret_name] then
log("Gun turret isn't here, some mod or something has changed it")
storage.do_turret_logic = false
end
end)</syntaxhighlight>

The contents of the <code>data</code> parameter is defined [https://lua-api.factorio.com/latest/concepts/ConfigurationChangedData.html here].

[https://lua-api.factorio.com/latest/classes/LuaBootstrap.html#on_load <code>on_load()</code>] will run every time the script loads. <code>game</code> will not be available during <code>on_load</code>. This should only be used to handle resetting up metatables, making local references to variables in <code>storage</code>, and setting up conditional event handlers.

<syntaxhighlight lang="lua">local variable
script.on_load(function()
--Resetting metatables
for k, v in (storage.objects_with_metatable) do
setmetatable(v, object_metatable)
end

--Setting local reference to variable in storage
variable = storage.variable

--Conditional event handler
if storage.trees then
script.on_event(defines.events.on_tick, handle_tree_function)
end
end)</syntaxhighlight>
It is quite easy to generate desyncs doing overly complex things with on_load, so we recommend only doing things with it if absolutely nescessary.

== [http://lua-api.factorio.com/latest/events.html Game events] ==

The scripts all run based off events. These events are sent by the game after certain actions are performed. For instance <code>on_player_crafted_item</code>. To ''do'' something with an event, you will need to assign an event handler:

<syntaxhighlight lang="lua">script.on_event(defines.events.on_player_crafted_item, player_crafted_function)</syntaxhighlight>
When the event is triggered, it will then call the function with <code>event</code> as its parameter. <code>event</code> is a table that contains varying information about the event. More specific info on them [http://lua-api.factorio.com/latest/events.html here]. You then process the event using your own function:

<syntaxhighlight lang="lua">function player_crafted_function(event)
game.print("A player crafted an item on tick "..event.tick)
end</syntaxhighlight>
This also works with anonymous functions:

<syntaxhighlight lang="lua">script.on_event(defines.events.on_tick, function(event)
game.print("tick")
end)</syntaxhighlight>
Note that only one event handler can be assigned for each event, such that:

<syntaxhighlight lang="lua">script.on_event(defines.events.on_tick, function(event)
game.print("tick")
end)

script.on_event(defines.events.on_tick, function(event)
game.print("tock")
end)</syntaxhighlight>
The second handler will overwrite the first.

If you want to do multiple things on the same event, a simple way is as follows:

<syntaxhighlight lang="lua">script.on_event(defines.events.on_tick, function(event)
this_on_tick(event)
that_on_tick(event)
end)</syntaxhighlight>
== Saving data & the <code>storage</code> table ==

Save/Load stability is very important to preserve the determinism of the game. In Lua, all values are global by default. This isn’t good news in Factorio, as it can make it seem as though things are working correctly, but will lead to desyncs in multiplayer.

To preserve data between load and save, we have the <code>storage</code> table. If there is some variable that you need to use between events, this is where it should live.

<syntaxhighlight lang="lua">script.on_event(defines.events.on_tick, function(event)
storage.ticker = (storage.ticker or 0) + 1
end)</syntaxhighlight>
Now when the player saves the game, the value of <code>storage.ticker</code> will be saved. When it is loaded again, its value will be restored. This is important, because in multiplayer, players joining the game will load the value from the save.

The way this can cause desyncs is quite clear: if one player has their Lua state, with a ticker value of 100, and another has a value of 50, and you then create ticker number of biters, it would create 100 for player 1, and 50 for player 2.

However it is not often this easy. The case is often as follows:

<syntaxhighlight lang="lua">tick_to_print = 10 --So lets say this is a static variable. Just some config for how your script works.

function on_tick()
if game.tick == tick_to_print then
game.print("hello")
end
end

script.on_event(defines.event.on_tick, on_tick)</syntaxhighlight>
This will be fine, we are using the variable, but not changing it. When a new player loads the game, <code>tick_to_print</code> will be <code>10</code>, same as the other players.

Problem comes if we adjust <code>tick_to_print</code>, either by purpose or intentionally.

<syntaxhighlight lang="lua">tick_to_print = 10 --So lets say this is a static variable. Just some config for how your script works.

function on_tick()
if game.tick == tick_to_print then
game.print("hello")
tick_to_print = tick_to_print + 100 --Say we want it to print again in 100 ticks
end
end

script.on_event(defines.event.on_tick, on_tick)</syntaxhighlight>
Now when you test the script, it will work perfectly. Every 100 ticks it will print “hello”. The problem occurs when you save and then load the game. When you save, the value of <code>tick_to_print</code> is not saved anywhere, and so when you load, it just uses the value it is told to at the top of the script: <code>10</code>.

Now it is clear that the value of <code>tick_to_print</code> has changed by saving and loading, so we say it is not save/load stable. If a players joins a multiplayer game with this script, they would desync as soon as one of the scripts prints as the result of a comparison against <code>tick_to_print</code>.

So TL;DR - If you want to use something between ticks then store it in <code>storage</code>. This will prevent 99% of possible desyncs.

== Story script ==

Story script is a Lua library designed to facilitate the scripting and flow of a story. It has some simple structure and supporting function to help things move along.

<syntaxhighlight lang="lua">--Initialize the story info
script.on_init(function()
storage.story = story_init()
end)

--Register to update the story on events
script.on_event(defines.events, function(event)
story_update(storage.story, event)
end)

--Story table is where the 'story' is all defined.
story_table =
{
{
--branch 1
{
--First story event

--Initialise this event
init = function(event, story)
game.print("First init of first story event")
end,

--Update function that will run on all events
update = function(event, story)
log("updating")
end,

--Condition to move on. If the return value is 'true', the story will continue.
condition = function(event, story)
if event.tick > 100 then
return true
end
end,

--Action to perform after condition is met
action = function(event, story)
game.print("You completed the objective!")
end
},
{
--Second story event - example.
init = function(event, story)
game.print("Collect 100 iron plate")
end,
condition = function(event, story)
return game.players[1].get_item_count("iron-plate") >= 100
end,
action = function(event, story)
game.print("Well done")
end
}
--Once the end of a branch is reached, the story is finished.
--The game will now display the mission complete screen.
},
{
--branch 2
}
}

--Init the helpers and story table. Must be done all times script is loaded.
story_init_helpers(story_table)</syntaxhighlight>

Branches are an optional system of the story system, and you can jump to another branch using <code>story_jump_to(story, name)</code>. The story progresses from the top down, and when it reaches the last story event, the mission concludes.

It is possible to leverage any number of clever Lua tricks and API calls in the story table. It is good form to try and keep each story part independant from its neighbors, as it makes maintanance and reworkings more manageable.

Bad:

<syntaxhighlight lang="lua"> {
action = function()
player().insert("iron-plate")
end
},
{
init = function()
player().print("Use your iron plate to craft some belts")
end
}</syntaxhighlight>
Good:

<syntaxhighlight lang="lua"> {
init = function()
player().insert("iron-plate")
player().print("Use your iron plate...")
end
}</syntaxhighlight>

There are some utility functions to make things simpler on the scripting side:

<syntaxhighlight lang="lua">--Return true only after this many seconds has elasped
story_elapsed_check(5)

--Update the objective for all players
set_goal({"objective-1"})

--Flash the goal GUI for players (updating info doesn't flash it)
flash_goal()

--Update the 'info gui' for all players. This is quite powerful and can use custom function to build complex GUI's
set_info(
{
text = {"info-1"},
picture = "item/iron-plate"
})

--Exports entities in a Lua table format
export_entities(parameters)

--Recreates entities saved using a Lua format
recreate_entities(entities, parameters)

--Shorthand syntax for game.players[i], defaults i to 1
player(i)

--Shorthand syntax for game.surfaces[i], defaults i to 1
surface(i)</syntaxhighlight>

[[Category:Modding]]

Application directory

2024-08-26T04:39:15Z

DoubleThought: /* Locations */

{{Languages}}
== Overview ==
Depending on your installation method and OS, you will have one or two directories that contain Factorio assets, and one that contains user data, such as saves and mods.

== User data directory ==
The user data directory is where personal files are stored:
* Save files <code>./saves</code>
* Mods <code>./mods</code>
* Script-output, e.g. from /screenshot <code>./script-output</code>
* Local [[scenario system|scenarios]] <code>./scenarios</code>
* Local settings <code>./config/config.ini</code>
* [[log file]]s <code>factorio-*.log</code>
* Crash dump files <code>factorio-dump-*.dmp</code>

=== Locations ===
Search your computer for the directory location, or type the path into your file manager address bar.

Windows:

%appdata%\Factorio

:The <code>%appdata%</code> shorthand translates to your local version of <code>C:\Users\[user name]\AppData\Roaming</code>

MacOSX:

~/Library/Application Support/factorio

Linux distributions:

~/.factorio

:When using the Flatpak version of steam, all paths start from <code>~/.var/app/com.valvesoftware.Steam/</code> instead.

When using Steam on Windows, the config.ini, achievements.dat, modded-achievements.dat and player-data.json can also be found in

C:\Program Files (x86)\Steam\userdata\[user number]\427520\remote

== Application directory ==
The application directory stores three things:
* Factorio executables <code>./bin</code>
* Data for vanilla Factorio <code>./data</code>
* API documentation <code>./doc-html</code>

=== Locations ===

Windows:

C:\Program Files (x86)\Steam\steamapps\common\Factorio
C:\Program Files\Factorio

MacOSX:

~/Library/Application Support/Steam/steamapps/common/Factorio/factorio.app/Contents
/Applications/factorio.app/Contents

Linux:

~/.factorio

Debian-based Linux, with Factorio installed through Steam:

~/.steam/steam/steamapps/common/Factorio

== Changing the user data directory ==

You can create a file <code>config-path.cfg</code> to configure Factorio to any directory.

In order to change the user data directory, user must edit the location of the "write-data" entry in the file <code>(Game install directory)/config/config.ini</code>. This affects the location of mods, scenario and temp.

==== macOS ====
Create <code>factorio.app/config-path.cfg</code> with the following contents:

config-path=__PATH__executable__/../config
use-system-read-write-data-directories=false

Update <code>factorio.app/Contents/config/config.ini</code>

[path]
read-data=__PATH__executable__/../data
write-data=__PATH__executable__/..

'''[http://www.factorioforums.com/forum/viewtopic.php?f=49&t=12819&p=87281#p87281 Please see this discussion]''' (for older versions of macOS, but may work on any other OS).

==== Linux ====
Update <code>__Game_Install_directory/config-path.cfg</code>

use-system-read-write-data-directories=true

Update <code>__Game_Install_directory/config/config.ini</code>

[path]
read-data=__PATH__executable__/../../data
write-data=.local/share/factorio

You could set the <code>write-data</code> value to '''<code>.factorio</code>''' if you prefer.

Once you have done this, you can remove write permissions to the entire game installation directory '''except''' for <code>config/config.ini</code>, which '''must''' be writable by all people who wish to play the game.

Note that if someone changes any options, in-game, those option changes will apply to everyone who plays on the same computer.

== Installation from Zip File ==
The unzipped Factorio directory.

A list of all things found here:

* Save games (as zip files)
* User-installed/created [[Mods]].
* User-installed/created scenarios.
* User configuration and settings storage
* [[Log file]] (factorio-*.log)
* Player data (player-data.json)

Note: Deleting the configuration file will result in a default replacement being generated upon the next Factorio launch.

It is recommended to create backups from this directory (of saves, config, etc) before installing a new version.

== See also ==
* [[Install guide]]
* [[Installing Mods]]
* [http://www.factorioforums.com/forum/viewtopic.php?f=5&t=8294 Linux Version - Save games in $HOME somewhere]

{{C|Main}}

Official Factorio Wiki - User contributions [en]

Tutorial:Scripting

Application directory