Tutorial:Scripting - Revision history

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

2025-08-08T05:59:35Z

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

← Older revision		Revision as of 05:59, 8 August 2025
Line 10:		Line 10:
	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.		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] ==		== [https://lua-api.factorio.com/latest/auxiliary/libraries.html Factorio specifics] ==
	Factorio uses Lua version 5.2.1.		Factorio uses Lua version 5.2.1.

Xorimuth: Fix broken links, add links, tweak wording.

2025-02-27T13:15:06Z

Fix broken links, add links, tweak wording.

Xorimuth: 2.0 update (global -> storage)

2024-11-13T16:59:56Z

2.0 update (global -> storage)

← Older revision		Revision as of 16:59, 13 November 2024
Line 18:		Line 18:
	* Serpent cannot serialize a lot of Lua objects, such as functions, metatables and coroutines.		* 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.		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] ==		== [http://lua-api.factorio.com/latest/LuaBootstrap.html Script events] ==
Line 26:		Line 26:
	* <code>script.on_load()</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:		<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()		<syntaxhighlight lang="lua">script.on_init(function()
	~~global~~.ticker = 0		storage.ticker = 0
	~~global~~.level = 1		storage.level = 1
	~~global~~.teams = {default_team = "johns-lads"}		storage.teams = {default_team = "johns-lads"}
	game.create_surface("Scenario Surface")		game.create_surface("Scenario Surface")
	game.map_settings.pollution.enabled = false		game.map_settings.pollution.enabled = false
Line 47:		Line 47:
	if not game.entity_prototypes[turret_name] then		if not game.entity_prototypes[turret_name] then
	log("Gun turret isn't here, some mod or something has changed it")		log("Gun turret isn't here, some mod or something has changed it")
	~~global~~.do_turret_logic = false		storage.do_turret_logic = false
	end		end
	end)</syntaxhighlight>		end)</syntaxhighlight>
Line 53:		Line 53:
	The contents of the <code>data</code> parameter is defined [http://lua-api.factorio.com/latest/Concepts.html#ConfigurationChangedData here].		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.		<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		<syntaxhighlight lang="lua">local variable
	script.on_load(function()		script.on_load(function()
	--Resetting metatables		--Resetting metatables
	for k, v in (~~global~~.objects_with_metatable) do		for k, v in (storage.objects_with_metatable) do
	setmetatable(v, object_metatable)		setmetatable(v, object_metatable)
	end		end

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

	--Conditional event handler		--Conditional event handler
	if ~~global~~.trees then		if storage.trees then
	script.on_event(defines.events.on_tick, handle_tree_function)		script.on_event(defines.events.on_tick, handle_tree_function)
	end		end
Line 104:		Line 104:
	that_on_tick(event)		that_on_tick(event)
	end)</syntaxhighlight>		end)</syntaxhighlight>
	== Saving data & the <code>~~global~~</code> table ==		== 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 MP.		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.		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)		<syntaxhighlight lang="lua">script.on_event(defines.events.on_tick, function(event)
	~~global~~.ticker = (~~global~~.ticker or 0) + 1		storage.ticker = (storage.ticker or 0) + 1
	end)</syntaxhighlight>		end)</syntaxhighlight>
	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.		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 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.		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.
Line 146:		Line 146:
	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>.		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.		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 ==
Line 154:		Line 154:
	<syntaxhighlight lang="lua">--Initialize the story info		<syntaxhighlight lang="lua">--Initialize the story info
	script.on_init(function()		script.on_init(function()
	~~global~~.story = story_init()		storage.story = story_init()
	end)		end)

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

Penguinencounter: Fix header

2024-01-13T21:29:09Z

Fix header

← Older revision		Revision as of 21:29, 13 January 2024
Line 1:		Line 1:
	{{Languages}}== What is a script? ==		{{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.		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.

Bilka: Translations of the modding tutorials are allowed

2023-11-13T20:43:38Z

Translations of the modding tutorials are allowed

← Older revision		Revision as of 20:43, 13 November 2023
Line 1:		Line 1:
	== What is a script? ==		{{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.		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.

Ickputzdirwech: Removed {{Languages}}. added category modding

2023-11-12T09:36:25Z

Removed {{Languages}}. added category modding

← Older revision		Revision as of 09:36, 12 November 2023
Line 1:		Line 1:
	~~{{Languages}}~~
	== What is a script? ==		== 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.		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.

Line 9:		Line 7:

	== Loading a script ==		== 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.		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] ==		== [https://lua-api.factorio.com/latest/Libraries.html Factorio specifics] ==

	Factorio uses Lua version 5.2.1.		Factorio uses Lua version 5.2.1.

Line 24:		Line 20:

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

	The Lua script has some special functions it runs outside of events:		The Lua script has some special functions it runs outside of events:
	* <code>script.on_init()</code>		* <code>script.on_init()</code>
Line 273:		Line 268:
	--Shorthand syntax for game.surfaces[i], defaults i to 1		--Shorthand syntax for game.surfaces[i], defaults i to 1
	surface(i)</syntaxhighlight>		surface(i)</syntaxhighlight>

			[[Category:Modding]]

Bilka: updated doc links to migrated prototype docs

2023-09-21T11:29:08Z

updated doc links to migrated prototype docs

← Older revision		Revision as of 11:29, 21 September 2023
Line 4:		Line 4:
	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.		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.		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.		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.

Bilka: Replaced deprecated source html tag

2022-09-06T15:01:05Z

Replaced deprecated source html tag

Show changes

Bilka at 14:56, 6 September 2022

2022-09-06T14:56:37Z

← Older revision		Revision as of 14:56, 6 September 2022
Line 1:		Line 1:
	{{Languages}}== What is a script? ==		{{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.		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.

Bilka: Added missing language template

2022-09-06T14:56:15Z

Added missing language template

← Older revision		Revision as of 14:56, 6 September 2022
Line 1:		Line 1:
	== What is a script? ==		{{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.		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.

← Older revision		Revision as of 13:15, 27 February 2025
Line 26:		Line 26:
	* <code>script.on_load()</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 storage variables you will need, changing game parameters, for instance:		[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()		<syntaxhighlight lang="lua">script.on_init(function()
Line 37:		Line 37:
	end)</syntaxhighlight>		end)</syntaxhighlight>

	[~~http~~://lua-api.factorio.com/latest/LuaGameScript.html <code>game</code>] namespace is available during on_init		[https://lua-api.factorio.com/latest/classes/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.		[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:		So if you are dependent on some prototype for your script to work, you should check here that it still exists:
Line 45:		Line 45:
	<syntaxhighlight lang="lua">script.on_configuration_changed(function(data)		<syntaxhighlight lang="lua">script.on_configuration_changed(function(data)
	local turret_name = "gun-turret"		local turret_name = "gun-turret"
	if not ~~game~~.~~entity_prototypes~~[turret_name] then		if not prototypes.entity[turret_name] then
	log("Gun turret isn't here, some mod or something has changed it")		log("Gun turret isn't here, some mod or something has changed it")
	storage.do_turret_logic = false		storage.do_turret_logic = false
Line 51:		Line 51:
	end)</syntaxhighlight>		end)</syntaxhighlight>

	The contents of the <code>data</code> parameter is defined [~~http~~://lua-api.factorio.com/latest/~~Concepts~~.html~~#ConfigurationChangedData~~ here].		The contents of the <code>data</code> parameter is defined [https://lua-api.factorio.com/latest/concepts/ConfigurationChangedData.html 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>storage</code>, and setting up conditional event handlers.		[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		<syntaxhighlight lang="lua">local variable
Line 106:		Line 106:
	== Saving data & the <code>storage</code> table ==		== 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 MP.		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.		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.
Line 113:		Line 113:
	storage.ticker = (storage.ticker or 0) + 1		storage.ticker = (storage.ticker or 0) + 1
	end)</syntaxhighlight>		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 MP, players joining the game will load the value from the save.		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.		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:		However it is not often this easy. The case is often as follows:
Line 142:		Line 142:

	script.on_event(defines.event.on_tick, on_tick)</syntaxhighlight>		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 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 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, ~~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>.		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.		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 ==