Official Factorio Wiki - User contributions [en]

Tutorial:Modding tutorial/Gangsir

2026-09-12T09:56:17Z

Osmo: Change the very outdated Load order section

{{Languages}}
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 ==
Before we start the tutorial, a few things to note:

<pre style="background-color:#AAFFAA!important; color:black">
Code tinted green like this should be included into the mod this tutorial is going to create; If the reader follows along with it. The best way to do this is to copy and paste, to ensure faithful reproduction.
Whenever code is added to the mod, a Lua comment with the file name will be at the beginning of the green box. Place the code in the box into that file. Eg:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Code tinted purple like this should not be included into the mod, it's just for educational/example purposes, and to boost understanding.
</pre>

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

Before we start the tutorial, a few terms and definitions should be laid out, to ensure the reader understands.

; Mod : A script or series of scripts that allow modifications to the game through the API.
; Entity : An entity in Factorio is anything in the game that is not a concept, event, or tile. Examples of entities include the character, an assembling machine, a biter, etc. This can be 'machines' or free-moving objects like the character.
; Character : The actual entity that the player manipulates the world through.
; Player : All the data that defines a player, such as username, online time or the current zoom level.
; Prototype : A prototype describes an instance of an entity, item or recipe etc, a bit like a template. It defines stats, like what an entity actually is, an item's stack size, a recipe's ingredients etc. A prototype is used to create an instance of an entity/item/etc, and many functionally identical entities/items/etc will use the same prototype.
; Surface : A surface is a bit like a dimension. It is composed of terrain, such as grass, sand, and water, and all the entities on the surface. By default, there is only one surface in Factorio, referred to internally as "nauvis", or <code style="background-color:#DDA0DD; color:black">game.surfaces[1]</code>, but mods may create additional surfaces through the API.
; Event : An event is a recurring...event, that is triggered internally by the game. There are several events that mods may connect functions to, such as <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, etc. More on this in the control scripting section.
; Item : Items are what is moved around in inventories, by inserters and on belts, etc. Each item in-game is an instance of the respective item prototype.

More terminology may be declared and defined later in this tutorial.

== Before beginning to mod ==

Before we can start modding Factorio, we must understand what Factorio is. You may be tempted to answer in lieu of the [[Factorio:About|about page]], but that is what a player would say. Since we are trying to become a modder, we need a more detailed explanation. Factorio is a game that is coded in the language C++, with an API provided by Wube (the developers of Factorio) to mod Factorio in the programming language Lua (version 5.2.1). This API allows adding scripts to the Factorio init process, to modify it without the source code of the base game being exposed, or modifying memory. This may be different than other games that offer modding, but this is a more professional and proper way of supporting modding.

To aid in the use of this API, the devs have kindly provided fairly comprehensive documentation of mods on at their [https://lua-api.factorio.com/latest/ API doc site]. Get used to using this site, as you will be frequently visiting it while you develop mods. The scripting API site contains information on [https://lua-api.factorio.com/latest/classes.html Factorio's classes] and information on [https://lua-api.factorio.com/latest/events.html events] that you can hook into. The [https://lua-api.factorio.com/latest/index-prototype.html prototype documentation] contains and links to information all around prototypes, listing their inheritance structure and their properties. You will need to check this site often, so the author recommends bookmarking it. In addition to this site, there are also many resources to be found created by the community, such as this tutorial.

=== Setup ===

The best way to develop a mod is to develop it in a place where it can be easily tested. When the tutorial gets to making the mod, this will be explained further. Additionally, using an editor that allows ease of typing and Lua language support is recommended. Emacs, Vim, Sublime Text, VSCode, and Notepad++ are all viable candidates.

== How Factorio loads mods ==

=== Load order ===
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 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 very first mod stage that is loaded when Factorio initializes is the settings stage. This stage is used to define all mod settings that are later shown in the in-game mod settings GUI, and has no other functions or possibilities. When running through this stage, the game looks through all mods for a file called <code>settings.lua</code>. After settings.lua has been executed for all mods, each mod's <code>settings-updates.lua</code> is executed, and finally each mod's <code>settings-final-fixes.lua</code> is called. These 3 different phases of the settings stage allow to change settings of other mods without needing to rely on dependencies to load last. All other files to be loaded will need to be required. All the files run here should contain nothing but setting definitions and code to produce setting definitions.

The settings stage does not have access to prototype or runtime data because it is loaded before those stages. The settings are expected to have a certain format, and all additional code will be discarded once the stage is over.

Mod settings are not covered in this tutorial, see [[Tutorial:Mod settings]] for further info on them.

=== The data stage ===

This is the most restricted part of the Factorio init, there's not much you can do here other than declare prototypes for technologies, entities, items and more. Things like manipulating files, affecting the world, etc, are blocked/unavailable. In fact, any functions or changes made will be discarded, as the lua session is terminated. You also cannot mess with the data table, it will error or be ignored. When using <code>data:extend({})</code>, it expects a specific format, more on this later.

When running through this stage, the game looks through all mods for a file called <code>data.lua</code>. After data.lua has been executed for all mods, each mod's <code>data-updates.lua</code> is executed, and finally each mod's <code>data-final-fixes.lua</code> is called. These 3 different phases of the data stage allow to change data of other mods without needing to rely on dependencies to load last. For example, the base mod creates barrelling recipes for all (then present) fluids in data-updates.lua. This means that if you add a fluid in data.lua, the base mod's data-updates.lua will add barreling recipes for it, regardless of whether your mod depends on base. Of course this also means that if you add a fluid in data-final-fixes.lua, it is created after the barrelling code runs in data-updates.lua, so no barrelling recipe gets created, even when desired. Because of this and similar mod interactions, it is recommended to create prototypes as early as possible. So, don't use data-final-fixes.lua to exclude a fluid from barreling, instead create it in data.lua and utilize "auto_barrel = false" on the fluid.

All other files to be loaded will need to be required. All the files run here should contain nothing but prototype definitions and code to produce prototype definitions. More on requiring files later.

All prototypes are documented on the modding API documentation website: [https://lua-api.factorio.com/latest/index-prototype.html Prototype documentation].

=== Migrations ===

[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 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 ===

Within most mods is a file called <code>control.lua</code>. This file contains scripting that makes the mod do things during the game, rather than just adding entities to the game. During this stage, each mod's control.lua is run, in it's own lua instance (this means no inter-communication without special setup) which it will own for the rest of the play session. During the play session, access to all tables provided by the game can be done inside of event handlers. (More on those below.) Because the control.lua is run every time a save file is created or loaded you don't need to restart the game to see changes made to the control.lua file. Simply restarting or reloading a save will re-run this stage. '''There are a few other caveats to this stage, reading the [https://lua-api.factorio.com/latest/auxiliary/data-lifecycle.html data life cycle] page on the API site provides the best overview.'''

The control stage documented is documented on [https://lua-api.factorio.com/latest/index-runtime.html lua-api.factorio.com].

== The major components to any Factorio mod ==

Within the average mod, there are several components that make the mod function.

Mods that define new entities will need to declare these entities in <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code>.

Mods with in-game effects will also need a <code>control.lua</code> file, to add scripting.

Mods with configurable user settings will use <code>settings.lua</code> to describe those settings.

Mods that define any game element with a readable name may also provide a <code>locale</code> directory and subdirectories with names/descriptions in one or more languages.

The mod that we'll make in this tutorial will include both data.lua prototypes and control.lua scripting, to give you a feel for both.

== The tutorial mod ==

And now for the moment you've been waiting for. Let's start making your first mod. You'll need:

* A recent install of Factorio
* A text editor, such as Emacs, Vim, Sublime Text, VSCode, or Notepad++.
* 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.

Once you have all of these things, we can begin.

For this mod, we're going to make a set of armor that leaves behind damaging fire behind you as you walk. It will be fully resistant to fire, but weaker towards physical damage than heavy armor, making it an armor for hit and run attacks.

=== Creation of the directory structure ===

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)
** mods
*** fire-armor

Then, inside fire-armor, create two files, <code>info.json</code> and <code>data.lua</code>. The directory should now look like:

* (user data directory, sometimes called .factorio)
** mods
*** fire-armor
**** data.lua
**** info.json

=== The info.json file ===

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">
{
"name": "fire-armor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"factorio_version": "2.0",
"dependencies": ["base >= 2.0"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

To explain each field:

{| class="wikitable"
! Item
! Explanation
|-
| name
| This is the internal name of your mod, it is used to identify your mod in code.
|-
| version
| This is the version of your mod. This can be anything you want, provided it's a of the format "number.number.number".
|-
| title
| The pretty title of your mod, this will be displayed on the mods screen and when you submit it to the mod portal.
|-
| author
| Your name! You can change this in the example above.
|-
| factorio_version
| 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
| Any dependencies of your mod.
|-
| description
| A short description of your mod, which appears in game. The mod portal is better for a long description.
|}

And that's all for info.json!

=== Prototype creation ===

Now, there are two ways to create prototypes in Factorio. There's the short way, and the long way. One way requires to create a complete prototype definition based on [https://lua-api.factorio.com/latest/index-prototype.html the documentation]. Another way uses a Lua function to copy and modify an already existing definition. For the sake of this tutorial, we'll do it both ways.

In the data.lua file, copy and paste the following:

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

local fireArmor = table.deepcopy(data.raw["armor"]["heavy-armor"]) -- copy the table that defines the heavy armor item into the fireArmor variable

fireArmor.name = "fire-armor"
fireArmor.icons = {
{
icon = fireArmor.icon,
icon_size = fireArmor.icon_size,
tint = {r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
}
}

-- create the recipe prototype from scratch
local recipe = {
type = "recipe",
name = "fire-armor",
enabled = true,
energy_required = 8, -- time to craft in seconds (at crafting speed 1)
ingredients = {
{type = "item", name = "copper-plate", amount = 200},
{type = "item", name = "steel-plate", amount = 50}
},
results = {{type = "item", name = "fire-armor", amount = 1}}
}

data:extend{fireArmor, recipe}

</pre>

What we've just done here is we've copied the definition of the heavy armor item, then changed its properties, and injected it into the Factorio init with data:extend. The first line of code is probably the most interesting. <code>table.deepcopy</code> copies a table fully into another table. We do this from data.raw. The <code>data</code> part is a table, which will be used by the game to setup the Factorio universe. In fact, it contains the function <code>extend(self, prototypes)</code> and a table called <code>raw</code>. The former is a customary way to add new stuff to the latter. It is actually data.raw that holds the prototypes for the game. (You can view the implementation in the file [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). It is important to note that data.raw only exists during the data loading stage of the game. During the control stage, when the game is running and being played, you cannot read this data; instead you read processed values through the API from the various types like LuaEntityPrototype.

In addition to defining the item prototype, we also define a recipe for it. This is necessary if you want to be able to craft the thing. We also set it to enabled so it doesn't need a technology to unlock.

=== More on data.raw ===

When Factorio initializes, all prototypes are put into a table called data.raw. This table holds all prototype types, and within those types, individual prototypes identified by name: <code>local prototype = data.raw["prototype-type"]["internal-name"]</code>. You saw earlier how we deepcopied from the definition of heavy armor, and modified some fields. In fact, let's go over each part of the deepcopy line:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw["armor"]["heavy-armor"])
</pre>

We assign a variable called fireArmor that holds our copy of the heavy armor definition. Notice how in data.raw, there is a type table that holds all armors, and the specific armor we're looking for is called heavy-armor. We can find [[heavy armor]]'s prototype type and internal name in the infobox of its page on this wiki and just copy it from there. 
Alternatively, we can find the items prototype type and internal name by opening the game, inserting the item into our inventory and then pressing {{Keybinding|shift|ctrl|F}} while hovering over the item. This will open the prototype explorer GUI, which has rows showing the name and type of the item.

As another example, the [[player|character]]'s prototype would be, according to the infobox on the page:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw["character"]["character"]
</pre>

Because the character is ''the'' character, his type matches his name. You could define a new character with a mod. You can see all the available prototype fields of the character in the documentation: [https://lua-api.factorio.com/latest/prototypes/CharacterPrototype.html CharacterPrototype].

You may be thinking at this point, "Can I modify Factorio's existing prototypes without making new ones?" Well, the answer is yes! You would simply access the data.raw table during init, in data-final-fixes.lua if you want to run after all other mods, and change a property. For example, make the iron chest instead have 1000 health:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw["container"]["iron-chest"].max_health = 1000
</pre>

The reason why this code is in data-final-fixes.lua is because that is the last file run, after all mod files have been run. This prevents (to a degree) your changes from being messed with by other mods. Of course, it is still possible to have incompatibilities. You should note any that you know of in your mod's description. Again, the [https://lua-api.factorio.com/latest/auxiliary/data-lifecycle.html dev's documentation] on this should be looked at.

This can also be applied to other mods, not just Factorio's base. You could mod a mod, as long as you add the mod (that you modified with your mod) to your dependencies so it gets loaded first.

=== The control scripting ===

And now, to finalize the mod, we have to make it be more than just simple armor. Let's think about what we want the armor to do. We want the armor to create fire on the ground as we walk with the armor on. The event we're going to use is called [https://lua-api.factorio.com/latest/events.html#on_player_changed_position on_player_changed_position], since we want the fire to be created when the player moves.

In our mod folder, create a file called <code>control.lua</code>. The game will automatically execute this file, so requiring it is not necessary.

Inside control.lua, copy and paste the following:

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

script.on_event(defines.events.on_player_changed_position,
function(event)
local player = game.get_player(event.player_index) -- get the player that moved
-- if they're currently controlling the character
if player.controller_type == defines.controllers.character then
-- and wearing our armor
if player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
-- create the fire where they're standing
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
)

</pre>

I've used lua comments in the code above to explain each step. It's fairly easy to understand, and it shows how you would get the current armor that the player character is wearing, with defines.inventory.character_armor, which is an inventory constant. You can read the list of defines [https://lua-api.factorio.com/latest/defines.html#defines.inventory here].

=== Locale ===

If you've already tried loading up Factorio and trying the mod so far (which you can at this point without it crashing), you may have noticed that the item name of the armor says "Unknown key". This means that Factorio has the internal name, but it doesn't know what it should look like to the user. So, we need to create a locale for our mod.

In the mod folder, create a folder called <code>locale</code>, then create another folder inside that called <code>en</code>, then a file called <code>any_name_can_be_here.cfg</code>.

If you know another language, you can also translate your mod by making other language code files inside locale, such as de for German.

Inside the .cfg file, paste the following:

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

[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Notice how this is not a lua file. Locale is handled with C config files, so the format is different.

== The finished tutorial mod ==

Well, the mod is finished. Since this mod is only a tutorial, there isn't much balance to it.

If you want to share a mod with other users, it needs to be a zip file. For that, simply zip the <code>fire-armor</code> folder and then rename the archive to <code>fire-armor_0.1.0</code> so that it follows the expected mod zip name pattern of <code>mod-name_version</code>. Keep in mind to not submit this tutorial mod to the mod portal as your own, since it's from the Wiki.

However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.

== Extended learning ==
One of the best ways to learn how to mod beyond this is to look at other mods. The [[Tutorial:Inspecting a live mod]] is a good starting point for touring a particularly well-commented mod. As all mods can be opened and inspected, looking at the mods of experienced modders can help significantly when making your own mod.

Something you'll see a lot in other mods or the base game are <code>require</code> statements. These load other files, so you can split up long code files and organize your mod however you like.

For example, if you wanted to put some of your data stage code into a file called "foo.lua" in a folder called "bar", your mod folder would look like this:

* fire-armor
** bar
*** foo.lua
** data.lua
** control.lua
** info.json

And you would need to add this to data.lua:
<pre style="background-color:#DDA0DD!important; color:black">
require("bar.foo")
</pre>

=== Keeping your mod working ===
As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

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

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mod "fire-armor": __fire-armor__/data.lua:39: unfinished string near '"fire-armor,'
</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?

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 39 of data.lua, we find:

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

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

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event fire-armor::on_player_changed_position (ID 82)
__fire-armor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [https://lua-api.factorio.com/latest/LuaPlayer.html A player] is a table of several values. Trying to print it simply print "LuaPlayer" instead of providing useful data.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event fire-armor::on_player_changed_position (ID 82)
Unknown entity name: fire-flam
stack traceback:
__fire-armor__/control.lua:7: in function <__fire-armor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 7 of control.lua, inside of an on_player_changed_position event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:190: Map tick at moment of crash: 432029
696.148 Error Util.cpp:97: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
Please also include the save file(s), any mods you may be using, and any steps you know of to reproduce the crash.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</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/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 ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [https://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* 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.

=== Comparison by reference ===

Be cautious of comparing tables by reference. In multiplayer syncing, tables deserialized from the server state will be new objects, not equal by reference to any table initialized by client code.

<pre style="background-color:#DDA0DD!important; color:black">
if a == b then
</pre>
<pre style="background-color:#DDA0DD!important; color:black">
if a ~= b then
</pre>
If <code>a</code> and <code>b</code> are tables in the above conditionals, there will for example be different results between server and client if <code>a</code> is created locally and <code>b</code> is downloaded from the server.

Note that LuaObjects provided by the game have their equality operator overwritten to prevent this behaviour, so code such as <code>LuaEntityA ~= LuaEntityB</code> will not desync.
However, this does not apply when LuaObjects are used as keys in tables:
<pre style="background-color:#DDA0DD!important; color:black">
if table[LuaObject] then
</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 ==
* [[Modding]]
* [[Tutorial:Modding tutorial|Modding tutorial overview]]

[[Category:Modding]]

Tutorial:Localisation

2026-06-10T11:37:49Z

Osmo: /* Default Behavior(s) for finding an Unspecified Localised String */ Improve this whole section, add rules for recipes and technologies. Remove "and is not an empty table" because empty tables are not valid localised strings (at least anymore).

{{Languages}}Mods should define human readable names for prototypes that they add. They can also define descriptions for items or custom strings for usage in GUIs etc. This is called '''localisation'''.

== File format ==
Translations are stored as .cfg files, with the following format:

<pre>welcome-message=Hello world
[category]
title=Category related title
# Comment
; Another comment</pre>
Any whitespace after or before <code>=</code> is included in the key or string, so <code>title =Category related title</code> will give an unknown key error if you are looking for the <code>title</code> key, since it is the <code>title </code> key.

<code>category</code> can be one of the existing locale categories, which permits implicit search mechanisms to find translations, but may also be another key, such as <code>[my-mod-messages]</code>. These are accessible the same as other translations, e.g. <code>{"my-mod-messages.hello"}</code>

These files are located within the language code of the language in the locale folder of the mod, so as an English example <code>__mod__/locale/en/any_name_here.cfg</code>. There can be more than 1 file per language, all of them will be read.

== Localising simple strings ==
The simplest localisation is of items, entities etc. If we say the item is <code>iron-plate</code>, the game will then search all loaded locale files for <code>item-name.iron-plate</code> and <code>item-description.iron-plate</code>, which in the locale file looks like this:

<pre>[item-name]
iron-plate=Iron plate
[item-description]
iron-plate=A plate made of iron.</pre>
If found in the locale, the label is set to this string. If not found, the game will instead show: <code>Unknown key: "item-name.iron-plate"</code>

In script, the localised string is formatted as <code>{"category.name"}</code>, so <code>game.print({"item-name.iron-plate"})</code> prints ''Iron plate''.

It is possible to use [[rich text]] features in the localised text if the location where the text is shown supports it, e.g. in the chat, prototype names and prototype tooltips.

<code>\n</code> can be used for line breaks if the location where the text is shown supports multiline text.

The list of all localization categories used by the base game is:

{| class="mw-collapsible mw-collapsed wikitable"
|-
!Localization categories
|-
|<code>[achievement-description]</code>
|-
|<code>[achievement-name]</code>
|-
|<code>[ammo-category-name]</code>
|-
|<code>[autoplace-control-names]</code>
|-
|<code>[controls]</code>
|-
|<code>[damage-type-name]</code>
|-
|<code>[decorative-name]</code>
|-
|<code>[entity-description]</code>
|-
|<code>[entity-name]</code>
|-
|<code>[equipment-name]</code>
|-
|<code>[fluid-name]</code>
|-
|<code>[fuel-category-name]</code>
|-
|<code>[item-description]</code>
|-
|<code>[item-group-name]</code>
|-
|<code>[item-limitation]</code>
|-
|<code>[item-name]</code>
|-
|<code>[map-gen-preset-description]</code>
|-
|<code>[map-gen-preset-name]</code>
|-
|<code>[mod-description]</code>
|-
|<code>[mod-name]</code>
|-
|<code>[modifier-description]
|-
|<code>[programmable-speaker-instrument]</code>
|-
|<code>[programmable-speaker-note]</code>
|-
|<code>[recipe-name]</code>
|-
|<code>[shortcut-name]</code>
|-
|<code>[story]</code>
|-
|<code>[string-mod-setting]</code>
|-
|<code>[technology-description]</code>
|-
|<code>[technology-name]</code>
|-
|<code>[tile-name]</code>
|-
|<code>[tips-and-tricks-item-description]</code>
|-
|<code>[tips-and-tricks-item-name]</code>
|-
|<code>[virtual-signal-description]</code>
|-
|<code>[virtual-signal-name]</code>
|}

== Localising with parameters ==
For more complex strings, localisation parameters can be used. For instance we want to show ''Time left: 10 minutes.''

So a key with a placeholder is defined, which is replaced by the first parameter after the locale key.:

<pre>time-left=Time left: __1__ minutes.</pre>
So it is used like this:

<syntaxhighlight lang="lua">game.print({"time-left", 10})</syntaxhighlight>
It also works with multiple parameters:

<syntaxhighlight lang="lua">game.print({"time-left", 10, 45})</syntaxhighlight>
<pre>time-left=Time left: __1__ minutes and __2__ seconds.</pre>
Which results in ''Time left: 10 minutes and 45 seconds.''

=== Built-in parameters ===
For some situations, we use localisation to show control schemes. For instance we want to say:

<pre>technology-prompt=Use T to open the technology screen</pre>
However the player may have rebound the key, but we can’t figure out which key as it would not be deterministic. So instead we use the built-in replacement functionality

<pre>technology-prompt=Use __CONTROL__open-technology-gui__ to open the technology screen.</pre>
We can also use this for items and entities:

<pre>big-iron-plate=Big __ITEM__iron-plate__</pre>
<pre>tiny-gun-turret=Tiny __ENTITY__gun-turret__</pre>

==== List of built-in parameters ====
<code>name</code> is the name of an internal game control or a prototype name, depending on context. <code>n</code> can be 1 or 2, it's used in parameters that control [[#Localising_alternate_input_names|alternate input names]]. For a list of internal game control names, see [https://lua-api.factorio.com/latest/types/LinkedGameControl.html CustomInputPrototype::linked_game_control].
* <code>__CONTROL__name__</code> - The combination of modifiers and input, such as "Control + Alt + Left-click", or "Not set".
* <code>__CONTROL_MODIFIER__name__</code> - The modifiers, such as "ControlShift", or, "No modifier selected."
* <code>__CONTROL_STYLE_BEGIN__</code>
* <code>__CONTROL_STYLE_END__</code>
* <code>__CONTROL_LEFT_CLICK__</code> is replaced with <code>control-keys.mouse-button-1</code> or <code>control-keys.controller-b</code>[https://crowdin.com/project/factorio/discussions/214]
* <code>__CONTROL_RIGHT_CLICK__</code> is replaced with <code>control-keys.mouse-button-2</code> or <code>control-keys.controller-x</code>
* <code>__CONTROL_KEY_SHIFT__</code> is replaced with <code>control-keys.shift</code> or <code>control-keys.controller-leftshoulder</code>
* <code>__CONTROL_KEY_CTRL__</code> is replaced with <code>control-keys.control</code> or <code>control-keys.controller-rightshoulder</code>
* <code>__ALT_CONTROL_LEFT_CLICK__n__</code> is replaced with <code>control-keys.mouse-button-1-alt-n</code> or <code>control-keys.controller-button-alt-n</code> (with parameter <code>control-keys.controller-b</code>)
* <code>__ALT_CONTROL_RIGHT_CLICK__n__</code> is replaced with <code>control-keys.mouse-button-2-alt-n</code> or <code>control-keys.controller-button-alt-n</code> (with parameter <code>control-keys.controller-x</code>)
* <code>__ALT_CONTROL__n__name__</code>
* <code>__CONTROL_MOVE__</code> - The Movement keys, squished together. Example: "WASD", from a conventional QWERTY English keyboard.
* <code>__REMARK_COLOR_BEGIN__</code>
* <code>__REMARK_COLOR_END__</code>
* <code>__ENTITY__name__</code> - The localised name of the [https://lua-api.factorio.com/latest/prototypes/EntityPrototype.html EntityPrototype] subclass.
* <code>__FLUID__name__</code> - The localised name of the [https://lua-api.factorio.com/latest/prototypes/FluidPrototype.html FluidPrototype].
* <code>__ITEM__name__</code> - The localised name of the [https://lua-api.factorio.com/latest/prototypes/ItemPrototype.html ItemPrototype] or subclass.
* <code>__PLANET__name__</code> - The localised name of the [https://lua-api.factorio.com/latest/prototypes/SpaceLocationPrototype.html SpaceLocationPrototype] or subclass.
* <code>__TILE__name__</code> - The localised name of the [https://lua-api.factorio.com/latest/prototypes/TilePrototype.html TilePrototype].

=== Plurals ===
Pluralization can be used in any string that uses a parameter (e.g. __1__) that is numeric, so something like an amount of minutes. It can be used multiple times per string.

<pre>format-days=__1__ __plural_for_parameter__1__{1=day|rest=days}__</pre>
This results in "1 day" and "2 days" / "500 days" etc.

The number after <code>__plural_for_parameter__</code> denotes which parameter is used to determine the plural. This is the parameter 1 in the above example. Anything inside the {} is used to make the plural. Each plural form is separated by a |.
The text in front of the = determines for what the plural form is used. Options for this are:
* A simple number, e.g. "1".
* Multiple numbers, e.g. "2,3,4".
* What the number ends with, e.g. "ends in 11" or "ends in 1"
* Multiple ends with, e.g. "ends in 1,ends in 2,ends in 12".
* "decimal" for any number with a fractional part.
* "rest" to give the default plural.

For negative numbers the plural is picked as if the number was positive, so a plural like <code>__plural_for_parameter__1__{1=day|rest=days}__</code> will result in "-1 day" for -1. 
For numbers with a SI prefix the plural is picked as if the number was fully written out, so a plural like <code>__plural_for_parameter__1__{1=day|1000=eons|rest=days}__</code> will result in "1k eons" for 1k.

Plural forms may be empty or contain other keys such as __1__ or spaces. This allows rather large plural forms:

<pre>__plural_for_parameter__1__{1=__1__ player is|rest=__1__ players are}__ connecting</pre>

The system picks the first fitting plural that it encounters when multiple would fit:
<pre>__plural_for_parameter__1__{ends in 12=option 1|ends in 2=option 2|rest=option 3}__</pre>
This will result in "option 1" for 12 and in "option 2" for 22 and in "option 3" for numbers not ending with 2.

The parameter used for pluralisation does not need to be present in the string. For example, a parameter could represent the number of list items present in another parameter:
<pre>
I like __plural_for_parameter__1__{1=only one thing:|rest=these things:} __2__
</pre>
Can result in "I like only one thing: trains", or in "I like these things: trains and turtles".

=== Concatenating localised strings ===
The special locale key: <code>""</code> is used to concatenate, as the table format does not support concatenation:

<syntaxhighlight lang="lua">game.print({"", {"item-name.iron-plate"}, ": ", 60})</syntaxhighlight>
Will result in: ''Iron plate: 60''

=== Advanced concatenation and modification existing localised strings ===

When working with LocalisedString tables in prototype definitions (e.g., in data.lua, data-updates.lua, or data-final-fixes.lua), there are several important rules and practical patterns:

'''All parameters must be strings'''

At the prototype data stage, every parameter passed to a localised string must be a string. Numbers, booleans, or other types will cause a Value must be a string error.

<syntaxhighlight lang="lua">-- This will cause an error:
localised_description = {"description.example", 42}

-- Correct:
localised_description = {"description.example", "42"}
-- or using tostring():
localised_description = {"description.example", tostring(42)}</syntaxhighlight>

This applies to numeric values from prototype properties as well:
<syntaxhighlight lang="lua">-- Wrong:
localised_description = {"description.radar-range", prototype.max_distance}

-- Correct:
localised_description = {"description.radar-range", tostring(prototype.max_distance)}</syntaxhighlight>

'''Appending lines to existing descriptions'''

When modifying a prototype that already has a localised_description (e.g., from another mod), use the <code>""</code> (empty string) key for concatenation with newline separators. Here is a practical function that safely appends a new line while preserving existing content:
<syntaxhighlight lang="lua">
local function append_localised_line(target, new_line)
if not target.localised_description then
target.localised_description = new_line
return
end

local result = {""} -- concatenation key
local idx = 2

local function flatten(desc)
if type(desc) == "string" then
result[idx] = desc
idx = idx + 1
elseif type(desc) == "table" then
-- Skip the key if present
if desc[1] == "" or desc[1] == "?" then
for i = 2, #desc do
flatten(desc[i])
end
else
result[idx] = desc
idx = idx + 1
end
end
end

flatten(target.localised_description)
result[idx] = "\n"
idx = idx + 1
result[idx] = new_line

target.localised_description = result
end

-- Usage:
append_localised_line(radar_prototype, {"description.radar-range", tostring(range)})

--Examples of modifying existing localised strings

--Example 1: Adding line if localised_description == nil
local entity = data.raw["assembling-machine"]["assembling-machine-3"]
append_localised_line(entity, {"description.building-size", "3.0", "3.0"})
--Result:
-- entity.localised_description = {"description.building-size", "3.0", "3.0"}

--Example 2: Adding a second line
append_localised_line(entity, {"description.max-health", "500"})
--Result:
-- entity.localised_description = {
-- "",
-- {"description.building-size", "3.0", "3.0"},
-- "\n",
-- {"description.max-health", "500"}
-- }

--Final in-game display (with localization):
--Size: 3.0x3.0
--Max health: 500
</syntaxhighlight>

'''Error interpretation'''

When a LocalisedString error occurs, note that the property tree error messages use 0-based indexing, while Lua tables use 1-based indexing. An error pointing to '''[2][1]''' refers to the element at index '''3''' in your Lua table, then its element at index '''2'''.

=== Localising alternate input names ===

In the introduction campaign, a special locale system is used for informing players how to do certain actions with their mouse.
The normal form is to use eg:
<pre>how-to-build=Use __CONTROL__build__ to place a building</pre>
which results in "Use Left mouse button to place a building". A more natural phrasing would be "Left-click to place a building", which can be achieved by using the following:
<pre>how-to-build=__ALT_CONTROL__1__build__ to place a building</pre>

These "alt" versions are controlled by a few special locale keys, mouse-button-X-alt-1 and mouse-button-X-alt-2. In English, form 1 produces eg "Left-click", and form 2 produces eg "Left-clicking". Only two alt forms ("1" and "2") are available at the moment, but if this a problem for some languages, more forms may be added in the future.
Extra mouse buttons, mouse scroll and keyboard keys are handled through the mouse-button-n-alt-1/2, mouse-wheel-alt-1/2 and keyboard-alt-1/2 keys, which just take the normal name and prepend something like "Press/Pressing", or "Scroll/Scrolling".

When translating to another language, you can use whatever forms you want here, but the important part is that you are consistent when you use the alt-forms everywhere else. It does not necessarily make sense to just copy the usages of alt forms from the English locale, and for some languages it may be more natural to simply not use this system at all.

== Accessing the localised result in code ==
While usually unneeded, it is possible to read the resulting localised text in code, for example to search in localised names.

See
[https://lua-api.factorio.com/latest/classes/LuaPlayer.html#request_translation LuaPlayer::request_translation],
[https://lua-api.factorio.com/latest/classes/LuaPlayer.html#request_translations LuaPlayer::request_translations] and
[https://lua-api.factorio.com/latest/events.html#on_string_translated on_string_translated event].

== Default Behavior(s) for finding an Unspecified Localised String ==
If a localised_name or localised_description is not defined in the prototype, Factorio may have a default search behavior.

Note: the angle brackets are meant to mean a generic term, they are not part of the actual string.

For most types, the name defaults to {"<base type>-name.<prototype name>"}, for example {"entity-name.underground-belt"}

Similarly, the description defaults to {"<base type>-description.<prototype name>"}, for example {"entity-description.underground-belt"}

Base types are represented by [https://lua-api.factorio.com/latest/concepts/IDType.html IDType].

=== Items ===
For items, the process is more complicated.

Note: place_result and placed_as_equipment_result are strings, and and Factorio fetches the matching prototype to examine.

# if localised_name is provided in the item prototype, use the provided value
# else if there is a place_result and it has a localised_name, use the localised_name of place_result
# else if there is a place_result, use {"entity-name.<place_result name>"}
# else if there is placed_as_equipment_result and it has a localised_name, use the localised_name of placed_as_equipment_result
# else if there is placed_as_equipment_result, use {"equipment-name.<place_as_equipment_result name>"}
# else use {"item-name.<item name>"}

Descriptions of items are found in the same way, except localised_description is used instead of localised_name and <base type>-description is used instead of <base type>-name.

Example: The transport-belt item does not have a localised_name, so 1->2.
There is a place result, but the entity prototype does not have localised_name set, 2->3.
There is a place result, so use the localised string {"entity-name.transport-belt"}.

Reference: [https://forums.factorio.com/viewtopic.php?p=494243#p494243]

=== Recipes ===
# if localised_name is provided in the recipe prototype, use the provided value
# else if main_product is set to an empty string: "", use {"recipe-name.<recipe name>"}
# else if main_product is set or recipe only has a single product:
#:# if the main product or only product has the same name as the recipe, use the localised name of the product. For item products, this uses the rules described in [[#Items]].
#:# else use {"recipe-name.<recipe name>"}
# else use {"recipe-name.<recipe name>"}
Descriptions of recipes have no special rules.

Reference: [https://lua-api.factorio.com/latest/prototypes/RecipePrototype.html#main_product]

=== Technologies ===
If localised_name is provided in the technology prototype, the provided value is used.
Otherwise, if the name of a technology ends with -<number>, that number is ignored for localisation purposes.
E.g. if the name is technology-3, the localised name defaults to {"technology-name.technology"} and the localised description defaults to {"technology-description.technology"}.

Reference: [https://lua-api.factorio.com/latest/prototypes/TechnologyPrototype.html#name]

== See also ==
* [https://lua-api.factorio.com/latest/types/LocalisedString.html LocalisedString data stage doc]
* [https://lua-api.factorio.com/latest/concepts/LocalisedString.html LocalisedString control stage doc]

[[Category:Modding]]

Tutorial:Localisation

2026-06-08T12:35:37Z

Osmo: Undo revision 218718 by Osmo (talk) since it was prematurely saved

{{Languages}}Mods should define human readable names for prototypes that they add. They can also define descriptions for items or custom strings for usage in GUIs etc. This is called '''localisation'''.

== File format ==
Translations are stored as .cfg files, with the following format:

<pre>welcome-message=Hello world
[category]
title=Category related title
# Comment
; Another comment</pre>
Any whitespace after or before <code>=</code> is included in the key or string, so <code>title =Category related title</code> will give an unknown key error if you are looking for the <code>title</code> key, since it is the <code>title </code> key.

<code>category</code> can be one of the existing locale categories, which permits implicit search mechanisms to find translations, but may also be another key, such as <code>[my-mod-messages]</code>. These are accessible the same as other translations, e.g. <code>{"my-mod-messages.hello"}</code>

These files are located within the language code of the language in the locale folder of the mod, so as an English example <code>__mod__/locale/en/any_name_here.cfg</code>. There can be more than 1 file per language, all of them will be read.

== Localising simple strings ==
The simplest localisation is of items, entities etc. If we say the item is <code>iron-plate</code>, the game will then search all loaded locale files for <code>item-name.iron-plate</code> and <code>item-description.iron-plate</code>, which in the locale file looks like this:

<pre>[item-name]
iron-plate=Iron plate
[item-description]
iron-plate=A plate made of iron.</pre>
If found in the locale, the label is set to this string. If not found, the game will instead show: <code>Unknown key: "item-name.iron-plate"</code>

In script, the localised string is formatted as <code>{"category.name"}</code>, so <code>game.print({"item-name.iron-plate"})</code> prints ''Iron plate''.

It is possible to use [[rich text]] features in the localised text if the location where the text is shown supports it, e.g. in the chat, prototype names and prototype tooltips.

<code>\n</code> can be used for line breaks if the location where the text is shown supports multiline text.

The list of all localization categories used by the base game is:

{| class="mw-collapsible mw-collapsed wikitable"
|-
!Localization categories
|-
|<code>[achievement-description]</code>
|-
|<code>[achievement-name]</code>
|-
|<code>[ammo-category-name]</code>
|-
|<code>[autoplace-control-names]</code>
|-
|<code>[controls]</code>
|-
|<code>[damage-type-name]</code>
|-
|<code>[decorative-name]</code>
|-
|<code>[entity-description]</code>
|-
|<code>[entity-name]</code>
|-
|<code>[equipment-name]</code>
|-
|<code>[fluid-name]</code>
|-
|<code>[fuel-category-name]</code>
|-
|<code>[item-description]</code>
|-
|<code>[item-group-name]</code>
|-
|<code>[item-limitation]</code>
|-
|<code>[item-name]</code>
|-
|<code>[map-gen-preset-description]</code>
|-
|<code>[map-gen-preset-name]</code>
|-
|<code>[mod-description]</code>
|-
|<code>[mod-name]</code>
|-
|<code>[modifier-description]
|-
|<code>[programmable-speaker-instrument]</code>
|-
|<code>[programmable-speaker-note]</code>
|-
|<code>[recipe-name]</code>
|-
|<code>[shortcut-name]</code>
|-
|<code>[story]</code>
|-
|<code>[string-mod-setting]</code>
|-
|<code>[technology-description]</code>
|-
|<code>[technology-name]</code>
|-
|<code>[tile-name]</code>
|-
|<code>[tips-and-tricks-item-description]</code>
|-
|<code>[tips-and-tricks-item-name]</code>
|-
|<code>[virtual-signal-description]</code>
|-
|<code>[virtual-signal-name]</code>
|}

== Localising with parameters ==
For more complex strings, localisation parameters can be used. For instance we want to show ''Time left: 10 minutes.''

So a key with a placeholder is defined, which is replaced by the first parameter after the locale key.:

<pre>time-left=Time left: __1__ minutes.</pre>
So it is used like this:

<syntaxhighlight lang="lua">game.print({"time-left", 10})</syntaxhighlight>
It also works with multiple parameters:

<syntaxhighlight lang="lua">game.print({"time-left", 10, 45})</syntaxhighlight>
<pre>time-left=Time left: __1__ minutes and __2__ seconds.</pre>
Which results in ''Time left: 10 minutes and 45 seconds.''

=== Built-in parameters ===
For some situations, we use localisation to show control schemes. For instance we want to say:

<pre>technology-prompt=Use T to open the technology screen</pre>
However the player may have rebound the key, but we can’t figure out which key as it would not be deterministic. So instead we use the built-in replacement functionality

<pre>technology-prompt=Use __CONTROL__open-technology-gui__ to open the technology screen.</pre>
We can also use this for items and entities:

<pre>big-iron-plate=Big __ITEM__iron-plate__</pre>
<pre>tiny-gun-turret=Tiny __ENTITY__gun-turret__</pre>

==== List of built-in parameters ====
<code>name</code> is the name of an internal game control or a prototype name, depending on context. <code>n</code> can be 1 or 2, it's used in parameters that control [[#Localising_alternate_input_names|alternate input names]]. For a list of internal game control names, see [https://lua-api.factorio.com/latest/types/LinkedGameControl.html CustomInputPrototype::linked_game_control].
* <code>__CONTROL__name__</code> - The combination of modifiers and input, such as "Control + Alt + Left-click", or "Not set".
* <code>__CONTROL_MODIFIER__name__</code> - The modifiers, such as "ControlShift", or, "No modifier selected."
* <code>__CONTROL_STYLE_BEGIN__</code>
* <code>__CONTROL_STYLE_END__</code>
* <code>__CONTROL_LEFT_CLICK__</code> is replaced with <code>control-keys.mouse-button-1</code> or <code>control-keys.controller-b</code>[https://crowdin.com/project/factorio/discussions/214]
* <code>__CONTROL_RIGHT_CLICK__</code> is replaced with <code>control-keys.mouse-button-2</code> or <code>control-keys.controller-x</code>
* <code>__CONTROL_KEY_SHIFT__</code> is replaced with <code>control-keys.shift</code> or <code>control-keys.controller-leftshoulder</code>
* <code>__CONTROL_KEY_CTRL__</code> is replaced with <code>control-keys.control</code> or <code>control-keys.controller-rightshoulder</code>
* <code>__ALT_CONTROL_LEFT_CLICK__n__</code> is replaced with <code>control-keys.mouse-button-1-alt-n</code> or <code>control-keys.controller-button-alt-n</code> (with parameter <code>control-keys.controller-b</code>)
* <code>__ALT_CONTROL_RIGHT_CLICK__n__</code> is replaced with <code>control-keys.mouse-button-2-alt-n</code> or <code>control-keys.controller-button-alt-n</code> (with parameter <code>control-keys.controller-x</code>)
* <code>__ALT_CONTROL__n__name__</code>
* <code>__CONTROL_MOVE__</code> - The Movement keys, squished together. Example: "WASD", from a conventional QWERTY English keyboard.
* <code>__REMARK_COLOR_BEGIN__</code>
* <code>__REMARK_COLOR_END__</code>
* <code>__ENTITY__name__</code> - The localised name of the [https://lua-api.factorio.com/latest/prototypes/EntityPrototype.html EntityPrototype] subclass.
* <code>__FLUID__name__</code> - The localised name of the [https://lua-api.factorio.com/latest/prototypes/FluidPrototype.html FluidPrototype].
* <code>__ITEM__name__</code> - The localised name of the [https://lua-api.factorio.com/latest/prototypes/ItemPrototype.html ItemPrototype] or subclass.
* <code>__PLANET__name__</code> - The localised name of the [https://lua-api.factorio.com/latest/prototypes/SpaceLocationPrototype.html SpaceLocationPrototype] or subclass.
* <code>__TILE__name__</code> - The localised name of the [https://lua-api.factorio.com/latest/prototypes/TilePrototype.html TilePrototype].

=== Plurals ===
Pluralization can be used in any string that uses a parameter (e.g. __1__) that is numeric, so something like an amount of minutes. It can be used multiple times per string.

<pre>format-days=__1__ __plural_for_parameter__1__{1=day|rest=days}__</pre>
This results in "1 day" and "2 days" / "500 days" etc.

The number after <code>__plural_for_parameter__</code> denotes which parameter is used to determine the plural. This is the parameter 1 in the above example. Anything inside the {} is used to make the plural. Each plural form is separated by a |.
The text in front of the = determines for what the plural form is used. Options for this are:
* A simple number, e.g. "1".
* Multiple numbers, e.g. "2,3,4".
* What the number ends with, e.g. "ends in 11" or "ends in 1"
* Multiple ends with, e.g. "ends in 1,ends in 2,ends in 12".
* "decimal" for any number with a fractional part.
* "rest" to give the default plural.

For negative numbers the plural is picked as if the number was positive, so a plural like <code>__plural_for_parameter__1__{1=day|rest=days}__</code> will result in "-1 day" for -1. 
For numbers with a SI prefix the plural is picked as if the number was fully written out, so a plural like <code>__plural_for_parameter__1__{1=day|1000=eons|rest=days}__</code> will result in "1k eons" for 1k.

Plural forms may be empty or contain other keys such as __1__ or spaces. This allows rather large plural forms:

<pre>__plural_for_parameter__1__{1=__1__ player is|rest=__1__ players are}__ connecting</pre>

The system picks the first fitting plural that it encounters when multiple would fit:
<pre>__plural_for_parameter__1__{ends in 12=option 1|ends in 2=option 2|rest=option 3}__</pre>
This will result in "option 1" for 12 and in "option 2" for 22 and in "option 3" for numbers not ending with 2.

The parameter used for pluralisation does not need to be present in the string. For example, a parameter could represent the number of list items present in another parameter:
<pre>
I like __plural_for_parameter__1__{1=only one thing:|rest=these things:} __2__
</pre>
Can result in "I like only one thing: trains", or in "I like these things: trains and turtles".

=== Concatenating localised strings ===
The special locale key: <code>""</code> is used to concatenate, as the table format does not support concatenation:

<syntaxhighlight lang="lua">game.print({"", {"item-name.iron-plate"}, ": ", 60})</syntaxhighlight>
Will result in: ''Iron plate: 60''

=== Localising alternate input names ===

In the introduction campaign, a special locale system is used for informing players how to do certain actions with their mouse.
The normal form is to use eg:
<pre>how-to-build=Use __CONTROL__build__ to place a building</pre>
which results in "Use Left mouse button to place a building". A more natural phrasing would be "Left-click to place a building", which can be achieved by using the following:
<pre>how-to-build=__ALT_CONTROL__1__build__ to place a building</pre>

These "alt" versions are controlled by a few special locale keys, mouse-button-X-alt-1 and mouse-button-X-alt-2. In English, form 1 produces eg "Left-click", and form 2 produces eg "Left-clicking". Only two alt forms ("1" and "2") are available at the moment, but if this a problem for some languages, more forms may be added in the future.
Extra mouse buttons, mouse scroll and keyboard keys are handled through the mouse-button-n-alt-1/2, mouse-wheel-alt-1/2 and keyboard-alt-1/2 keys, which just take the normal name and prepend something like "Press/Pressing", or "Scroll/Scrolling".

When translating to another language, you can use whatever forms you want here, but the important part is that you are consistent when you use the alt-forms everywhere else. It does not necessarily make sense to just copy the usages of alt forms from the English locale, and for some languages it may be more natural to simply not use this system at all.

== Accessing the localised result in code ==
While usually unneeded, it is possible to read the resulting localised text in code, for example to search in localised names.

See
[https://lua-api.factorio.com/latest/classes/LuaPlayer.html#request_translation LuaPlayer::request_translation],
[https://lua-api.factorio.com/latest/classes/LuaPlayer.html#request_translations LuaPlayer::request_translations] and
[https://lua-api.factorio.com/latest/events.html#on_string_translated on_string_translated event].

== Default Behavior(s) for finding an Unspecified Localised String ==
If a localised_string is not defined in the prototype for certain prototype classes, e.g. entity, item, Factorio may have a default search behavior.

Determining an item's localised name:
Note: the angle brackets are meant to mean a generic term, they are not part of the actual string. Also, place_result and placed_as_equipment_result are strings, and Factorio fetches the matching prototype to examine.

# if localised_name is provided in the item prototype and it is not empty {}, use the provided value
# else if there is place_result and it has localised_name that is not an empty table: {}, use the localised_name of place_result
# else if there is place_result with an empty localised_name, use {"entity-name.<entity prototype name>"}
# else if there is placed_as_equipment_result and it has a localised_name that is not an empty table: {}, use the localised_name of placed_as_equipment_result
# else if there is placed_as_equipment_result with empty localised_name, use {"equipment-name.<equipment name>"}
# else use default {"item-name.<item name>"}

Reference: [https://forums.factorio.com/viewtopic.php?p=494243#p494243]

Example: The transport-belt item does not have a localised_name, so 1->2. There is a place result, but not localised_name in the entity prototype. 2->3. The place result lacks a localised_name. Use the localised string {"entity-name.transport-belt"}

Such defaults often include a "leading key" using [<group>-name] or [<group>-description] (such as [recipe-name], [mod-setting-description]). However, each prototype may have a distinct search behavior before using those, based on presence/absence of values in the prototype. [https://lua-api.factorio.com/latest/prototypes/RecipePrototype.html RecipePrototype] for example may use the first product's localised_name, or the main_product's localised_name, or the localised string found in {"recipe-name.<recipe name>"], depending on values provided (and lacking) in the prototype.

== See also ==
* [https://lua-api.factorio.com/latest/types/LocalisedString.html LocalisedString data stage doc]
* [https://lua-api.factorio.com/latest/concepts/LocalisedString.html LocalisedString control stage doc]

[[Category:Modding]]

Tutorial:Localisation

2026-06-08T12:34:08Z

Osmo: /* Default Behavior(s) for finding an Unspecified Localised String */

{{Languages}}Mods should define human readable names for prototypes that they add. They can also define descriptions for items or custom strings for usage in GUIs etc. This is called '''localisation'''.

== File format ==
Translations are stored as .cfg files, with the following format:

<pre>welcome-message=Hello world
[category]
title=Category related title
# Comment
; Another comment</pre>
Any whitespace after or before <code>=</code> is included in the key or string, so <code>title =Category related title</code> will give an unknown key error if you are looking for the <code>title</code> key, since it is the <code>title </code> key.

<code>category</code> can be one of the existing locale categories, which permits implicit search mechanisms to find translations, but may also be another key, such as <code>[my-mod-messages]</code>. These are accessible the same as other translations, e.g. <code>{"my-mod-messages.hello"}</code>

These files are located within the language code of the language in the locale folder of the mod, so as an English example <code>__mod__/locale/en/any_name_here.cfg</code>. There can be more than 1 file per language, all of them will be read.

== Localising simple strings ==
The simplest localisation is of items, entities etc. If we say the item is <code>iron-plate</code>, the game will then search all loaded locale files for <code>item-name.iron-plate</code> and <code>item-description.iron-plate</code>, which in the locale file looks like this:

<pre>[item-name]
iron-plate=Iron plate
[item-description]
iron-plate=A plate made of iron.</pre>
If found in the locale, the label is set to this string. If not found, the game will instead show: <code>Unknown key: "item-name.iron-plate"</code>

In script, the localised string is formatted as <code>{"category.name"}</code>, so <code>game.print({"item-name.iron-plate"})</code> prints ''Iron plate''.

It is possible to use [[rich text]] features in the localised text if the location where the text is shown supports it, e.g. in the chat, prototype names and prototype tooltips.

<code>\n</code> can be used for line breaks if the location where the text is shown supports multiline text.

The list of all localization categories used by the base game is:

{| class="mw-collapsible mw-collapsed wikitable"
|-
!Localization categories
|-
|<code>[achievement-description]</code>
|-
|<code>[achievement-name]</code>
|-
|<code>[ammo-category-name]</code>
|-
|<code>[autoplace-control-names]</code>
|-
|<code>[controls]</code>
|-
|<code>[damage-type-name]</code>
|-
|<code>[decorative-name]</code>
|-
|<code>[entity-description]</code>
|-
|<code>[entity-name]</code>
|-
|<code>[equipment-name]</code>
|-
|<code>[fluid-name]</code>
|-
|<code>[fuel-category-name]</code>
|-
|<code>[item-description]</code>
|-
|<code>[item-group-name]</code>
|-
|<code>[item-limitation]</code>
|-
|<code>[item-name]</code>
|-
|<code>[map-gen-preset-description]</code>
|-
|<code>[map-gen-preset-name]</code>
|-
|<code>[mod-description]</code>
|-
|<code>[mod-name]</code>
|-
|<code>[modifier-description]
|-
|<code>[programmable-speaker-instrument]</code>
|-
|<code>[programmable-speaker-note]</code>
|-
|<code>[recipe-name]</code>
|-
|<code>[shortcut-name]</code>
|-
|<code>[story]</code>
|-
|<code>[string-mod-setting]</code>
|-
|<code>[technology-description]</code>
|-
|<code>[technology-name]</code>
|-
|<code>[tile-name]</code>
|-
|<code>[tips-and-tricks-item-description]</code>
|-
|<code>[tips-and-tricks-item-name]</code>
|-
|<code>[virtual-signal-description]</code>
|-
|<code>[virtual-signal-name]</code>
|}

== Localising with parameters ==
For more complex strings, localisation parameters can be used. For instance we want to show ''Time left: 10 minutes.''

So a key with a placeholder is defined, which is replaced by the first parameter after the locale key.:

<pre>time-left=Time left: __1__ minutes.</pre>
So it is used like this:

<syntaxhighlight lang="lua">game.print({"time-left", 10})</syntaxhighlight>
It also works with multiple parameters:

<syntaxhighlight lang="lua">game.print({"time-left", 10, 45})</syntaxhighlight>
<pre>time-left=Time left: __1__ minutes and __2__ seconds.</pre>
Which results in ''Time left: 10 minutes and 45 seconds.''

=== Built-in parameters ===
For some situations, we use localisation to show control schemes. For instance we want to say:

<pre>technology-prompt=Use T to open the technology screen</pre>
However the player may have rebound the key, but we can’t figure out which key as it would not be deterministic. So instead we use the built-in replacement functionality

<pre>technology-prompt=Use __CONTROL__open-technology-gui__ to open the technology screen.</pre>
We can also use this for items and entities:

<pre>big-iron-plate=Big __ITEM__iron-plate__</pre>
<pre>tiny-gun-turret=Tiny __ENTITY__gun-turret__</pre>

==== List of built-in parameters ====
<code>name</code> is the name of an internal game control or a prototype name, depending on context. <code>n</code> can be 1 or 2, it's used in parameters that control [[#Localising_alternate_input_names|alternate input names]]. For a list of internal game control names, see [https://lua-api.factorio.com/latest/types/LinkedGameControl.html CustomInputPrototype::linked_game_control].
* <code>__CONTROL__name__</code> - The combination of modifiers and input, such as "Control + Alt + Left-click", or "Not set".
* <code>__CONTROL_MODIFIER__name__</code> - The modifiers, such as "ControlShift", or, "No modifier selected."
* <code>__CONTROL_STYLE_BEGIN__</code>
* <code>__CONTROL_STYLE_END__</code>
* <code>__CONTROL_LEFT_CLICK__</code> is replaced with <code>control-keys.mouse-button-1</code> or <code>control-keys.controller-b</code>[https://crowdin.com/project/factorio/discussions/214]
* <code>__CONTROL_RIGHT_CLICK__</code> is replaced with <code>control-keys.mouse-button-2</code> or <code>control-keys.controller-x</code>
* <code>__CONTROL_KEY_SHIFT__</code> is replaced with <code>control-keys.shift</code> or <code>control-keys.controller-leftshoulder</code>
* <code>__CONTROL_KEY_CTRL__</code> is replaced with <code>control-keys.control</code> or <code>control-keys.controller-rightshoulder</code>
* <code>__ALT_CONTROL_LEFT_CLICK__n__</code> is replaced with <code>control-keys.mouse-button-1-alt-n</code> or <code>control-keys.controller-button-alt-n</code> (with parameter <code>control-keys.controller-b</code>)
* <code>__ALT_CONTROL_RIGHT_CLICK__n__</code> is replaced with <code>control-keys.mouse-button-2-alt-n</code> or <code>control-keys.controller-button-alt-n</code> (with parameter <code>control-keys.controller-x</code>)
* <code>__ALT_CONTROL__n__name__</code>
* <code>__CONTROL_MOVE__</code> - The Movement keys, squished together. Example: "WASD", from a conventional QWERTY English keyboard.
* <code>__REMARK_COLOR_BEGIN__</code>
* <code>__REMARK_COLOR_END__</code>
* <code>__ENTITY__name__</code> - The localised name of the [https://lua-api.factorio.com/latest/prototypes/EntityPrototype.html EntityPrototype] subclass.
* <code>__FLUID__name__</code> - The localised name of the [https://lua-api.factorio.com/latest/prototypes/FluidPrototype.html FluidPrototype].
* <code>__ITEM__name__</code> - The localised name of the [https://lua-api.factorio.com/latest/prototypes/ItemPrototype.html ItemPrototype] or subclass.
* <code>__PLANET__name__</code> - The localised name of the [https://lua-api.factorio.com/latest/prototypes/SpaceLocationPrototype.html SpaceLocationPrototype] or subclass.
* <code>__TILE__name__</code> - The localised name of the [https://lua-api.factorio.com/latest/prototypes/TilePrototype.html TilePrototype].

=== Plurals ===
Pluralization can be used in any string that uses a parameter (e.g. __1__) that is numeric, so something like an amount of minutes. It can be used multiple times per string.

<pre>format-days=__1__ __plural_for_parameter__1__{1=day|rest=days}__</pre>
This results in "1 day" and "2 days" / "500 days" etc.

The number after <code>__plural_for_parameter__</code> denotes which parameter is used to determine the plural. This is the parameter 1 in the above example. Anything inside the {} is used to make the plural. Each plural form is separated by a |.
The text in front of the = determines for what the plural form is used. Options for this are:
* A simple number, e.g. "1".
* Multiple numbers, e.g. "2,3,4".
* What the number ends with, e.g. "ends in 11" or "ends in 1"
* Multiple ends with, e.g. "ends in 1,ends in 2,ends in 12".
* "decimal" for any number with a fractional part.
* "rest" to give the default plural.

For negative numbers the plural is picked as if the number was positive, so a plural like <code>__plural_for_parameter__1__{1=day|rest=days}__</code> will result in "-1 day" for -1. 
For numbers with a SI prefix the plural is picked as if the number was fully written out, so a plural like <code>__plural_for_parameter__1__{1=day|1000=eons|rest=days}__</code> will result in "1k eons" for 1k.

Plural forms may be empty or contain other keys such as __1__ or spaces. This allows rather large plural forms:

<pre>__plural_for_parameter__1__{1=__1__ player is|rest=__1__ players are}__ connecting</pre>

The system picks the first fitting plural that it encounters when multiple would fit:
<pre>__plural_for_parameter__1__{ends in 12=option 1|ends in 2=option 2|rest=option 3}__</pre>
This will result in "option 1" for 12 and in "option 2" for 22 and in "option 3" for numbers not ending with 2.

The parameter used for pluralisation does not need to be present in the string. For example, a parameter could represent the number of list items present in another parameter:
<pre>
I like __plural_for_parameter__1__{1=only one thing:|rest=these things:} __2__
</pre>
Can result in "I like only one thing: trains", or in "I like these things: trains and turtles".

=== Concatenating localised strings ===
The special locale key: <code>""</code> is used to concatenate, as the table format does not support concatenation:

<syntaxhighlight lang="lua">game.print({"", {"item-name.iron-plate"}, ": ", 60})</syntaxhighlight>
Will result in: ''Iron plate: 60''

=== Localising alternate input names ===

In the introduction campaign, a special locale system is used for informing players how to do certain actions with their mouse.
The normal form is to use eg:
<pre>how-to-build=Use __CONTROL__build__ to place a building</pre>
which results in "Use Left mouse button to place a building". A more natural phrasing would be "Left-click to place a building", which can be achieved by using the following:
<pre>how-to-build=__ALT_CONTROL__1__build__ to place a building</pre>

These "alt" versions are controlled by a few special locale keys, mouse-button-X-alt-1 and mouse-button-X-alt-2. In English, form 1 produces eg "Left-click", and form 2 produces eg "Left-clicking". Only two alt forms ("1" and "2") are available at the moment, but if this a problem for some languages, more forms may be added in the future.
Extra mouse buttons, mouse scroll and keyboard keys are handled through the mouse-button-n-alt-1/2, mouse-wheel-alt-1/2 and keyboard-alt-1/2 keys, which just take the normal name and prepend something like "Press/Pressing", or "Scroll/Scrolling".

When translating to another language, you can use whatever forms you want here, but the important part is that you are consistent when you use the alt-forms everywhere else. It does not necessarily make sense to just copy the usages of alt forms from the English locale, and for some languages it may be more natural to simply not use this system at all.

== Accessing the localised result in code ==
While usually unneeded, it is possible to read the resulting localised text in code, for example to search in localised names.

See
[https://lua-api.factorio.com/latest/classes/LuaPlayer.html#request_translation LuaPlayer::request_translation],
[https://lua-api.factorio.com/latest/classes/LuaPlayer.html#request_translations LuaPlayer::request_translations] and
[https://lua-api.factorio.com/latest/events.html#on_string_translated on_string_translated event].

== Default Behavior(s) for finding an Unspecified Localised String ==
If a localised_name or localised_description is not defined in the prototype or is an empty table: {}, Factorio may have a default search behavior.

For most types, the name defaults to {"<base type>-name.<prototype name>"}, for example {"entity-name.underground-belt"}

Similarly, the description defaults to {"<base type>-description.<prototype name>"}, for example {"entity-description.underground-belt"}

Note: the angle brackets are meant to mean a generic term, they are not part of the actual string.

For items, the process is more complicated:
# if localised_name is provided in the item prototype and it is not empty {}, use the provided value
# else if the item prototype has a place_result:
#:# if place_result has localised_name that is not an empty table: {}, use the localised_name of place_result
#:# else if {"entity-name.<place_result name>"} has a translation, use it
#:# else use {"item-name.<item name>"}
# else if the item prototype has a placed_as_equipment_result:
#:# if place_result has a localised_name that is not an empty table: {}, use the localised_name of placed_as_equipment_result
#:# else if {"equipment-name.<place_as_equipment_result name>"} has a translation, use it
#:# else use {"item-name.<item name>"}
# else if the item prototype has a placed_as_tile:
#:# if place_as_tile result has a localised_name that is not an empty table: {}, use the localised_name of placed_as_tile result
#:# else if {"tile-name.<place_as_tile result name>"} has a translation, use it
#:# else use {"item-name.<item name>"}
# else use {"item-name.<item name>"}
Descriptions of items are found in the same way, except localised_description is used instead of localised_name and <base type>-description is used instead of <base type>-name.

Reference: [https://forums.factorio.com/viewtopic.php?p=494243#p494243] 

Example: The transport-belt item does not have a localised_name, so 1->2. There is a place result, but not localised_name in the entity prototype. 2->3. The place result lacks a localised_name. Use the localised string {"entity-name.transport-belt"}

Such defaults often include a "leading key" using [<group>-name] or [<group>-description] (such as [recipe-name], [mod-setting-description]). However, each prototype may have a distinct search behavior before using those, based on presence/absence of values in the prototype. [https://lua-api.factorio.com/latest/prototypes/RecipePrototype.html RecipePrototype] for example may use the first product's localised_name, or the main_product's localised_name, or the localised string found in {"recipe-name.<recipe name>"], depending on values provided (and lacking) in the prototype.

== See also ==
* [https://lua-api.factorio.com/latest/types/LocalisedString.html LocalisedString data stage doc]
* [https://lua-api.factorio.com/latest/concepts/LocalisedString.html LocalisedString control stage doc]

[[Category:Modding]]

Command line parameters

2026-04-24T03:41:35Z

Osmo: Add --enable-lua-udp

{{Languages}}__TOC__

Command line parameters can be used to set settings in the command line before the game launches, this is useful mainly for advanced users or server hosts.

{| class="wikitable"
|+General options
|-
| -h, --help
|
| display help
|-
| --version
|
| show version information
|-
| -v, --verbose
|
| enable verbose logging
|-
| -c, --config
| PATH
| config file to use
|-
| --no-log-rotation
|
| don't rotate log file
|-
| --mod-directory
| PATH
| Mod directory to use
|-
| --check-unused-prototype-data
|
| Print a warning for all prototype values that were not accessed. Note for mod authors: If an entry is unused and is a table that contains the key/value pair 'ignore' with the value 'true' then the entire entry is ignored.
|-
| --executable-path
| PATH
| Override autodetected __PATH__executable. Usually not needed except on very weird systems.
|}

{| class="wikitable"
|+ Running options
|-
| -s, --map2scenario
| arg
| map to scenario conversion
|-
| -m, --scenario2map
| arg
| scenario to map conversion
|-
| --apply-update
| arg
| immediately apply update package
|-
| --create
| FILE
| create a new map
|-
| --map-gen-settings
| FILE
| Map generation settings for use with <code>--create</code>, <code>--start-server-load-scenario</code> or <code>--generate-map-preview</code>. See data/map-gen-settings.example.json
|-
| --map-gen-seed
| SEED
| Map generation seed for use with --create, --start-server-load-scenario or --generate-map-preview. Will override seed specified in map gen settings
|-
| --map-gen-seed-max
| SEED
| Map generation seed for use with --generate-map-preview to generate multiple previews using every second seed in the interval from map-gen-seed to map-gen-seed-max.
|-
| --map-settings
| FILE
| Map settings for use with --create or --start-server-load-scenario. See data/base/prototypes/map-settings.lua
|-
| --preset
| arg
| Name of the map generation preset to be used.
|-
| --generate-map-preview
| PATH
| Generate preview images of the map; PATH should name a PNG file or end with a '/' or '\' to indicate a directory.
|-
| --generate-map-preview-random
| COUNT
| Number of maps to generate with a random seed using --generate-map-preview.
|-
| --map-preview-size
| SIZE
| Size (in pixels) of map preview (default: 1024)
|-
| --map-preview-offset
| X,Y
| Offset of the center of the map, in meters (default: 0,0)
|-
| --map-preview-planet
| PLANET
| Planet to generate the preview for (default: nauvis)
|-
| --report-quantities
| PROTOTYPE,...
| When generating map preview, report approximate quantities of the named entity prototypes
|-
| --threads
| THREADCOUNT
| Number of threads to use when generating map previews
|-
| --disable-migration-window
|
| Disables the gui that is shown when opening a save with migrated content
|-
| --instrument-mod
| arg
| Name of a mod to enable [https://lua-api.factorio.com/latest/auxiliary/instrument.html Instrument Mode]
|-
| --sync-mods
| FILE
| Sync mods with save. Note for headless servers: requires <code>service-username</code> and <code>service-token</code> to be set in the player-data.json file if any mods need to be downloaded.
|-
| --enable-unsafe-lua-debug-api
|
| Enables unsafe functions in the Lua debug library.
|-
| --enable-lua-udp
| arg
| Set local port and enable [https://lua-api.factorio.com/latest/classes/LuaHelpers.html#send_udp helpers.send_udp()] and and [https://lua-api.factorio.com/latest/classes/LuaHelpers.html#recv_udp helpers.recv_udp()]
|-
| --host
| FILE
| Start hosting a multiplayer game
|-
| --host-interactive
| FILE
| Open multiplayer server settings for hosting the selecting save
|-
| --start-server
| FILE
| start a multiplayer server
|-
| --start-server-load-scenario
| [MOD/]NAME
| start a multiplayer server and load the specified scenario. The scenario is looked for inside the given mod. If no mod is given, it is looked for in the top-level scenarios directory.
|-
| --start-server-load-latest
|
| start a multiplayer server and load the latest available save
|-
| --until-tick
| TICK
| run a save until given map tick
|-
| --benchmark
| FILE
| load save and run benchmark
|-
| --benchmark-ticks
| N
| number of ticks for benchmarking. Default is 1000
|-
| --benchmark-runs
| N
| how often the number of ticks will be run, map will reload after each run. Default is 1
|-
| --benchmark-verbose
| timings
| comma separated list of Update timings to output each tick. "all", "timestamp" as well as all other values seen in the debug show-time-usage view's Update section are allowed here. An empty string disabled verbose benchmarking. Timings are returned in nanoseconds.
|-
| --benchmark-sanitize
|
| only output the final benchmark results
|-
| --benchmark-ignore-paused
|
| leaves the game paused if it was paused when saved. By default the game is unpaused when a benchmark starts.
|-
| --output-perf-stats
| FILE
| path of file to which rendering performance statistics measurements should be saved. Special tags {api}, {hw}, {time} and {tag} will be replaced.
|-
| --dump-data
|
| dumps data.raw as JSON to the script output folder and exits.
|-
| --dump-icon-sprites
|
| dumps all icon sprites as png files to the script output folder and exits.
|-
| --dump-prototype-locale
|
| dumps all prototypes name and description (if they have a valid value) to the script output folder and exits.
|-
| --report-autogenerated-icon-mipmaps
|
| Report which icons will have generated mipmaps.
|-
| --log-shared-tile-layers
|
| After loading prototypes logs which tile layers are shared by multiple prototypes and lists the prototypes that share them.
|-
| --log-spritesheets-to-optimize
| N
| Logs N spritesheets that seem to have some nearly transparent noise, and could be made much smaller if the noise was cleaned up.
|-
| --mp-connect
| ADDRESS
| start factorio and connect to address
|-
| --password
| PASSWORD
| the password to use when using mp-connect (if any)
|-
| --heavy
|
| run the game in heavy mode if singleplayer with graphics. (heavy mode is related to investigating desyncs, see [[Desynchronization#Using_heavy_mode_command]])
|-
| --load-game
| FILE
| start Factorio and load a game in singleplayer
|-
| --load-scenario
| [MOD/]NAME
| start Factorio and load the specified scenario in singleplayer. The scenario is looked for inside the given mod. If no mod is given, it is looked for in the top-level scenarios directory.
|-
| --benchmark-graphics
| FILE
| load save and run it with graphics for benchmark-ticks number of ticks as normal game would
|-
| --benchmark-frame
| FILE
| load save and benchmark graphics rendering of single frame (prepare + render) without updating the game
|-
| --force-opengl
|
|use OpenGL for rendering (windows, mac only)
|-
| --force-d3d
|
|use Direct3D for rendering (windows only)
|-
| --d3d-adapter
| ID
|adapter which should be used to initialized Direct3D (windows only)
|-
| --d3d-feature-level
|
|override feature level (11, 10.1, 10) (windows only)
|-
| --dxgi-blit-model
|
|force Blit presentation mode (windows only)
|-
| --force-metal
|
|use Metal for rendering (mac only)
|-
| --debug-graphics
|
| enables debugging layer for graphics API. If DirectX is used DirectX SDK needs to be installed for this to work.
|-
| --fullscreen
| BOOL
| start game in windowed mode (saved to configuration)
|-
| --max-texture-size
| N
| maximal size of texture that the game can use (saved to configuration). Should be power of two greater than 2048
|-
| --graphics-quality
| arg
| accepted values: high, medium
|-
| --video-memory-usage
| arg
| accepted values: all, high, medium, low
|-
| --force-graphics-preset
| arg
| accepted values: very-low, low, mac-with-low-ram, medium-with-low-vram, medium, high, very-high, extreme
|-
| --gfx-safe-mode
|
| resets some graphics settings to values that should work on most configurations
|-
| --low-vram
|
| sprites that are not put into sprite atlases won't be allocated as texture objects
|-
| --shader
| arg
| enable/disable shader postprocessing (saved to configuration)
|-
| --disable-audio
|
| Disable audio. Mainly for faster startup during development.
|-
| --window-size
| arg
| Desired window resolution. For example "1680x1050". Or "maximized"
|-
| --single-thread-loading
|
| Disables loading of sprites in multiple threads.
|-
| --cache-sprite-atlas
| BOOL
| Enable/disable sprite atlas cache.
|-
| --nogamepad
|
| Disable gamepad(controller) support
|}

{| class="wikitable"
|+ Server options
|-
| --port
| N
| network port to use
|-
| --bind
| ADDRESS[:PORT]
| IP address (and optionally port) to bind to
|-
| --rcon-port
| N
| Port to use for RCON
|-
| --rcon-bind
| ADDRESS:PORT
| IP address and port to use for RCON
|-
| --rcon-password
| PASSWORD
| Password for RCON
|-
| --server-settings
| FILE
| Path to file with server settings. See data/server-settings.example.json
|-
| --use-server-whitelist
| BOOL
| If the whitelist should be used.
|-
| --use-authserver-bans
|
| Verify that connecting players are not banned from multiplayer and inform Factorio.com about ban/unban commands.
|-
| --server-whitelist
| FILE
| Path to file with server whitelist.
|-
| --server-banlist
| FILE
| Path to file with server banlist.
|-
| --server-adminlist
| FILE
| Path to file with server adminlist.
|-
| --console-log
| FILE
| Path to file where a copy of the server's log will be stored
|-
| --server-id
| FILE
| Path where server ID will be stored or read from
|}

=== Boolean options ===

Parameters shown above with a BOOL option must be formatted as <code>[parameter]=true</code> or <code>[parameter]=false</code>. For example,

--fullscreen=false

will start the game in windowed (not fullscreen) mode.

=== Multiplayer ===

--start-server SAVE

Will start a Headless (Dedicated) server, with no GUI.

--mp-connect ADDRESS
ADDRESS is the IP:port of the remote host. Port is optional.
Examples:

./factorio --mp-connect 192.168.1.101
./factorio --mp-connect 192.168.1.101:2345

As above, port can be specified by placing the port number after a colon in the address.

=== Creating a map from custom settings ===

Sometimes it's useful to create a new game with map and/or map generator settings stored in a JSON file rather than going through the in-game map settings screen.
One reason is that by editing the settings directly it is possible to set settings outside the range normally available from the GUI.

To do this, Factorio is run from the command-line, and a JSON file containing the map generator settings and a JSON file containing map settings (if customizing them) are needed.

Example for custom generator settings:
<pre>{
"terrain_segmentation": 0.5,
"water": "2",
"width": 0,
"height": 0,
"starting_area": "normal",
"peaceful_mode": false,
"autoplace_controls":
{
"coal": {"frequency": 1, "size": 2, "richness": 0.5},
"copper-ore": {"frequency": "low", "size": "normal", "richness": "high"},
"crude-oil": {"frequency": "normal", "size": "normal", "richness": "normal"},
"enemy-base": {"frequency": "normal", "size": "normal", "richness": "normal"},
"iron-ore": {"frequency": "normal", "size": "normal", "richness": "normal"},
"stone": {"frequency": "normal", "size": 0, "richness": "normal"},
"uranium-ore": {"frequency": "normal", "size": "none", "richness": "normal"}
},

"cliff_settings":
{
"name": "cliff",
"cliff_elevation_0": 30,
"cliff_elevation_interval": 20,
"richness": 1
},

"property_expression_names":
{
"elevation": "0_16-elevation",
"temperature": "35"
},

"seed": null
}
</pre>

Note that this is the same format as [https://lua-api.factorio.com/latest/concepts/MapGenSettings.html MapGenSettings] that are modifiable from Lua. Everything in the file is optional.

Creating a custom save:
<pre>
"C:\Program Files\Factorio\bin\x64\Factorio.exe" --create stuff-seed123.zip --map-gen-settings map-gen-settings.json --map-gen-seed 123
</pre>

Generating a map preview:
<pre>
"C:\Program Files\Factorio\bin\x64\Factorio.exe" --generate-map-preview preview-seed123.png --map-gen-settings map-gen-settings.json --map-gen-seed 123
</pre>

==== Creating the JSON files from a map exchange string ====

It can be useful to create the initial JSON files from a known map exchange string instead of creating them from scratch. To convert the map exchange string to JSON, open the game and run the following command with your map exchange string:

/c helpers.write_file('map.txt', helpers.table_to_json(helpers.parse_map_exchange_string("<your exchange string here>")))

Then open the script_output folder in the [[user data directory]] and open map.txt - it will look like this:

{"map_settings":{ ...<MAP_SETTINGS> ... },"map_gen_settings":{ ...<MAP_GEN_SETTINGS>... }}

Copy the { ...<MAP_SETTINGS> ... } section into a new file called 'map-settings.json' in the desired location. Copy the { ...<MAP_GEN_SETTINGS> ... } section section into a new file called 'map-gen-settings.json' in the desired location.

== See also ==
* [[Console]]

{{C|Modding}}

Settings

2026-01-06T06:49:56Z

Osmo: typo

{{Languages}}
{{Stub}}

Factorio has a number of '''settings''' in different places, this page covers the ones accessible through the Main menu and Game (pause) menu. These settings are also saved to and can be changed from the "config.ini" file in the Factorio [[Application_directory#User_data_directory|user data directory]]. The [[#See also]] section covers other places that allow configuring the game.

== Controls ==

See [[Controls]]

== Mod settings ==

Settings added by mods are placed here. There are 3 sections: Startup, Map and Per player. Each section contains a list of settings, grouped per mod that added them.

Startup settings require the game to be restarted. This means closing and opening the game, not resetting progress in a save file. Map settings can be changed while the game is running. Per player settings can be changed while the game is running and allow each player to have different values in the settings.

See also: [[Tutorial:Mod settings]]

== Hidden settings ==

Factorio supports a number of hidden configuration options that are not normally shown in the GUI. They can be accessed by holding CTRL + ALT when clicking the "Settings" button in the pause menu, which will cause a new button labeled "The rest" to appear.

These settings may be experimental and may not be validated for safety, so change them at your own risk.

{| class="wikitable"
|+ Notable hidden settings
|-
! Name !! Default !! Description
|-
| autosave-slots || 3 || How many autosaves to keep on a rolling basis
|-
| non-blocking-saving || false || Only works on Mac and Linux. When set to true, saves do not cause the game to pause. [https://forums.factorio.com/viewtopic.php?t=57464]
|-
| technology-gui-pauses-game || true || By setting to false, the game will no longer pause in single player when opening the technology tree.
|-
| cache-prototype-data || false || When enabled, significantly speeds up the "Building prototypes..." step when starting the game at the cost of increased storage space, if prototypes haven't changed since last startup. The cache needs to be built first, so the loading time will increase when rebuilding it, such as when the setting is enabled for the first time.
|-
| cache-sprite-atlas || false || When enabled, significantly speeds up the "Loading sprites..." step when starting the game at the cost of increased storage space, if sprites haven't changed since last startup. The cache needs to be built first, so the loading time will increase when rebuilding it, such as when the setting is enabled for the first time.
|-
| main-menu-simulation-selector || false || Shows a dropdown on the main menu allowing to select a simulation to play in the background. Can be useful for modders when creating custom simulations.
|}

== See also ==

* [[Debug mode|Debug options]]
* [[Command line parameters]]
* [[Map generator]]

Settings

2025-10-23T04:32:45Z

Osmo: Links to multiple relevant pages, added more information, covered settings other than hidden settings.

{{Stub}}

Factorio has a number of '''settings''' in different places, this page covers the ones accessible through the Main menu and Game (pause) menu. These settings are also saved to and can be changed from the "config.ini" file in the Factorio [[Application_directory#User_data_directory|user data directory]]. The [[#See also]] section covers other places that allow configuring the game.

== Controls ==

See [[Controls]]

== Mod settings ==

Settings added by mods are placed here. There are 3 sections: Startup, Map and Per player. Each section contains a list of settings, grouped per mod that added them.

Startup settings require the game to be restarted. This means closing and opening the game, not resetting progress in a save file. Map settings can be changed while the game is running. Per player settings can be changed while the game is running and allow each player to have different values in the settings.

See also: [[Tutorial:Mod settings]]

== Hidden settings ==

Factorio supports a number of hidden configuration options that are not normally shown in the GUI. They can be accessed by holding CTRL + ALT when clicking the "Settings" button in the pause menu, which will cause a new button labeled "The rest" to appear.

These settings may be experimental and may not be validated for safety, so change them at your own risk.

{| class="wikitable"
|+ Notable hidden settings
|-
! Name !! Default !! Description
|-
| autosave-slots || 3 || How many autosaves to keep on a rolling basis
|-
| non-blocking-saving || false || Only works on Mac and Linux. When set to true, saves do not cause to game to pause. [https://forums.factorio.com/viewtopic.php?t=57464]
|-
| technology-gui-pauses-game || true || By setting to false, the game will no longer pause in single player when opening the technology tree.
|-
| cache-prototype-data || false || When enabled, significantly speeds up the "Building prototypes..." step when starting the game at the cost of increased storage space, if prototypes haven't changed since last startup. The cache needs to be built first, so the loading time will increase when rebuilding it, such as when the setting is enabled for the first time.
|-
| cache-sprite-atlas || false || When enabled, significantly speeds up the "Loading sprites..." step when starting the game at the cost of increased storage space, if sprites haven't changed since last startup. The cache needs to be built first, so the loading time will increase when rebuilding it, such as when the setting is enabled for the first time.
|-
| main-menu-simulation-selector || false || Shows a dropdown on the main menu allowing to select a simulation to play in the background. Can be useful for modders when creating custom simulations.
|}

== See also ==

* [[Debug mode|Debug options]]
* [[Command line parameters]]
* [[Map generator]]

Rich text

2025-09-15T22:33:10Z

Osmo: Fix syntactical error

{{Languages}}
Rich text formatting allows the use of tags within most of the game's textboxes to change the visual formatting of text or to embed interactable images/entities. Predefined text tags are employed for this purpose.

== Tags ==

Tags are useful for sharing blueprints, marking map locations in chat or adding icons to map markers and train stations.
Ctrl+alt clicking the map or ground will automatically insert a gps tag and post it into [[console|chat]].

Shift clicking most things with the console open will insert a tag for that thing into chat. The chat and many other textboxes in the game have a button on the right edge that opens an icon selector. This can be used to easily insert rich text tags of recipes, items, fluids, virtual signals and entities into the textbox.

When used in chat, the tag image will be followed by a text description, except for the img tag.
Used elsewhere only the image is shown.

{| class="wikitable"
|-
! style="width:20%"| Syntax
! style="width:15%"| Example Input
! style="width:15%"| Example Result
! style="width:50%"| Description

|-
| [img=class/name] 
[img=class.name] 
[img=sprite-prototype-name]
| [img=item.iron-plate] 
[img=quantity-time] 
[img=utility/played_green]
| [[File:Iron_plate.png|28px]] 
[[File:Time_icon.png|28px]] 
[[File:Played green.png|28px]]
| Embeds only a small inline game graphic. The period format must be used in game save names. This tag uses [https://lua-api.factorio.com/latest/concepts/SpritePath.html sprite paths]:
class is any of: item, entity, technology, recipe, item-group, fluid, tile, virtual-signal, achievement, equipment, space-location or utility.

name: see below

sprite-prototype-name is the [[Data.raw#sprite|internal-name]] of a [[Prototype/Sprite|sprite prototype]].

|-
| [item=name]
| [item=iron-plate]
| [[File:Iron_plate.png|28px]] [Item: Iron plate]
| name is the internal-name of the item

|-
| [entity=name]
| [entity=small-biter]
| [[File:Small_biter.png|28px]] [Entity: Small biter]
| name is the internal-name of the entity

|-
| [technology=name]
| [technology=logistics]
| [[File:Logistics_(research).png|28px]] [Technology: Logistics]
| name is the internal-name of the technology

|-
| [recipe=name]
| [recipe=basic-oil-processing]
| [[File:Basic_oil_processing.png|28px]] [Recipe: Basic oil processing]
| name is the internal-name of the recipe, usually the item name

|-
| [item-group=name]
| [item-group=combat]
| [[File:Item-group_military.png|28px]] [Item Group: Combat]
| name is any of: logistics, production, intermediate-products, combat, fluids or signals

|-
| [fluid=name]
| [fluid=water]
| [[File:Water.png|28px]] [Fluid: Water]
| name is the internal name of the fluid

|-
| [tile=name]
| [tile=grass-3]
| [[File:Grass_3.png|28px]] [Tile: Grass 3]
| name is the internal name of the tile, usually the lowercase name with hyphens replacing spaces as written from the map editor

|-
| [virtual-signal=name]
| [virtual-signal=signal-A]
| [[File:Signal-A.png|28px]] [Virtual Signal: Signal A]
| name is the word signal followed by either an uppercase letter, number, color, each, everything or anything

|-
| [achievement=name]
| [achievement=minions]
| [[File:Minions-achievement.png|28px]] [Achievement: Minions]
| name is the internal-name of the achievement, usually the lowercase name with hyphens replacing spaces

|-
| [gps=x,y]
[gps=x,y,surface]
| [gps=0,0]
| [[File:Map.png|28px]] [Location: 0,0]
| Embeds a map location and marks the location on the map of other players.
x is the x point coordinate 
y is the y point coordinate 
surface is the current surface. Is only added if the player Ctrl+alt clicks on a surface that is not the default surface. When the player is on another surface than surface, clicking the tag does nothing. Mods must handle this case with [https://lua-api.factorio.com/latest/events.html#on_player_clicked_gps_tag on_player_clicked_gps_tag]
|-
| [special-item=blueprint_string]
|
| [[File:Blueprint.png|28px]] [Blueprint]
| Embeds a blueprint. Players can get a blueprint item by clicking the icon.
blueprint_string is the blueprint string of a blueprint, deconstruction planner or upgrade planners

|-
| [armor=player]
| [armor=Player]
| [[File:Power_armor_MK2.png|28px]] [Armor: Player]
| Embeds the armor of a player. Allows other players to see the equipment installed.
player is the name of the player

|-
| [train=number]
| [train=93]
| [[File:Locomotive.png|28px]] [Train: 2]
| Embeds a reference to a train. Clicking the icon will open the train GUI for that train.
number is the internal unit number of the train

|-
| [train-stop=number]
| [train-stop=100]
| [[File:Train_stop.png|28px]] [Train Stop: Trangar]
| Embeds a reference to a train stop. Clicking the icon will open the GUI for that train stop.
number is the internal unit number of the train stop

|-
| [shortcut=shortcut-name]
| [shortcut=give-spidertron-remote]
| [[File:Spidertron_remote.png|28px]] [Shortcut: Create spidertron remote]
| Embeds a reference to a shortcut from the [[Shortcut bar]]. Hovering over the rich text will show the shortcut's description. Clicking the rich text will act as if you clicked the shortcut.
shortcut-name is the internal name of the shortcut.

|-
| [tip=tip-name]
| [tip=spidertron-control]
| [[File:Tip.png|28px]] [Tip: Spidertron control]
| Embeds a reference to a tip from the "Tips and tricks" menu. Hovering over the icon will show the tip's text. Clicking the icon will open the "Tips and tricks" menu to that page.

|-
| [tooltip=text,tooltip locale key]
| [tooltip=Hover to see "Iron plate",item-name.iron-plate]
| [[File:Custom-tag-icon.png|28px]] Hover to see "Iron plate"
| Shows the given text with a tooltip that is specified with a [[Tutorial:Localisation#Localising_simple_strings|locale key]].

|-
| [quality=tier] 
[item=name,quality=tier] 
[entity=name,quality=tier] 

|[quality=normal] 
[item=iron-plate,quality=normal] 
[entity=small-biter,quality=uncommon] 

| [[File:Quality normal.png|28px]] [Quality: Normal] 
[[File:Iron_plate.png|28px]] [Item: Iron plate] 
[[File:Uncommon small biter.png|28px]] [Entity: Uncommon Small biter] 
|
[[Quality]] can also be optionally specified on the following tags: item, entity, recipe, fluid, and virtual-signal 
It can also be added to the other tags that use name, but they ignore it.

The normal quality is the default quality and won't modify tags. Any other quality won't exist without [[Space Age]] and Quality

tier is the internal-name of the quality

|-
| [space-platform=number]
| [space-platform=3]
| [[File:Space_platform_hub.png|28px]] [Space platform: My cool space platform]
| number is the internal id of a space-platform, starting with 1.
Hovering over the rich text will show a view of the space platform. Clicking the rich text will go to the platform in remote view.

|-
| [planet=name]
| [planet=gleba]
| [[File:Gleba.png|28px]] [Planet: Gleba]
| name is the internal name of a planet.
Available planets in Space Age are: nauvis, gleba, fulgora, vulcanus, and aquilo.

[[Nauvis]] is part of the base game and will always be available.

|-
| [space-location=name]
| [space-location=shattered-planet]
[space-location=gleba]
| [[File:Shattered planet.png|28px]] [Space location: Shattered Planet]
[[File:Gleba.png|28px]] [Planet: Gleba]
| name is the internal name of a space-location in Space Age.
Available locations in Space Age are: nauvis, gleba, fulgora, vulcanus, aquilo, solar-system-edge, and shattered-planet.

For the planet's listed in the section above 'planet' will be used as the text prefix instead of 'space-location'

|-
| [space-age]
| [space-age]
| [[File:Space_age_icon.png|28px]]
| Embeds the Space Age icon.
|}

== Text modifiers ==
[[File:Fonts.png|right|thumbnail|100px|Different fonts displayed in-game. (Click to enlarge.)]]

The color and font of text can be changed

{| class="wikitable"
|-
! style="width:20%"| Syntax
! style="width:15%"| Example Input
! style="width:15%"| Example Result
! style="width:50%"| Description
|-
| [color=rgb]...[/color] 
[color=#rrggbb]...[/color] 
[color=#aarrggbb]...[/color] 
[color=rgb]...[.color] 
[color=#rrggbb]...[.color] 
[color=#aarrggbb]...[.color]
| [color=red]Red[/color] text 
[color=1,0,0]Red[/color] text 
[color=255,0,0]Red[/color] text 
[color=#ff0000]Red[/color] text
| Red text
| rgb is a comma separated RGB color ranging from 0 to 1 or 0 to 255, or a color name
Available colors: default, red, green, blue, orange, yellow, pink, purple, white, black, gray, brown, cyan, acid.
|-
| [font=font-name]...[/font] 
[font=font-name]...[.font]
| [font=default-bold]Bold text[/font]
| Bold text
| font-name is the name of the [[Data.raw#font|Factorio font]] to render
|}

== See also ==
* [[Console]]
* [[Data.raw]] for the list of internal names of recipes, technologies, fluids, etc.

{{C|GUI}}