Tutorial:Modding tutorial/Gangsir - Revision history

Osmo: Change the very outdated Load order section

2026-09-12T09:56:17Z

Change the very outdated Load order section

← Older revision		Revision as of 09:56, 12 September 2026
Line 47:		Line 47:
	Within stages, mods are loaded by dependency, then by alphabetical order. This is ''very important'' to understand, as it can cause you problems if you neglect it and try to add inter-mod support to your mod.		Within stages, mods are loaded by dependency, then by alphabetical order. This is ''very important'' to understand, as it can cause you problems if you neglect it and try to add inter-mod support to your mod.

	Factorio has ~~three~~ kinds of dependencies. ~~There are required dependencies, and optional~~ dependencies. ~~The third kind~~, ~~restrictive dependencies, does not affect mod order and instead prevents the game from loading if~~ the other mod ~~is found. Required dependencies are~~ loaded first, ~~always~~. ~~The game~~ will ~~fail to initialize if one of these is~~ not present. ~~Optional~~ dependencies ~~are loaded first~~ if ~~present, but do not have to be~~ present. ~~This is useful for enabling bonus features if mods are used together. Required~~ dependencies ~~should~~ be used ~~for~~ mod ~~libraries~~, ~~and similar infrastructure~~.		Factorio has multiple kinds of dependencies, all of them documented [https://lua-api.factorio.com/latest/auxiliary/mod-structure.html#dependencies here].
			If your mod depends on another mod, the other mod will always be loaded first, unless you specified a load order unaffecting dependancy (<code>~</code>).
			Required dependencies can be used if your mod will not work without the other mod present.
			Incompatible dependencies will make the game error on startup if a mod marked incompatible by another mod is present.
			Optional and recommended dependencies can be used to change stuff in your mod, such as adding or removing certain recipes, when the other mod is present.

	=== The settings stage ===		=== The settings stage ===

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.