Tutorial:Modding tutorial/Gangsir - Revision history

Bilka: Mod structure page moved to lua-api.factorio.com

2025-09-18T11:15:55Z

Mod structure page moved to lua-api.factorio.com

← Older revision		Revision as of 11:15, 18 September 2025
Line 107:		Line 107:
	=== Creation of the directory structure ===		=== Creation of the directory structure ===

	The game expects mod to be laid out [~~[Tutorial~~:~~Mod~~ structure\|in a certain way]]. To start out, create a folder in your [[Application directory\|user data directory]]/mods folder. This folder must have a specific name, <code>fire-armor</code>. You don't need to zip anything for now, that will come later when you're done working on the mod. When you're finished, the mod directory should look like this:		The game expects mod to be laid out [https://lua-api.factorio.com/latest/auxiliary/mod-structure.html in a certain way]. To start out, create a folder in your [[Application directory\|user data directory]]/mods folder. This folder must have a specific name, <code>fire-armor</code>. You don't need to zip anything for now, that will come later when you're done working on the mod. When you're finished, the mod directory should look like this:

	* (user data directory, sometimes called .factorio)		* (user data directory, sometimes called .factorio)
Line 123:		Line 123:
	=== The info.json file ===		=== The info.json file ===

	Then, inside [~~[Tutorial~~:~~Mod_structure~~#info.json\|info.json]], copy and paste the following into it:		Then, inside [https://lua-api.factorio.com/latest/auxiliary/mod-structure.html#info.json info.json], copy and paste the following into it:

	<pre style="background-color:#AAFFAA!important; color:black">		<pre style="background-color:#AAFFAA!important; color:black">

Xorimuth: Remove obsolete migration text, clarify surrounding text.

2025-02-27T16:18:42Z

Remove obsolete migration text, clarify surrounding text.

← Older revision		Revision as of 16:18, 27 February 2025
Line 70:		Line 70:
	[https://lua-api.factorio.com/latest/auxiliary/migrations.html Migrations] are scripts that are used to "fix" a save after a mod updates. Whenever prototype names change within a mod, migrations must be setup to replace all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.		[https://lua-api.factorio.com/latest/auxiliary/migrations.html Migrations] are scripts that are used to "fix" a save after a mod updates. Whenever prototype names change within a mod, migrations must be setup to replace all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

	To avoid having to write migrations, avoid changing prototype names and technology unlocks~~. Prototypes names cannot be dynamically changed and technology unlocks of already researched technologies do not apply automatically, making migrations necessary. Try to avoid these changes~~ after shipping the mod out to the public. Try to come up with a finalized version of prototype names that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.		To avoid having to write migrations, avoid changing prototype names and technology unlocks after shipping the mod out to the public. Additionally, prototype names cannot be dynamically migrated because migrations are just a static list of names. Try to come up with a finalized version of prototype names that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

	=== Runtime stage ===		=== Runtime stage ===

PennyJim: Update references of `global` to `storage` - Some rewording in places might be recommended

2024-12-13T23:12:36Z

Update references of `global` to `storage` - Some rewording in places might be recommended

← Older revision		Revision as of 23:12, 13 December 2024
Line 432:		Line 432:
	</pre>		</pre>

	If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [https://lua-api.factorio.com/latest/auxiliary/~~global~~.html ~~global~~] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.		If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [https://lua-api.factorio.com/latest/auxiliary/storage.html storage] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

	=== Conditional event subscribing ===		=== Conditional event subscribing ===
Line 446:		Line 446:
	* Re-register conditional event handlers		* Re-register conditional event handlers
	* Re-setup meta tables		* Re-setup meta tables
	* Create local references to tables stored in the ~~global~~ table		* Create local references to tables stored in the storage table

	Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.		Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

PennyJim: Fix typo (controller the character :facepalm:)

2024-11-03T22:51:20Z

Fix typo (controller the character :facepalm:)

← Older revision		Revision as of 22:51, 3 November 2024
Line 274:		Line 274:
	function(event)		function(event)
	local player = game.get_player(event.player_index) -- get the player that moved		local player = game.get_player(event.player_index) -- get the player that moved
	-- if they're currently ~~controller~~ the character		-- if they're currently controlling the character
	if player.controller_type == defines.controllers.character then		if player.controller_type == defines.controllers.character then
	-- and wearing our armor		-- and wearing our armor

PennyJim: Tweak formatting

2024-11-03T22:49:37Z

Tweak formatting

← Older revision		Revision as of 22:49, 3 November 2024
Line 275:		Line 275:
	local player = game.get_player(event.player_index) -- get the player that moved		local player = game.get_player(event.player_index) -- get the player that moved
	-- if they're currently controller the character		-- if they're currently controller the character
	if player.controller_type == defines.controllers.character		if player.controller_type == defines.controllers.character then
	-- ~~And~~ wearing our armor		-- and wearing our armor
	~~and~~ player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then		if player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
	-- create the fire where they're standing		-- create the fire where they're standing
	player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}		player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
			end
	end		end
	end		end

PennyJim: Update references of 1.1 to 2.0, and fix a crash with map view

2024-11-03T22:36:32Z

Update references of 1.1 to 2.0, and fix a crash with map view

← Older revision		Revision as of 22:36, 3 November 2024
Line 1:		Line 1:
	{{Languages}}		{{Languages}}
	This is a modding tutorial for Factorio version 1.1. In this tutorial, the author will explain how Factorio works behind the scenes, how to modify Factorio, where to find documentation, and explain concepts.		This is a modding tutorial for Factorio version 2.0. In this tutorial, the author will explain how Factorio works behind the scenes, how to modify Factorio, where to find documentation, and explain concepts.

	== Overview ==		== Overview ==
Line 15:		Line 15:
	</pre>		</pre>

	This tutorial was updated to version 1.1, so any ''viewers in the future should take note that some minor changes may have been made'', and should look at the changelogs up to the current version.		This tutorial was updated to version 2.0, so any ''viewers in the future should take note that some minor changes may have been made'', and should look at the changelogs up to the current version.

	== Terminology used in modding ==		== Terminology used in modding ==
Line 131:		Line 131:
	"title": "Fire Armor",		"title": "Fire Armor",
	"author": "You",		"author": "You",
	"factorio_version": "1.1",		"factorio_version": "2.0",
	"dependencies": ["base >= 1.1"],		"dependencies": ["base >= 2.0"],
	"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."		"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
	}		}
Line 156:		Line 156:
	\|-		\|-
	\| factorio_version		\| factorio_version
	\| This tells the game what version the mod is for, this must match the version you're developing the mod for, 1.1 in this case.		\| This tells the game what version the mod is for, this must match the version you're developing the mod for, 2.0 in this case.
	\|-		\|-
	\| dependencies		\| dependencies
Line 274:		Line 274:
	function(event)		function(event)
	local player = game.get_player(event.player_index) -- get the player that moved		local player = game.get_player(event.player_index) -- get the player that moved
	-- if they're ~~wearing our armor~~		-- if they're currently controller the character
	if player.character and player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then		if player.controller_type == defines.controllers.character
			-- And wearing our armor
			and player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
	-- create the fire where they're standing		-- create the fire where they're standing
	player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}		player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}

Bilka: 2.0 ready recipe prototype

2024-10-05T15:25:36Z

2.0 ready recipe prototype

← Older revision		Revision as of 15:25, 5 October 2024
Line 216:		Line 216:
	enabled = true,		enabled = true,
	energy_required = 8, -- time to craft in seconds (at crafting speed 1)		energy_required = 8, -- time to craft in seconds (at crafting speed 1)
	ingredients = {{"copper-plate", 200}, {"steel-plate", 50}},		ingredients = {
	~~result~~ = "fire-armor"		{type = "item", name = "copper-plate", amount = 200},
			{type = "item", name = "steel-plate", amount = 50}
			},
			results = {{type = "item", name = "fire-armor", amount = 1}}
	}		}

Bilka: Moved extended learning section above common errors and desyncs

2024-01-16T19:44:38Z

Moved extended learning section above common errors and desyncs

@@ Line 311: / Line 311: @@
 However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.
 == Resolving common errors in modding ==
@@ Line 440: / Line 462: @@
 </pre>
 This will desync in the same way as described for the plain tables <code>a</code> and <code>b</code> above. For entities it is recommended to use [https://lua-api.factorio.com/latest/LuaEntity.html#LuaEntity.unit_number LuaEntity.unit_number] as the table key instead of the whole entity.
 == See also ==

Bilka: /* The tutorial mod */ mention vscode later too

2024-01-16T19:37:48Z

The tutorial mod: mention vscode later too

← Older revision		Revision as of 19:37, 16 January 2024
Line 97:		Line 97:

	* A recent install of Factorio		* A recent install of Factorio
	* A text editor, such as Emacs, Vim, Sublime ~~text~~, ~~etc~~		* A text editor, such as Emacs, Vim, Sublime Text, VSCode, or Notepad++.
	* An understanding of the tutorial above		* An understanding of the tutorial above
	* An understanding of Lua as a programming language. Enough to know the syntax and how it works. If you have prior programming experience, it should not be difficult to pick up.		* An understanding of Lua as a programming language. Enough to know the syntax and how it works. If you have prior programming experience, it should not be difficult to pick up.

Bilka: /* Syntax errors */ updated error

2024-01-16T19:33:52Z

Syntax errors: updated error

← Older revision		Revision as of 19:33, 16 January 2024
Line 318:		Line 318:
	=== Syntax errors ===		=== Syntax errors ===

	The ~~lua~~ programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:		The Lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

	<pre style="background-color:#DDA0DD!important; color:black">		<pre style="background-color:#DDA0DD!important; color:black">
	Failed to load ~~mods~~: __fire-armor__/data.lua:36: ~~syntax error~~ near '~~true~~'		Failed to load mod "fire-armor": __fire-armor__/data.lua:39: unfinished string near '"fire-armor,'
	</pre>		</pre>

	You'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?		You'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

	Right away, we see the reason why Factorio didn't start normally. "Failed to load ~~mods~~:". So, we know that it's a mod that messed up~~, and by extension, we know it's our mod~~. Whenever the Lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was ~~indirectly~~ caused by line 36 of data.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.		Right away, we see the reason why Factorio didn't start normally. "Failed to load mod "fire-armor":". So, we know that it's our mod that messed up. Whenever the Lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was caused by line 39 of data.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

	Going to line 36 of data.lua, we find:		Going to line 39 of data.lua, we find:

	<pre style="background-color:#DDA0DD!important; color:black">		<pre style="background-color:#DDA0DD!important; color:black">
	~~recipe.enabled true~~		name = "fire-armor,
	</pre>		</pre>

	Hmm, that doesn't look right. Can you see what's missing? We left off an ~~= between enabled and true~~. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.		Hmm, that doesn't look right. Can you see what's missing? We left off an " after armor before the comma. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

	=== Illogical actions, indexing nil ===		=== Illogical actions, indexing nil ===