Factorio talk:Terms of Service

2022-02-02T20:09:44Z

Sunarch: Response

In the "Intellectual Property and Sharing", in the second bullet point the example is given thus: "(for instance namely translations)" which is a doubling of the meaning. Preferably it should be one or the other: "for instance, translations" or "namely, translations" (the first one being better in this context, in my opinion). -- [[User:Sunarch|Sunarch]] ([[User talk:Sunarch|talk]]) 05:08, 9 January 2022 (UTC)
:Hey, as stated on the page, these Terms of Service are a copy of the Terms of Service of factorio.com. If you'd like those amended, I'd suggest sending an email to factorio@factorio.com. -- [[User:Bilka|Bilka]] ([[User talk:Bilka|talk]]) - <span style="color:#FF0000">Admin</span> 17:54, 13 January 2022 (UTC)
::I just wanted to point it out. If you don't think any action should be taken on it, I don't think it's a major issue. -- [[User:Sunarch|Sunarch]] ([[User talk:Sunarch|talk]]) 20:09, 2 February 2022 (UTC)

Factorio talk:Terms of Service

2022-01-09T05:08:12Z

Sunarch: Add note on wording of an example

Tutorial:Scripting

2022-01-09T04:55:51Z

Sunarch: /* Saving data & the global table */ Add missing verb

== 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 [[prototype definitions|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/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 [http://lua-api.factorio.com/latest/index.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>

<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 global variables you will need, changing game parameters, for instance:

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

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

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

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

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

<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>global</code>, and setting up conditional event handlers.

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

--Setting local reference to global variable
variable = global.variable

--Conditional event handler
if global.trees then
script.on_event(defines.events.on_tick, handle_tree_function)
end
end)</source>
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:

<source lang="lua">script.on_event(defines.events.on_player_crafted_item, player_crafted_function)</source>
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:

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

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

<source 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)</source>
The second handler will overwrite the first.

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

<source lang="lua">script.on_event(defines.events.on_tick, function(event)
this_on_tick(event)
that_on_tick(event)
end)</source>
== Saving data & the <code>global</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 MP.

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

<source lang="lua">script.on_event(defines.events.on_tick, function(event)
global.ticker = (global.ticker or 0) + 1
end)</source>
Now when the player saves the game, the value of <code>global.ticker</code> will be saved. When it is loaded again, its value will be restored. This is important, because in MP, 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:

<source 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)</source>
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.

<source 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)</source>
Now when you test the script, it will work perfectly. Every 100 ticks it will print “hello”. The problem occurs when you save, and load the game. When you save, the value of <code>tick_to_print</code> is not saved anywhere, And thus, when you load, it just uses the value its 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, thus we say it is not save/load stable. If a players joins a MP 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>global</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.

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

--Register to update the story on events
script.on_event(defines.events, function(event)
story_update(global.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)</source>

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:

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

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

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

<source 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)</source>

Official Factorio Wiki - User contributions [en]

Factorio talk:Terms of Service

Factorio talk:Terms of Service

Tutorial:Scripting