Official Factorio Wiki - User contributions [en]

Tutorial:Modding tutorial/Gangsir

2025-02-27T16:18:42Z

Xorimuth: Remove obsolete migration text, clarify surrounding text.

{{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 three kinds of dependencies. There are required dependencies, and optional dependencies. The third kind, restrictive dependencies, does not affect mod order and instead prevents the game from loading if the other mod is found. Required dependencies are loaded first, always. The game will fail to initialize if one of these is not present. Optional dependencies are loaded first if present, but do not have to be present. This is useful for enabling bonus features if mods are used together. Required dependencies should be used for mod libraries, and similar infrastructure.

=== 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 [[Tutorial:Mod structure|in a certain way]]. To start out, create a folder in your [[Application directory|user data directory]]/mods folder. This folder must have a specific name, <code>fire-armor</code>. You don't need to zip anything for now, that will come later when you're done working on the mod. When you're finished, the mod directory should look like this:

* (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 [[Tutorial:Mod_structure#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.<br>
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:Modding tutorial

2025-02-27T14:03:44Z

Xorimuth: Warn that "Inspecting a live mod" tutorial is 1.1-based.

These tutorials range from teaching the first steps of modding to in-depth explanations of individual mechanics:

* [[Tutorial:Modding tutorial/Gangsir|Modding tutorial/Gangsir]] — A simple modding tutorial that suits beginners well.
* [[Tutorial:Mod structure|Mod structure]] — More details on how mods need to be structured in order to be loaded by the game.
* [[Tutorial:Scripting|Scripting]] — A small tutorial that focuses on run-time scripting and provides some info on how to use the story script.
* [[Tutorial:Mod settings|Mod settings]] — A comprehensive tutorial about how to create and use mod settings.
* [[Tutorial:Localisation|Localisation]] — A tutorial about how to format and use localisation, which is how mods are translated.
* <s>[[Tutorial:Inspecting a live mod|Inspecting a live mod]] — An annotated tour of a mod that is live on the mod portal right now.</s> (Beware that this uses the 1.1 API, so many examples will not work in 2.0+ without modifications)
* [[Tutorial:Mod changelog format|Mod changelog format]] — The formatting requirements for the mod changelog.txt file.
* [[Tutorial:Script interfaces|Script interfaces]] — A small tutorial about script interfaces ([https://lua-api.factorio.com/latest/classes/LuaRemote.html LuaRemote]) and custom keyboard shortcuts.
* <s>[https://togos.github.io/togos-example-noise-programs/ Noise Expressions] — A tutorial about generating terrain, complete with [https://mods.factorio.com/mod/togos-example-noise-programs example mod].</s> (Shows the 1.1 format which has significantly changed for 2.0)
* [https://github.com/ClaudeMetz/UntitledGuiGuide/wiki Untitled GUI Guide] — A tutorial about building custom interfaces that also expands into more advanced parts of GUI modding.
* [https://forums.factorio.com/106661 Controller modding guide / FAQ] — A guide about building your mod to support controllers (game pads).

=== Additional info ===
* [https://lua-api.factorio.com/latest Modding API docs] - Overview page of the modding API documentation website
** [https://lua-api.factorio.com/latest/index-prototype.html Prototype documentation]
** [https://lua-api.factorio.com/latest/index-runtime.html Documentation of the runtime API]
* [[Scenario system]] — Save-based mods ("soft mods") and their limitations
* [https://lua-api.factorio.com/latest/auxiliary/migrations.html Migrations guide] — All information about mod migrations
* [https://github.com/wube/factorio-data Factorio data github repository] — Tracks changes of the lua prototype definitions in Factorio in between releases
* [[Tutorial:Modding FAQ|Modding FAQ]]

=== Third-Party Tools ===
There is a wide variety of tools contributed by community members to help in mod development, such as plugins for IDEs to provide auto-completion, debuggers, as well as scripts to automate common tasks regarding translations or packaging.

* [https://forums.factorio.com/viewforum.php?f=135 Factorio sub-forum for mod development tools]
<noinclude>{{Languages}}
== See also ==
* [[Tutorials]]
* [[Modding]]
* [[:Category:Technical]] — Documentation of technical formats and API's not related to modding

[[Category:Modding]]
</noinclude>

Tutorial:Modding FAQ

2025-02-27T14:00:53Z

Xorimuth: Fix broken links

{{Languages}}
This is a list of common questions asked by new mod makers. Feel free to edit and update with new questions and answers.

== Errors ==
General note: Errors give you either a line info or at least a reference as to where the error occurred. If a line is specified, then the odds are high that the mistake actually happened on one of the previous lines. Try to check for common errors like missing a comma while defining an array or writing data.extend instead of data:extend beforehand.

=== "C:\Factorio\mod doesn't match the expected mod_version# (case sensitive!)" ===
The folder name of your mod must include the version number, and name of the mod separated by an underscore. So if your mod is titled "myMod" version 0.0.1, in order for Factorio to read it, the folder must be titled "myMod_0.0.1".

=== "attempt to index a nil value" ===
This is a Lua error that means the mod is trying to access a value that doesn't exist. Similar to a Null Pointer in other programming languages, you're trying to access something that doesn't exist. This happens most often with accessing Factorios custom Lua tables, and trying to access a var that doesn't exist within that table.
This also happens with developers experienced in other programming languages that forget that Lua tables are indexed from '''1''', not 0. Table[0] doesn't exist by default in Lua.

=== Failed to load mods: Error while loading prototype "prototype-name" (prototype-type): Key "property-name" not found in property tree at ROOT.prototype-type.prototype-name ===
Your prototype with the name <code>prototype-name</code> and type <code>prototype-type</code> is missing the <code>property-name</code> property. You need to add it to make it possible for the game to load.

== Problems ==
=== My item / entity wont load the sprite I made. ===
Make sure your path is right : __mod-name__/folder-name/2nd-folder-name/sprite.png. Pay attention to case, the following file is not the same as previous: __Mod-name__/Folder-name/2nd-folder-name/sprite.PNG. Also note that Factorio is only capable of loading png files for icons and entity textures.

=== The name of my item is displayed as "Unknown key: item-name.yourname" ===
Make sure you have valid locale mappings. Create a "locale" directory with an "en" sub-directory and create a "item-name.cfg" file. It should contains something like:
[item-name]
itemx=Item X
itemy=Item Y

Make sure there are no spaces before or after the <code>=</code>. Do the same for your entities, but put them in an ''[entity-name]'' section/file.
For each ''[xxx-name]'' section you should preferably also add a section ''[xxx-description]'', which will then display as description when you hover over the corresponding item/entity/technology/mod-setting

=== I'm trying to change the attributes of a vanilla entity, but it's not working! ===
If there are other mods installed in your dev environment, it's possible that their changes are overwriting yours. (A good find if this is true, because this is an incompatibility!) To fix, you need to add the mod that's doing it (up to you to find) as an ''optional'' dependency, so it gets loaded first. This ensures that your changes overwrite theirs.

Be careful though, if the mod in question is expecting it's changes to stick, you could break the mod. If so, this means that your mod is permanently incompatible with that mod, so you should declare that fact in your mod's description and in the dependencies by listing the mod with a <code>!</code> in front:

<pre>
"dependencies": ["base", "? optional-dependency >=0.13.1", "! incompatible-mod"]
</pre>

=== My mod does not show up in game ===
Your info.json has a problem/doesn't exist. Make sure you have a info.json file in the root folder of your mod, that it has the right file extension (.json), and the right factorio_version. The json also does not allow trailing commas in lists, the game will print that error to the [[log file]] and refuse to load the mod until you fix it. Other errors such as wrong format for dependenciescan also be found in the log file.

== Other ==
=== How do I store information with an entity, like integers or booleans? ===
Factorio's API ensures that modders use the proper way to do things, to reduce the possible instability arising from modders doing strange workarounds. The proper way to store data with an entity is to use a table in the [https://lua-api.factorio.com/latest/auxiliary/storage.html storage table] that contains the entity and information. If you then need to access it, you can write code to get the value out of the table that corresponds to the entity. It isn't possible to store data on an entity in any other way, either in the control stage or data stage. Some entity types do have space for variables, as of 0.15.

=== How do I make an entity store/consume energy even if it wasn't made to? ===
Use of the <code>electric energy interface</code> allows for arbitrary electricity handling. You will need to spawn this entity on top of yours, and clean it up when your entity is destroyed. Scripting is also necessary to gate the entity's functions behind energy requirements.

=== How can I disable a recipe with scripting? ===
Simple, just set it's <code>enabled</code> tag to false. An item's recipe can be obtained through its prototype.

=== How do I declare a dependency of my mod? ===
This is done in the info.json file of your mod. Under the dependency field, simply place the ''internal name'' (Not the pretty title!) of the mod you want to declare as a dependency. It is a json table, so multiple can be defined. If you want to declare it as an optional dependency, then put a question mark and space before the name. To define a minimum version, simply put a logic operator, such as >=, and a version. As an example:

<pre>
"dependencies": ["? MAIN-DyTech-Machine", "? CORE-DyTech-Core", "bobenemies>=0.13.1", "bobores", "? 5dim_ores"],
</pre>

Be careful with required dependencies, as they will cause your mod to be disabled if they are unmet or ill-defined. Dependencies also cannot be circular, if another mod requires yours, you ''cannot'' require it; Somebody has to load first.

=== How are mods loaded in Factorio? ===
See [https://lua-api.factorio.com/latest/auxiliary/data-lifecycle.html this page by the developers], it sums up the process very well.

=== How do I submit my mod to the mod portal? ===
Login with your Factorio.com account, and click the "Submit mod" button under "My Mods" in the top right corner. Provide the mod as a zip file, and write a description/upload some pics. The title, version, etc is all pulled from the zip. The mod name may not contain spaces.

[[Category:Modding]]

Tutorial:Script interfaces

2025-02-27T13:56:32Z

Xorimuth: building -> entity

{{Languages}}
== Script interfaces (LuaRemote) ==

Script interfaces allow direct communication between simultaneously running scripts. This is done in form of defining a public interface with given functions. All the code regarding the interfaces communication is in the <code>remote</code> namespace. More info can be found in the offical api documentation, in this case [https://lua-api.factorio.com/latest/classes/LuaRemote.html LuaRemote].

=== Defining interfaces ===

The interface is defined as follows:

<syntaxhighlight lang="lua">-- assuming interface_name and table_of_functions are defined elsewhere
remote.add_interface(interface_name, table_of_functions)

-- It is possible to define the name and table inside the call
remote.add_interface("my_interface", {
my_getter = function()
-- you can return 1 or more variables from the script
return "foo"
end,

-- the values can be only primitive type or (nested) tables
my_setter = function(foo, bar)
global.foo = foo
global.bar = bar
end
})</syntaxhighlight>

The interface functions cannot take function pointers or function closures. Primitive types, LuaObjects and tables work just fine.

=== Calling interface functions ===

The interface can be used for calling functions from a different script. '''Limitations''': A table with a metatable will not retain that metatable when received by the remote mod (however, game objects passed will remain intact). A received table is a '''copy''' of the original. It is '''not possible''' for two mods to "share" the same table across a remote call.

Example (in the different script than the one above):

<syntaxhighlight lang="lua">-- calls the my_interface.my_getter from the script above and prints the returning value
print(remote.call("my_interface", "my_getter"))
-- remote call takes the name of the interface, name of the function and then variable amount of parameters
remote.call("my_interface", "my_setter", 5, {bar=baz})</syntaxhighlight>

=== Discovering interfaces ===

The script can check for expected interfaces and its functions via the <code>remote.interfaces</code> table. This is a table indexed by interface names where the values are set of functions for particular interfaces.

Example:
<syntaxhighlight lang="lua">
-- check whether there is the "my_interface" interface and whether it contains the "my_getter" function
if remote.interfaces.my_interface and remote.interfaces.my_interface.my_getter then
-- the remote call for the function is safe to use
end</syntaxhighlight>

== Custom input ==

Keybindings can also be created. First the keybinding has to be defined in the data stage, see [https://lua-api.factorio.com/latest/prototypes/CustomInputPrototype.html CustomInputPrototype]:

<syntaxhighlight lang="lua">local button={
type = "custom-input",
name = "my-custom-input",
key_sequence = "SHIFT + G",
consuming = "none"
}
data:extend{button}</syntaxhighlight>

Available options for "consuming" are:
* none: default if not defined
* game-only: Blocks game inputs using the same key sequence but lets other custom inputs using the same key sequence fire.

:''See also [https://lua-api.factorio.com/latest/types/ConsumingType.html ConsumingType]''

Locale definition:

<syntaxhighlight lang="lua">[controls] --Text for "game menu -> controls -> mods"
my-custom-input=Potato controls</syntaxhighlight>

Use <code>__CONTROL__my-custom-input__</code> to get the bound key in other locale, for example

<syntaxhighlight lang="lua">this-is-some-locale=Potato controls are bound to "__CONTROL__my-custom-input__"</syntaxhighlight>

shows <code>Potato controls are bound to "SHIFT + G"</code> in-game.

And then it can be used runtime by subscribing to the event of the name of the custom input:

<syntaxhighlight lang="lua">script.on_event("my-custom-input", function(event)
game.print("Ran on tick: " .. tostring(event.tick))
end)</syntaxhighlight>

The [https://lua-api.factorio.com/latest/events.html#CustomInputEvent event ] contains the following:

* player_index :: [https://lua-api.factorio.com/latest/concepts/uint.html uint]
* tick :: [https://lua-api.factorio.com/latest/concepts/uint.html uint]
* input_name :: [https://lua-api.factorio.com/latest/types/string.html string]: The name of the custom input.
* cursor_position :: [https://lua-api.factorio.com/latest/concepts/MapPosition.html MapPosition]: The mouse cursor position when the input was activated.
* cursor_direction :: [https://lua-api.factorio.com/latest/defines.html#defines.direction defines.direction] (optional): The mouse cursor direction, for when the cursor contains a rotatable entity.
* cursor_display_location :: [https://lua-api.factorio.com/latest/concepts/GuiLocation.html GuiLocation]: The mouse cursor display location when the custom input was activated.
* selected_prototype :: [https://lua-api.factorio.com/latest/concepts/SelectedPrototypeData.html SelectedPrototypeData] (optional): Provided if [https://lua-api.factorio.com/latest/prototypes/CustomInputPrototype.html#include_selected_prototype include_selected_prototype] is true.

[[Category:Modding]]

Tutorial:Script interfaces

2025-02-27T13:56:05Z

Xorimuth: Fix broken link, add new CustomInputEvent value

{{Languages}}
== Script interfaces (LuaRemote) ==

Script interfaces allow direct communication between simultaneously running scripts. This is done in form of defining a public interface with given functions. All the code regarding the interfaces communication is in the <code>remote</code> namespace. More info can be found in the offical api documentation, in this case [https://lua-api.factorio.com/latest/classes/LuaRemote.html LuaRemote].

=== Defining interfaces ===

The interface is defined as follows:

<syntaxhighlight lang="lua">-- assuming interface_name and table_of_functions are defined elsewhere
remote.add_interface(interface_name, table_of_functions)

-- It is possible to define the name and table inside the call
remote.add_interface("my_interface", {
my_getter = function()
-- you can return 1 or more variables from the script
return "foo"
end,

-- the values can be only primitive type or (nested) tables
my_setter = function(foo, bar)
global.foo = foo
global.bar = bar
end
})</syntaxhighlight>

The interface functions cannot take function pointers or function closures. Primitive types, LuaObjects and tables work just fine.

=== Calling interface functions ===

The interface can be used for calling functions from a different script. '''Limitations''': A table with a metatable will not retain that metatable when received by the remote mod (however, game objects passed will remain intact). A received table is a '''copy''' of the original. It is '''not possible''' for two mods to "share" the same table across a remote call.

Example (in the different script than the one above):

<syntaxhighlight lang="lua">-- calls the my_interface.my_getter from the script above and prints the returning value
print(remote.call("my_interface", "my_getter"))
-- remote call takes the name of the interface, name of the function and then variable amount of parameters
remote.call("my_interface", "my_setter", 5, {bar=baz})</syntaxhighlight>

=== Discovering interfaces ===

The script can check for expected interfaces and its functions via the <code>remote.interfaces</code> table. This is a table indexed by interface names where the values are set of functions for particular interfaces.

Example:
<syntaxhighlight lang="lua">
-- check whether there is the "my_interface" interface and whether it contains the "my_getter" function
if remote.interfaces.my_interface and remote.interfaces.my_interface.my_getter then
-- the remote call for the function is safe to use
end</syntaxhighlight>

== Custom input ==

Keybindings can also be created. First the keybinding has to be defined in the data stage, see [https://lua-api.factorio.com/latest/prototypes/CustomInputPrototype.html CustomInputPrototype]:

<syntaxhighlight lang="lua">local button={
type = "custom-input",
name = "my-custom-input",
key_sequence = "SHIFT + G",
consuming = "none"
}
data:extend{button}</syntaxhighlight>

Available options for "consuming" are:
* none: default if not defined
* game-only: Blocks game inputs using the same key sequence but lets other custom inputs using the same key sequence fire.

:''See also [https://lua-api.factorio.com/latest/types/ConsumingType.html ConsumingType]''

Locale definition:

<syntaxhighlight lang="lua">[controls] --Text for "game menu -> controls -> mods"
my-custom-input=Potato controls</syntaxhighlight>

Use <code>__CONTROL__my-custom-input__</code> to get the bound key in other locale, for example

<syntaxhighlight lang="lua">this-is-some-locale=Potato controls are bound to "__CONTROL__my-custom-input__"</syntaxhighlight>

shows <code>Potato controls are bound to "SHIFT + G"</code> in-game.

And then it can be used runtime by subscribing to the event of the name of the custom input:

<syntaxhighlight lang="lua">script.on_event("my-custom-input", function(event)
game.print("Ran on tick: " .. tostring(event.tick))
end)</syntaxhighlight>

The [https://lua-api.factorio.com/latest/events.html#CustomInputEvent event ] contains the following:

* player_index :: [https://lua-api.factorio.com/latest/concepts/uint.html uint]
* tick :: [https://lua-api.factorio.com/latest/concepts/uint.html uint]
* input_name :: [https://lua-api.factorio.com/latest/types/string.html string]: The name of the custom input.
* cursor_position :: [https://lua-api.factorio.com/latest/concepts/MapPosition.html MapPosition]: The mouse cursor position when the input was activated.
* cursor_direction :: [https://lua-api.factorio.com/latest/defines.html#defines.direction defines.direction] (optional): The mouse cursor direction, for when the cursor contains a rotatable building.
* cursor_display_location :: [https://lua-api.factorio.com/latest/concepts/GuiLocation.html GuiLocation]: The mouse cursor display location when the custom input was activated.
* selected_prototype :: [https://lua-api.factorio.com/latest/concepts/SelectedPrototypeData.html SelectedPrototypeData] (optional): Provided if [https://lua-api.factorio.com/latest/prototypes/CustomInputPrototype.html#include_selected_prototype include_selected_prototype] is true.

[[Category:Modding]]

Tutorial:Scripting

2025-02-27T13:15:06Z

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

{{Languages}}
== What is a script? ==
In general, you can learn the definition of a script [https://en.wikipedia.org/wiki/Scripting_language here]. Within the context of Factorio, a script refers to a Lua script, packaged with a mod or scenario.

There are 2 usages of scripts, loading of [https://lua-api.factorio.com/latest/index-prototype.html prototype data], and runtime scripting of the game and its entities.

This guide only covers usages of runtime scripts. To be more specific, we call these runtime scripts 'control scripts', as they assert direct control on the game as it runs.

== Loading a script ==
When you load a game, scenario and mod scripts are loaded. The game looks for a file called 'control.lua', in the mod directory or the scenario directory. If found, the game will then load that script, and any other scripts required in the control script.

== [https://lua-api.factorio.com/latest/Libraries.html Factorio specifics] ==
Factorio uses Lua version 5.2.1.

Factorio uses Serpent for serialization - This comes with some big drawbacks:

* Serpent is relatively slow and inefficient
* Serpent cannot serialize a lot of Lua objects, such as functions, metatables and coroutines.

The full scripting API is generated and updated each release, and is available [https://lua-api.factorio.com/latest/index-runtime.html here]. This is the number 1 resource for scripting in the game.

== [http://lua-api.factorio.com/latest/LuaBootstrap.html Script events] ==
The Lua script has some special functions it runs outside of events:
* <code>script.on_init()</code>
* <code>script.on_configuration_changed()</code>
* <code>script.on_load()</code>

[https://lua-api.factorio.com/latest/classes/LuaBootstrap.html#on_init <code>on_init()</code>] will run when the game starts (or in mod cases, when you add it to an existing save). It is used to initialize storage variables you will need, changing game parameters, for instance:

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

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

[https://lua-api.factorio.com/latest/classes/LuaBootstrap.html#on_configuration_changed <code>on_configuration_changed(data)</code>] will run when some configuration about this save game changes, such as a mod being added, changed or removed. This function is used to account for changes to game or prototype changes. <code>data</code> will contain information on what has changed.

So if you are dependent on some prototype for your script to work, you should check here that it still exists:

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

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

[https://lua-api.factorio.com/latest/classes/LuaBootstrap.html#on_load <code>on_load()</code>] will run every time the script loads. <code>game</code> will not be available during <code>on_load</code>. This should only be used to handle resetting up metatables, making local references to variables in <code>storage</code>, and setting up conditional event handlers.

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

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

--Conditional event handler
if storage.trees then
script.on_event(defines.events.on_tick, handle_tree_function)
end
end)</syntaxhighlight>
It is quite easy to generate desyncs doing overly complex things with on_load, so we recommend only doing things with it if absolutely nescessary.

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

The scripts all run based off events. These events are sent by the game after certain actions are performed. For instance <code>on_player_crafted_item</code>. To ''do'' something with an event, you will need to assign an event handler:

<syntaxhighlight lang="lua">script.on_event(defines.events.on_player_crafted_item, player_crafted_function)</syntaxhighlight>
When the event is triggered, it will then call the function with <code>event</code> as its parameter. <code>event</code> is a table that contains varying information about the event. More specific info on them [http://lua-api.factorio.com/latest/events.html here]. You then process the event using your own function:

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

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

<syntaxhighlight lang="lua">script.on_event(defines.events.on_tick, function(event)
game.print("tick")
end)

script.on_event(defines.events.on_tick, function(event)
game.print("tock")
end)</syntaxhighlight>
The second handler will overwrite the first.

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

<syntaxhighlight lang="lua">script.on_event(defines.events.on_tick, function(event)
this_on_tick(event)
that_on_tick(event)
end)</syntaxhighlight>
== Saving data & the <code>storage</code> table ==

Save/Load stability is very important to preserve the determinism of the game. In Lua, all values are global by default. This isn’t good news in Factorio, as it can make it seem as though things are working correctly, but will lead to desyncs in multiplayer.

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

<syntaxhighlight lang="lua">script.on_event(defines.events.on_tick, function(event)
storage.ticker = (storage.ticker or 0) + 1
end)</syntaxhighlight>
Now when the player saves the game, the value of <code>storage.ticker</code> will be saved. When it is loaded again, its value will be restored. This is important, because in multiplayer, players joining the game will load the value from the save.

The way this can cause desyncs is quite clear: if one player has their Lua state, with a ticker value of 100, and another has a value of 50, and you then create ticker number of biters, it would create 100 for player 1, and 50 for player 2.

However it is not often this easy. The case is often as follows:

<syntaxhighlight lang="lua">tick_to_print = 10 --So lets say this is a static variable. Just some config for how your script works.

function on_tick()
if game.tick == tick_to_print then
game.print("hello")
end
end

script.on_event(defines.event.on_tick, on_tick)</syntaxhighlight>
This will be fine, we are using the variable, but not changing it. When a new player loads the game, <code>tick_to_print</code> will be <code>10</code>, same as the other players.

Problem comes if we adjust <code>tick_to_print</code>, either by purpose or intentionally.

<syntaxhighlight lang="lua">tick_to_print = 10 --So lets say this is a static variable. Just some config for how your script works.

function on_tick()
if game.tick == tick_to_print then
game.print("hello")
tick_to_print = tick_to_print + 100 --Say we want it to print again in 100 ticks
end
end

script.on_event(defines.event.on_tick, on_tick)</syntaxhighlight>
Now when you test the script, it will work perfectly. Every 100 ticks it will print “hello”. The problem occurs when you save and then load the game. When you save, the value of <code>tick_to_print</code> is not saved anywhere, and so when you load, it just uses the value it is told to at the top of the script: <code>10</code>.

Now it is clear that the value of <code>tick_to_print</code> has changed by saving and loading, so we say it is not save/load stable. If a players joins a multiplayer game with this script, they would desync as soon as one of the scripts prints as the result of a comparison against <code>tick_to_print</code>.

So TL;DR - If you want to use something between ticks then store it in <code>storage</code>. This will prevent 99% of possible desyncs.

== Story script ==

Story script is a Lua library designed to facilitate the scripting and flow of a story. It has some simple structure and supporting function to help things move along.

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

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

--Story table is where the 'story' is all defined.
story_table =
{
{
--branch 1
{
--First story event

--Initialise this event
init = function(event, story)
game.print("First init of first story event")
end,

--Update function that will run on all events
update = function(event, story)
log("updating")
end,

--Condition to move on. If the return value is 'true', the story will continue.
condition = function(event, story)
if event.tick > 100 then
return true
end
end,

--Action to perform after condition is met
action = function(event, story)
game.print("You completed the objective!")
end
},
{
--Second story event - example.
init = function(event, story)
game.print("Collect 100 iron plate")
end,
condition = function(event, story)
return game.players[1].get_item_count("iron-plate") >= 100
end,
action = function(event, story)
game.print("Well done")
end
}
--Once the end of a branch is reached, the story is finished.
--The game will now display the mission complete screen.
},
{
--branch 2
}
}

--Init the helpers and story table. Must be done all times script is loaded.
story_init_helpers(story_table)</syntaxhighlight>

Branches are an optional system of the story system, and you can jump to another branch using <code>story_jump_to(story, name)</code>. The story progresses from the top down, and when it reaches the last story event, the mission concludes.

It is possible to leverage any number of clever Lua tricks and API calls in the story table. It is good form to try and keep each story part independant from its neighbors, as it makes maintanance and reworkings more manageable.

Bad:

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

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

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

<syntaxhighlight lang="lua">--Return true only after this many seconds has elasped
story_elapsed_check(5)

--Update the objective for all players
set_goal({"objective-1"})

--Flash the goal GUI for players (updating info doesn't flash it)
flash_goal()

--Update the 'info gui' for all players. This is quite powerful and can use custom function to build complex GUI's
set_info(
{
text = {"info-1"},
picture = "item/iron-plate"
})

--Exports entities in a Lua table format
export_entities(parameters)

--Recreates entities saved using a Lua format
recreate_entities(entities, parameters)

--Shorthand syntax for game.players[i], defaults i to 1
player(i)

--Shorthand syntax for game.surfaces[i], defaults i to 1
surface(i)</syntaxhighlight>

[[Category:Modding]]

Tutorial:Scripting

2024-11-13T16:59:56Z

Xorimuth: 2.0 update (global -> storage)

{{Languages}}
== What is a script? ==
In general, you can learn the definition of a script [https://en.wikipedia.org/wiki/Scripting_language here]. Within the context of Factorio, a script refers to a Lua script, packaged with a mod or scenario.

There are 2 usages of scripts, loading of [https://lua-api.factorio.com/latest/index-prototype.html prototype data], and runtime scripting of the game and its entities.

This guide only covers usages of runtime scripts. To be more specific, we call these runtime scripts 'control scripts', as they assert direct control on the game as it runs.

== Loading a script ==
When you load a game, scenario and mod scripts are loaded. The game looks for a file called 'control.lua', in the mod directory or the scenario directory. If found, the game will then load that script, and any other scripts required in the control script.

== [https://lua-api.factorio.com/latest/Libraries.html Factorio specifics] ==
Factorio uses Lua version 5.2.1.

Factorio uses Serpent for serialization - This comes with some big drawbacks:

* Serpent is relatively slow and inefficient
* Serpent cannot serialize a lot of Lua objects, such as functions, metatables and coroutines.

The full scripting API is generated and updated each release, and is available [https://lua-api.factorio.com/latest/index-runtime.html here]. This is the number 1 resource for scripting in the game.

== [http://lua-api.factorio.com/latest/LuaBootstrap.html Script events] ==
The Lua script has some special functions it runs outside of events:
* <code>script.on_init()</code>
* <code>script.on_configuration_changed()</code>
* <code>script.on_load()</code>

<code>on_init()</code> will run when the game starts (or in mod cases, when you add it to an existing save). It is used to initialize storage variables you will need, changing game parameters, for instance:

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

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

<code>on_configuration_changed(data)</code> will run when some configuration about this save game changes, such as a mod being added, changed or removed. This function is used to account for changes to game or prototype changes. <code>data</code> will contain information on what has changed.

So if you are dependent on some prototype for your script to work, you should check here that it still exists:

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

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

<code>on_load()</code> will run every time the script loads. <code>game</code> will not be available during <code>on_load</code>. This should only be used to handle resetting up metatables, making local references to variables in <code>storage</code>, and setting up conditional event handlers.

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

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

--Conditional event handler
if storage.trees then
script.on_event(defines.events.on_tick, handle_tree_function)
end
end)</syntaxhighlight>
It is quite easy to generate desyncs doing overly complex things with on_load, so we recommend only doing things with it if absolutely nescessary.

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

The scripts all run based off events. These events are sent by the game after certain actions are performed. For instance <code>on_player_crafted_item</code>. To ''do'' something with an event, you will need to assign an event handler:

<syntaxhighlight lang="lua">script.on_event(defines.events.on_player_crafted_item, player_crafted_function)</syntaxhighlight>
When the event is triggered, it will then call the function with <code>event</code> as its parameter. <code>event</code> is a table that contains varying information about the event. More specific info on them [http://lua-api.factorio.com/latest/events.html here]. You then process the event using your own function:

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

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

<syntaxhighlight lang="lua">script.on_event(defines.events.on_tick, function(event)
game.print("tick")
end)

script.on_event(defines.events.on_tick, function(event)
game.print("tock")
end)</syntaxhighlight>
The second handler will overwrite the first.

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

<syntaxhighlight lang="lua">script.on_event(defines.events.on_tick, function(event)
this_on_tick(event)
that_on_tick(event)
end)</syntaxhighlight>
== Saving data & the <code>storage</code> table ==

Save/Load stability is very important to preserve the determinism of the game. In Lua, all values are global by default. This isn’t good news in Factorio, as it can make it seem as though things are working correctly, but will lead to desyncs in MP.

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

<syntaxhighlight lang="lua">script.on_event(defines.events.on_tick, function(event)
storage.ticker = (storage.ticker or 0) + 1
end)</syntaxhighlight>
Now when the player saves the game, the value of <code>storage.ticker</code> will be saved. When it is loaded again, its value will be restored. This is important, because in MP, players joining the game will load the value from the save.

The way this can cause desyncs is quite clear, if one player has their Lua state, with a ticker value of 100, and another has a value of 50, and you then create ticker number of biters, it would create 100 for player 1, and 50 for player 2.

However it is not often this easy. The case is often as follows:

<syntaxhighlight lang="lua">tick_to_print = 10 --So lets say this is a static variable. Just some config for how your script works.

function on_tick()
if game.tick == tick_to_print then
game.print("hello")
end
end

script.on_event(defines.event.on_tick, on_tick)</syntaxhighlight>
This will be fine, we are using the variable, but not changing it. When a new player loads the game, <code>tick_to_print</code> will be <code>10</code>, same as the other players.

Problem comes if we adjust <code>tick_to_print</code>, either by purpose or intentionally.

<syntaxhighlight lang="lua">tick_to_print = 10 --So lets say this is a static variable. Just some config for how your script works.

function on_tick()
if game.tick == tick_to_print then
game.print("hello")
tick_to_print = tick_to_print + 100 --Say we want it to print again in 100 ticks
end
end

script.on_event(defines.event.on_tick, on_tick)</syntaxhighlight>
Now when you test the script, it will work perfectly. Every 100 ticks it will print “hello”. The problem occurs when you save, and load the game. When you save, the value of <code>tick_to_print</code> is not saved anywhere, And thus, when you load, it just uses the value its told to at the top of the script: <code>10</code>.

Now it is clear that the value of <code>tick_to_print</code> has changed by saving and loading, thus we say it is not save/load stable. If a players joins a MP game with this script, they would desync as soon as one of the scripts prints as the result of a comparison against <code>tick_to_print</code>.

So TL;DR - If you want to use something between ticks, then store it in <code>storage</code>. This will prevent 99% of possible desyncs.

== Story script ==

Story script is a Lua library designed to facilitate the scripting and flow of a story. It has some simple structure and supporting function to help things move along.

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

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

--Story table is where the 'story' is all defined.
story_table =
{
{
--branch 1
{
--First story event

--Initialise this event
init = function(event, story)
game.print("First init of first story event")
end,

--Update function that will run on all events
update = function(event, story)
log("updating")
end,

--Condition to move on. If the return value is 'true', the story will continue.
condition = function(event, story)
if event.tick > 100 then
return true
end
end,

--Action to perform after condition is met
action = function(event, story)
game.print("You completed the objective!")
end
},
{
--Second story event - example.
init = function(event, story)
game.print("Collect 100 iron plate")
end,
condition = function(event, story)
return game.players[1].get_item_count("iron-plate") >= 100
end,
action = function(event, story)
game.print("Well done")
end
}
--Once the end of a branch is reached, the story is finished.
--The game will now display the mission complete screen.
},
{
--branch 2
}
}

--Init the helpers and story table. Must be done all times script is loaded.
story_init_helpers(story_table)</syntaxhighlight>

Branches are an optional system of the story system, and you can jump to another branch using <code>story_jump_to(story, name)</code>. The story progresses from the top down, and when it reaches the last story event, the mission concludes.

It is possible to leverage any number of clever Lua tricks and API calls in the story table. It is good form to try and keep each story part independant from its neighbors, as it makes maintanance and reworkings more manageable.

Bad:

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

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

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

<syntaxhighlight lang="lua">--Return true only after this many seconds has elasped
story_elapsed_check(5)

--Update the objective for all players
set_goal({"objective-1"})

--Flash the goal GUI for players (updating info doesn't flash it)
flash_goal()

--Update the 'info gui' for all players. This is quite powerful and can use custom function to build complex GUI's
set_info(
{
text = {"info-1"},
picture = "item/iron-plate"
})

--Exports entities in a Lua table format
export_entities(parameters)

--Recreates entities saved using a Lua format
recreate_entities(entities, parameters)

--Shorthand syntax for game.players[i], defaults i to 1
player(i)

--Shorthand syntax for game.surfaces[i], defaults i to 1
surface(i)</syntaxhighlight>

[[Category:Modding]]

Upcoming features

2023-08-18T17:33:43Z

Xorimuth: /* Known changes for 1.2 */ Added several upcoming changes mentioned by developers.

{{Languages}}
This is a list of known information about Factorio's "one big expansion pack".

== Plans ==
* Q: What?
** A: It is way too early to show any of the plans, and since we want to keep the iterative process of expanding things that prove to be the most fun, the plan is quite loose anyway. [https://www.factorio.com/blog/post/fff-365]
* Multiple people, including the modder [https://mods.factorio.com/user/Earendel Earendel] were hired to work on the expansion pack. [https://www.factorio.com/blog/post/fff-365]
* As of February 2022, development is on step 4 "Connecting systems into a prototype" out of 7 total steps until release. [https://factorio.com/blog/post/fff-367]
* [https://factorio.com/blog/post/fff-367 Friday Facts #367] shows some concept art for the expansion.
* [https://factorio.com/blog/post/fff-372 Friday Facts #372] shows some item icons from the expansion.
* It is planned to be "as big an addition as the whole vanilla game." [https://factorio.com/blog/post/fff-367]
* The planned price is $30.00. [https://factorio.com/blog/post/fff-367]
* Will not be ready before September 2023. [https://factorio.com/blog/post/fff-370]

== Known changes for 1.2 ==

* [[Crafting#Recipe_difficulties|Expensive mode]] gets turned into a mod. [https://forums.factorio.com/viewtopic.php?p=577191#p577191]
* [[Train_stop#Circuit_Network|Train stop disabling]] will be removed. [https://forums.factorio.com/viewtopic.php?p=574563#p574563]
* Improvements to controlling [[Spidertron|spidertrons]]. [https://www.reddit.com/r/factorio/comments/6e6tkw/im_the_founder_of_factorio_kovarex_ama/jnncw10/]
* Added the ability to use the pipette anywhere, including the crafting menu. [https://forums.factorio.com/viewtopic.php?p=567550#p567550]
* Added the ability to automatically remove fuel from [[Locomotive|locomotives]]. [https://forums.factorio.com/viewtopic.php?p=577389#p577389]
* [[Ghost]] [[Pipe|pipes]] will visually connect to each other. [https://forums.factorio.com/viewtopic.php?p=578549#p578549]

== See also ==
* [https://factorio.com/blog/post/fff-365 Friday Facts #365 - Future plans]
* [https://factorio.com/blog/post/fff-367 Friday Facts #367]
* [https://factorio.com/blog/post/fff-370 Friday Facts #370]
* [[Roadmap|Planned releases]]

Types/EnergySource

2023-04-04T10:45:30Z

Xorimuth: Typo fix

== Basics ==
Specifies the way the entity gets its energy.
=== type ===
'''Type''': [[Types/string]]

Mandatory. Only valid values are "electric", "burner", "heat", "fluid" or "void", it specifies the type of the energy source to be used.

=== emissions_per_minute ===
'''Type''': [[Types/double]]

'''Default''': 0

Optional. The pollution an entity emits per minute at full energy consumption. <code>emissions_per_minute</code> is exactly the value that is shown in the entity tooltip.

=== render_no_power_icon ===
'''Type''': [[Types/bool]]

'''Default''': true

Optional. Whether to render the [[File:Electricity-icon-red.png|50px]] icon on the entity if it is low on power. Also applies to [[File:Fuel-icon-red.png|50px]] when using a burner energy source.

=== render_no_network_icon ===
'''Type''': [[Types/bool]]

'''Default''': true

Optional. Whether to render the [[File:Electricity-icon-unplugged.png|50px]] icon on the entity if it is not connected to a electric network.

== Electric energy source ==
=== buffer_capacity ===
'''Type''': [[Types/Energy]]

Optional. How much energy the entity holds.

=== usage_priority ===
'''Type''': [[Types/ElectricUsagePriority]]

Mandatory.
=== input_flow_limit ===
'''Type''': [[Types/Energy]]

'''Default''': max double

Optional. The rate at which energy can be taken, from the network, to refill the energy buffer. 0 means no transfer.

=== output_flow_limit ===
'''Type''': [[Types/Energy]]

'''Default''': max double

Optional. The rate at which energy can be provided, to the network, from the energy buffer. 0 means no transfer.

=== drain ===
'''Type''': [[Types/Energy]]

Optional. How much energy (per second) will be continuously removed from the energy buffer. In game, this is shown in the tooltip as "Min. ''[Minimum]'' Consumption". Applied as a constant consumption-per-tick, even when the entity has the property <code>active</code> false.

== Burner ==
=== fuel_inventory_size ===
'''Type''': [[Types/ItemStackIndex]]

Mandatory.

=== burnt_inventory_size ===
'''Type''': [[Types/ItemStackIndex]]

'''Default''': 0

Optional.

=== smoke ===
'''Type''': [[Types/table]] of [[Types/SmokeSource]]

Optional. Array of 1 or more smoke sources.

=== light_flicker ===
'''Type''': [[Types/LightFlickeringDefinition]]

Optional.

=== effectivity ===
'''Type''': [[Types/double]]

'''Default''': 1

Optional. 1 means 100% effectivity. Must be greater than 0. Multiplier of the energy output.

=== fuel_category ===
'''Type''': [[Types/string]]

'''Default''': "chemical"

Optional. The energy source can be used with fuel from this [[Prototype/FuelCategory|fuel category]]. For a list of built-in categories, see [[Data.raw#fuel-category]].

If <code>fuel_categories</code> is defined, fuel_category is ignored.

=== fuel_categories ===
'''Type''': [[Types/table]] of [[Types/string]]

Optional. Same as above, only one of them can exist. For a list of built-in categories, see [[Data.raw#fuel-category]].

Takes precedence over <code>fuel_category</code>.

== Heat energy source ==
=== max_temperature ===
'''Type''': [[Types/double]]

Mandatory. max_temperature must be >= default_temperature.

=== default_temperature ===
'''Type''': [[Types/double]]

'''Default''': 15

Optional.

=== specific_heat ===
'''Type''': [[Types/Energy]]

Mandatory.

=== max_transfer ===
'''Type''': [[Types/Energy]]

Mandatory.

=== min_temperature_gradient ===
'''Type''': [[Types/double]]

'''Default''': 1

Optional.

=== min_working_temperature ===
'''Type''': [[Types/double]]

'''Default''': 15

Optional. min_working_temperature must be >= default_temperature. min_working_temperature must be <= max_temperature.

=== minimum_glow_temperature ===
'''Type''': [[Types/float]]

'''Default''': 1

=== pipe_covers ===
'''Type''': [[Types/Sprite4Way]]

Optional.

=== heat_pipe_covers ===
'''Type''': [[Types/Sprite4Way]]

Optional.

=== heat_picture ===
'''Type''': [[Types/Sprite4Way]]

Optional.

=== heat_glow ===
'''Type''': [[Types/Sprite4Way]]

Optional.

=== connections ===
'''Type''': [[Types/table]] of [[Types/HeatConnection]]

Optional. The table may only contain up to 32 connections.

== Void energy source ==
Void is free energy, there are no additional entries required.
<syntaxhighlight lang="lua">
energy_source = {type = "void"}
</syntaxhighlight>

== Fluid energy source ==
=== fluid_box ===
'''Type''': [[Types/FluidBox]]

Mandatory.
All standard fluid box configurations are acceptable, but the type must be "input" or "input-output" to function correctly.
Scale_fluid_usage, fluid_usage_per_tick or a filter on the fluidbox must be set to be able to calculate the fluid usage of the energy source.

=== smoke ===
'''Type''': [[Types/table]] of [[Types/SmokeSource]]

Optional. Array of 1 or more smoke sources.

=== light_flicker ===
'''Type''': [[Types/LightFlickeringDefinition]]

Optional.

=== effectivity ===
'''Type''': [[Types/double]]

'''Default''': 1

Optional. 1 means 100% effectivity. Must be greater than 0. Multiplier of the energy output.

=== burns_fluid ===
'''Type''': [[Types/bool]]

'''Default''': false

Optional. If set to true, the energy source will calculate power based on the fluid's fuel_value entry, else it will calculate based on fluid temperature.

=== scale_fluid_usage ===
'''Type''': [[Types/bool]]

'''Default''': false

Optional. If set to true, the energy source will consume as much fluid as required to produce the desired power, if set to false it will consume as much as it is allowed to, wasting any excess.

=== destroy_non_fuel_fluid ===
'''Type''': [[Types/bool]]

'''Default''': true

Optional. This property is used when:
* <code>burns_fluid</code> is true and the fluid has a [[Prototype/Fluid#fuel_value|fuel_value]] of 0
* or <code>burns_fluid</code> is false and the fluid is at default temperature
In these cases, this property determines whether the fluid should be destroyed, meaning that the fluid is consumed at the rate of <code>fluid_usage_per_tick</code>, without producing any power.

=== fluid_usage_per_tick ===
'''Type''': [[Types/double]]

'''Default''': 0

Optional. The number of fluid units the energy source uses per tick.
If used with scale_fluid_usage, this specifies the maximum. If this value is not set, scale_energy_usage = false and a fluid box filter is set, the game will attempt to calculate this value from the fluid box filter's fluid's fuel_value or heat_capacity and the entity's energy_usage. If burns_fluid is false, maximum_temperature will also be used. If the attempt of the game to calculate this value fails ( scale_energy_usage = false and a fluid box filter is set), then scale_energy_usage will be forced to true, to prevent the energy source from being an infinite fluid sink.[https://forums.factorio.com/90613]

=== maximum_temperature ===
'''Type''': [[Types/double]]

'''Default''': 0, meaning unlimited

If it is specified while scale_fluid_usage = false and fluid_usage_per_tick is not specified, the game will use this value to calculate fluid_usage_per_tick.

{{Prototype property type usage|{{FULLPAGENAME}}}}

Prototype/CustomInput

2023-01-31T11:32:22Z

Xorimuth: Fix CustomInputEvent links to runtime docs

{{Prototype parent|PrototypeBase}}
Used for custom keyboard shortcuts/keybindings in mods. The key associated with the custom input can be changed in the options. This means that <code>key_sequence</code> is simply the default keybinding.

{{Prototype TOC|custom-input}}

== Mandatory properties ==
Inherits all properties from [[PrototypeBase]].

=== name ===
:''See [[PrototypeBase#name]]''

Inherited from [[PrototypeBase]]. It is also the name for the event that is raised when they key (combination) is pressed and action is "lua", see [[Tutorial:Script interfaces]].

{{Prototype property|key_sequence|[[Types/string|string]]}}
The default key sequence for this custom input.

* "" (empty string) for unassigned
* "mouse-button-2" etc for mouse buttons, mouse-button-3 for middle mouse button
* "mouse-wheel-up", "mouse-wheel-down", "mouse-wheel-left", "mouse-wheel-right" for mouse wheel
* " + " is used to separate modifier keys from normal keys: <code>"ALT + G"</code>
* For modifier keys, the following names are used: "CONTROL", "SHIFT", "ALT", "COMMAND"
* A keybinding can contain an unlimited amount of modifier keys (listed above) but only one normal key (listed below).

<div class="toccolours mw-collapsible mw-collapsed" style="width: 40em;">
These names are available for the normal keys
<pre class="mw-collapsible-content">
A
B
C
D
E
F
G
H
I
J
K
L
M
N
O
P
Q
R
S
T
U
V
W
X
Y
Z
1
2
3
4
5
6
7
8
9
0
RETURN
ESCAPE
BACKSPACE
TAB
SPACE
MINUS
EQUALS
LEFTBRACKET
RIGHTBRACKET
BACKSLASH
NONUSHASH
SEMICOLON
APOSTROPHE
GRAVE
COMMA
PERIOD
SLASH
CAPSLOCK
F1
F2
F3
F4
F5
F6
F7
F8
F9
F10
F11
F12
PRINTSCREEN
SCROLLLOCK
PAUSE
INSERT
HOME
PAGEUP
DELETE
END
PAGEDOWN
RIGHT
LEFT
DOWN
UP
NUMLOCKCLEAR
KP_DIVIDE
KP_MULTIPLY
KP_MINUS
KP_PLUS
KP_ENTER
KP_1
KP_2
KP_3
KP_4
KP_5
KP_6
KP_7
KP_8
KP_9
KP_0
KP_PERIOD
NONUSBACKSLASH
APPLICATION
POWER
KP_EQUALS
F13
F14
F15
F16
F17
F18
F19
F20
F21
F22
F23
F24
EXECUTE
HELP
MENU
SELECT
STOP
AGAIN
UNDO
CUT
COPY
PASTE
FIND
MUTE
VOLUMEUP
VOLUMEDOWN
KP_COMMA
KP_EQUALSAS400
INTERNATIONAL1
INTERNATIONAL2
INTERNATIONAL3
INTERNATIONAL4
INTERNATIONAL5
INTERNATIONAL6
INTERNATIONAL7
INTERNATIONAL8
INTERNATIONAL9
LANG1
LANG2
LANG3
LANG4
LANG5
LANG6
LANG7
LANG8
LANG9
ALTERASE
SYSREQ
CANCEL
CLEAR
PRIOR
RETURN2
SEPARATOR
OUT
OPER
CLEARAGAIN
CRSEL
EXSEL
KP_00
KP_000
THOUSANDSSEPARATOR
DECIMALSEPARATOR
CURRENCYUNIT
CURRENCYSUBUNIT
KP_LEFTPAREN
KP_RIGHTPAREN
KP_LEFTBRACE
KP_RIGHTBRACE
KP_TAB
KP_BACKSPACE
KP_A
KP_B
KP_C
KP_D
KP_E
KP_F
KP_XOR
KP_POWER
KP_PERCENT
KP_LESS
KP_GREATER
KP_AMPERSAND
KP_DBLAMPERSAND
KP_VERTICALBAR
KP_DBLVERTICALBAR
KP_COLON
KP_HASH
KP_SPACE
KP_AT
KP_EXCLAM
KP_MEMSTORE
KP_MEMRECALL
KP_MEMCLEAR
KP_MEMADD
KP_MEMSUBTRACT
KP_MEMMULTIPLY
KP_MEMDIVIDE
KP_PLUSMINUS
KP_CLEAR
KP_CLEARENTRY
KP_BINARY
KP_OCTAL
KP_DECIMAL
KP_HEXADECIMAL
LCTRL
LSHIFT
LALT
LGUI
RCTRL
RSHIFT
RALT
RGUI
MODE
AUDIONEXT
AUDIOPREV
AUDIOSTOP
AUDIOPLAY
AUDIOMUTE
MEDIASELECT
WWW
MAIL
CALCULATOR
COMPUTER
AC_SEARCH
AC_HOME
AC_BACK
AC_FORWARD
AC_STOP
AC_REFRESH
AC_BOOKMARKS
BRIGHTNESSDOWN
BRIGHTNESSUP
DISPLAYSWITCH
KBDILLUMTOGGLE
KBDILLUMDOWN
KBDILLUMUP
EJECT
SLEEP
APP1
APP2
AUDIOREWIND
AUDIOFASTFORWARD
</pre>
</div>

== Optional properties ==

{{Prototype property|alternative_key_sequence|[[Types/string|string]]|optional=true}}
The alternative keybinding for this control. See [[#key_sequence]].

{{Prototype property|linked_game_control|[[Types/string|string]]|""|optional=true}}
When a custom-input is linked to a game control it won't show up in the control-settings GUI and will fire when the linked control is pressed. [https://forums.factorio.com/53591]

<div class="toccolours mw-collapsible mw-collapsed" style="width: 40em;">
List of internal names of game controls
<pre class="mw-collapsible-content">
action-bar-select-page-1
action-bar-select-page-10
action-bar-select-page-2
action-bar-select-page-3
action-bar-select-page-4
action-bar-select-page-5
action-bar-select-page-6
action-bar-select-page-7
action-bar-select-page-8
action-bar-select-page-9
activate-tooltip
add-station
add-temporary-station
alt-zoom-in
alt-zoom-out
build
build-ghost
build-with-obstacle-avoidance
cancel-craft
cancel-craft-5
cancel-craft-all
clear-cursor
confirm-gui
confirm-message
connect-train
controller-gui-crafting-tab
controller-gui-logistics-tab
copy
copy-entity-settings
craft
craft-5
craft-all
cursor-split
cut
cycle-blueprint-backwards
cycle-blueprint-forwards
cycle-clipboard-backwards
cycle-clipboard-forwards
debug-reset-zoom
debug-reset-zoom-2x
debug-toggle-atlas-gui
debug-toggle-basic
debug-toggle-debug-settings
decrease-ui-scale
disconnect-train
drag-map
drop-cursor
editor-clone-item
editor-delete-item
editor-next-variation
editor-previous-variation
editor-remove-scripting-object
editor-reset-speed
editor-set-clone-brush-destination
editor-set-clone-brush-source
editor-speed-down
editor-speed-up
editor-switch-to-surface
editor-tick-once
editor-toggle-pause
fast-entity-split
fast-entity-transfer
flip-blueprint-horizontal
flip-blueprint-vertical
focus-search
increase-ui-scale
inventory-split
inventory-transfer
larger-terrain-building-area
logistic-networks
mine
move-down
move-left
move-right
move-up
next-active-quick-bar
next-player-in-replay
next-weapon
open-character-gui
open-gui
open-item
open-prototype-explorer-gui
open-prototypes-gui
open-technology-gui
open-trains-gui
order-to-follow
paste
paste-entity-settings
pause-game
pick-item
pick-items
place-in-chat
place-ping
previous-active-quick-bar
previous-mod
previous-technology
production-statistics
quick-bar-button-1
quick-bar-button-1-secondary
quick-bar-button-10
quick-bar-button-10-secondary
quick-bar-button-2
quick-bar-button-2-secondary
quick-bar-button-3
quick-bar-button-3-secondary
quick-bar-button-4
quick-bar-button-4-secondary
quick-bar-button-5
quick-bar-button-5-secondary
quick-bar-button-6
quick-bar-button-6-secondary
quick-bar-button-7
quick-bar-button-7-secondary
quick-bar-button-8
quick-bar-button-8-secondary
quick-bar-button-9
quick-bar-button-9-secondary
remove-pole-cables
reset-ui-scale
reverse-rotate
reverse-select
rotate
rotate-active-quick-bars
select-for-blueprint
select-for-cancel-deconstruct
shoot-enemy
shoot-selected
show-info
smaller-terrain-building-area
smart-pipette
stack-split
stack-transfer
toggle-blueprint-library
toggle-console
toggle-driving
toggle-filter
toggle-gui-debug
toggle-gui-glows
toggle-gui-shadows
toggle-gui-style-view
toggle-map
toggle-menu
undo
zoom-in
zoom-out
</pre></div>

Example to use the same key sequence as the clear-cursor hotkey:
<syntaxhighlight lang="lua">key_sequence = ""
linked_game_control = "clear-cursor"</syntaxhighlight>

{{Prototype property|consuming|[[Types/ConsumingType|ConsumingType]]|"none"|optional=true}}
Sets whether internal game events associated with the same key sequence should be fired or blocked. If they are fired ("none"), then the custom input event will happen before the internal game event.

{{Prototype property|enabled|[[Types/bool|bool]]|true|optional=true}}
If this custom input is enabled. Disabled custom inputs exist but are not used by the game. If disabled, no event is raised when the input is used.

{{Prototype property|enabled_while_spectating|[[Types/bool|bool]]|false|optional=true}}

{{Prototype property|enabled_while_in_cutscene|[[Types/bool|bool]]|false|optional=true}}

{{Prototype property|include_selected_prototype|[[Types/bool|bool]]|false|optional=true}}
If true, the type and name of the currently selected prototype will be provided as "selected_prototype" in the raised [https://lua-api.factorio.com/latest/events.html#CustomInputEvent lua event]. This also works in GUI's, not just the game world.[https://forums.factorio.com/96125]

This will also return an item in the cursor such as copper-wire or rail-planner, if nothing is beneath the cursor.

{{Prototype property|item_to_spawn|[[Types/string|string]]|optional=true}}
Name of a [[Prototype/Item]]. It will be created when this input is pressed and action is set to "spawn-item". The item must have the [[Types/ItemPrototypeFlags#.22spawnable.22|"spawnable"]] flag set.

{{Prototype property|action|[[Types/string|string]]|"lua"|optional=true}}
One of "lua", "spawn-item", "toggle-personal-roboport", "toggle-personal-logistic-requests" and "toggle-equipment-movement-bonus".

A [https://lua-api.factorio.com/latest/events.html#CustomInputEvent lua event] is only raised if the action is "lua".

Types/SpiderVehicleGraphicsSet

2023-01-07T01:24:00Z

Xorimuth: /* light_positions */ eyelight -> eye_light

Used to specify the graphics for [[Prototype/SpiderVehicle]].

== Optional properties ==
=== base_animation ===
'''Type''': [[Types/RotatedAnimation|RotatedAnimation]]

=== shadow_base_animation ===
'''Type''': [[Types/RotatedAnimation|RotatedAnimation]]

=== animation ===
'''Type''': [[Types/RotatedAnimation|RotatedAnimation]]

=== shadow_animation ===
'''Type''': [[Types/RotatedAnimation|RotatedAnimation]]

=== base_render_layer ===
'''Type''': [[Types/RenderLayer|RenderLayer]]

'''Default''': "higher-object-under"

=== render_layer ===
'''Type''': [[Types/RenderLayer|RenderLayer]]

'''Default''': "wires-above"

=== autopilot_destination_visualisation_render_layer ===
'''Type''': [[Types/RenderLayer|RenderLayer]]

'''Default''': "object"

=== light ===
'''Type''': [[Types/LightDefinition|LightDefinition]]

=== eye_light ===
'''Type''': [[Types/LightDefinition|LightDefinition]]

Placed in multiple positions, as determined by [[#light_positions]].

=== autopilot_destination_on_map_visualisation ===
'''Type''': [[Types/Animation|Animation]]

=== autopilot_destination_queue_on_map_visualisation ===
'''Type''': [[Types/Animation|Animation]]

=== autopilot_destination_visualisation ===
'''Type''': [[Types/Animation|Animation]]

=== autopilot_destination_queue_visualisation ===
'''Type''': [[Types/Animation|Animation]]

=== autopilot_path_visualisation_line_width ===
'''Type''': [[Types/float|float]]

'''Default''': 0.125

=== autopilot_path_visualisation_on_map_line_width ===
'''Type''': [[Types/float|float]]

'''Default''': 2.0

=== light_positions ===
'''Type''': [[Types/table|array]] of [[Types/table|array]] of [[Types/vector|vector]]

Defines where each [[#eye_light]] is placed. One array per eye and each of those arrays should contain one position per body direction.

Prototype/SpiderVehicle

2022-11-27T23:32:46Z

Xorimuth: /* Optional properties */ Add note about disabling spidertron logistics to trash_inventory_size

{{Prototype parent|Prototype/Vehicle}}
The [[spidertron]].

{{Prototype TOC|spider-vehicle}}

== Mandatory properties ==
This prototype inherits all the properties from [[Prototype/Vehicle]].

{{Prototype property|burner or energy_source|[[Types/EnergySource|EnergySource]]}}
Must be a burner energy source when using "burner", otherwise it can also be a void energy source.

{{Prototype property|inventory_size|[[Types/ItemStackIndex|ItemStackIndex]]}}

{{Prototype property|graphics_set|[[Types/SpiderVehicleGraphicsSet|SpiderVehicleGraphicsSet]]}}

{{Prototype property|spider_engine|[[Types/SpiderEnginePrototype|SpiderEnginePrototype]]}}

{{Prototype property|height|[[Types/float|float]]}}
The height of the spider affects the shooting height and the drawing of the graphics and lights.

{{Prototype property|chunk_exploration_radius|[[Types/uint32|uint32]]}}

{{Prototype property|movement_energy_consumption|[[Types/Energy|Energy]]}}

{{Prototype property|automatic_weapon_cycling|[[Types/bool|bool]]}}

{{Prototype property|chain_shooting_cooldown_modifier|[[Types/float|float]]}}
This is applied whenever the spider shoots (manual and automatic targeting), <code>automatic_weapon_cycling</code> is true and the next gun in line (which is then selected) has ammo.<br>
When all of the above is the case, the chain_shooting_cooldown_modifier is a multiplier on the remaining shooting cooldown: <code><nowiki>cooldown = (remaining_cooldown × chain_shooting_cooldown_modifier)</nowiki></code>. chain_shooting_cooldown_modifier is intended to be in the range of 0 to 1. This means that setting chain_shooting_cooldown_modifier to 0 reduces the remaining shooting cooldown to 0 while a chain_shooting_cooldown_modifier of 1 does not affect the remaining shooting cooldown at all.

== Optional properties ==

{{Prototype property|torso_rotation_speed|[[Types/float|float]]|1|optional=true}}
The orientation of the torso of the spider affects the shooting direction and the drawing of the graphics and lights.

{{Prototype property|torso_bob_speed|[[Types/float|float]]|1|optional=true}}
Cannot be negative.

{{Prototype property|trash_inventory_size|[[Types/ItemStackIndex|ItemStackIndex]]|0|optional=true}}
If set to 0 then the spider will not have a '''Logistics''' tab.

{{Prototype property|guns|[[Types/table|table]] of [[Types/string|string]]s of prototype names|optional=true}}
The guns this spider vehicle uses.

Types/FluidBox

2022-09-01T12:32:31Z

Xorimuth: /* Optional properties */ Document new hide_connection_info option

== Basics ==
[[File:Fluidboxes.png|thumb|550px|Visual representation of base_area, base_level and height. When all the fluidboxes are connected, the water leaves fluidbox A and flows into the other 3 boxes through fluidbox B until the water level is equal in all boxes. For more info about fluids, see [[Fluid system#See also]].]]
Used to set the fluid amount an entity can hold, as well as the connection points for pipes leading into and out of the entity.

Entities can have multiple fluidboxes. These can be part of a [[Types/EnergySource#Fluid_energy_source]] or be specified directly in the entity prototype.

A fluidbox can store only one type of fluid at a time. However, a fluid system (multiple connected fluid boxes) can contain multiple different fluids, see [[Fluid_system#Fluid_mixing]].

== Mandatory properties ==

=== pipe_connections ===
'''Type''': [[Types/table]] of [[Types/PipeConnectionDefinition]]

Max number of members is 255.

Connection points to connect to other fluidboxes. This is also marked as blue arrows in alt mode.
Fluid may flow in or out depending on the `type` field of each connection.
Connection points may depend on the direction the entity is facing.

== Optional properties ==

=== base_area ===
'''Type''': [[Types/double]]

'''Default''': 1

Must be greater than 0. The total fluid capacity of the fluid box is <code>base_area × height × 100</code>.

=== base_level ===
'''Type''': [[Types/double]]

'''Default''': 0

=== height ===
'''Type''': [[Types/double]]

'''Default''': 1

Must be greater than 0. The total fluid capacity of the fluid box is <code>base_area × height × 100</code>.

=== filter ===
'''Type''': [[Types/string]]

Name of a [[Prototype/Fluid]]. Can be used to specify which fluid is allowed to enter this fluid box. [https://forums.factorio.com/viewtopic.php?f=28&t=46302]

=== render_layer ===
'''Type''': [[Types/RenderLayer]]

'''Default''': "object"

=== hide_connection_info ===
'''Type''': [[Types/bool]]

'''Default''': false

Hides the blue input/output arrows and icons at each connection point.

=== pipe_covers ===
'''Type''': [[Types/Sprite4Way]]

The pictures to show when another fluid box connects to this one.

=== pipe_picture ===
'''Type''': [[Types/Sprite4Way]]

=== minimum_temperature ===
'''Type''': [[Types/double]]

The minimum temperature allowed into the fluidbox. Only applied if a <code>filter</code> is specified [https://forums.factorio.com/viewtopic.php?p=496738#p496738].

<syntaxhighlight lang="lua">minimum_temperature = 100.0</syntaxhighlight>

=== maximum_temperature ===
'''Type''': [[Types/double]]

The maximum temperature allowed into the fluidbox. Only applied if a <code>filter</code> is specified [https://forums.factorio.com/viewtopic.php?p=496738#p496738].

<syntaxhighlight lang="lua">maximum_temperature = 1000.0</syntaxhighlight>

=== production_type ===
'''Type''': [[Types/string]]

'''Default''': "None"

Possible values:
* "None" or "none"
* "input"
* "input-output"
* "output"

=== secondary_draw_order ===
'''Type''': [[Types/int8]]

'''Default''': 1

Set the secondary draw order for all orientations. Used to determine render order for sprites with the same <code>render_layer</code> in the same position. Sprites with a higher <code>secondary_draw_order</code> are drawn on top.

=== secondary_draw_orders ===
'''Type''': [[Types/table]] of [[Types/int8]]

'''Default''': {north = 1, east = 1, south = 1, west = 1}

Set the secondary draw order for each orientation. Used to determine render order for sprites with the same <code>render_layer</code> in the same position. Sprites with a higher <code>secondary_draw_order</code> are drawn on top.

== Example ==

<syntaxhighlight lang="lua">fluid_box =
{
base_area = 1,
height = 2,
base_level = -1,
pipe_covers = pipecoverspictures(),
pipe_connections =
{
{type = "input-output", position = {-2, 0.5}},
{type = "input-output", position = {2, 0.5}}
},
production_type = "input-output"
},
</syntaxhighlight>

Types/SpiderVehicleGraphicsSet

2022-01-21T00:56:28Z

Xorimuth: /* light_positions */ Fix missing plural

Used to specify the graphics for [[Prototype/SpiderVehicle]].

== Optional properties ==
=== base_animation ===
'''Type''': [[Types/RotatedAnimation|RotatedAnimation]]

=== shadow_base_animation ===
'''Type''': [[Types/RotatedAnimation|RotatedAnimation]]

=== animation ===
'''Type''': [[Types/RotatedAnimation|RotatedAnimation]]

=== shadow_animation ===
'''Type''': [[Types/RotatedAnimation|RotatedAnimation]]

=== base_render_layer ===
'''Type''': [[Types/RenderLayer|RenderLayer]]

'''Default''': "higher-object-under"

=== render_layer ===
'''Type''': [[Types/RenderLayer|RenderLayer]]

'''Default''': "wires-above"

=== autopilot_destination_visualisation_render_layer ===
'''Type''': [[Types/RenderLayer|RenderLayer]]

'''Default''': "object"

=== light ===
'''Type''': [[Types/LightDefinition|LightDefinition]]

=== eye_light ===
'''Type''': [[Types/LightDefinition|LightDefinition]]

Placed in multiple positions, as determined by [[#light_positions]].

=== autopilot_destination_on_map_visualisation ===
'''Type''': [[Types/Animation|Animation]]

=== autopilot_destination_queue_on_map_visualisation ===
'''Type''': [[Types/Animation|Animation]]

=== autopilot_destination_visualisation ===
'''Type''': [[Types/Animation|Animation]]

=== autopilot_destination_queue_visualisation ===
'''Type''': [[Types/Animation|Animation]]

=== autopilot_path_visualisation_line_width ===
'''Type''': [[Types/float|float]]

'''Default''': 0.125

=== autopilot_path_visualisation_on_map_line_width ===
'''Type''': [[Types/float|float]]

'''Default''': 2.0

=== light_positions ===
'''Type''': [[Types/table|array]] of [[Types/table|array]] of [[Types/vector|vector]]

Defines where each [[#eyelight]] is placed. One array per eye and each of those arrays should contain one position per body direction.

Types/SpiderVehicleGraphicsSet

2022-01-06T19:56:04Z

Xorimuth: Add eye_light and light_positions explanations.

Used to specify the graphics for [[Prototype/SpiderVehicle]].

== Optional properties ==
=== base_animation ===
'''Type''': [[Types/RotatedAnimation|RotatedAnimation]]

=== shadow_base_animation ===
'''Type''': [[Types/RotatedAnimation|RotatedAnimation]]

=== animation ===
'''Type''': [[Types/RotatedAnimation|RotatedAnimation]]

=== shadow_animation ===
'''Type''': [[Types/RotatedAnimation|RotatedAnimation]]

=== base_render_layer ===
'''Type''': [[Types/RenderLayer|RenderLayer]]

'''Default''': "higher-object-under"

=== render_layer ===
'''Type''': [[Types/RenderLayer|RenderLayer]]

'''Default''': "wires-above"

=== autopilot_destination_visualisation_render_layer ===
'''Type''': [[Types/RenderLayer|RenderLayer]]

'''Default''': "object"

=== light ===
'''Type''': [[Types/LightDefinition|LightDefinition]]

=== eye_light ===
'''Type''': [[Types/LightDefinition|LightDefinition]]

Placed in multiple positions, as determined by [[#light_positions]].

=== autopilot_destination_on_map_visualisation ===
'''Type''': [[Types/Animation|Animation]]

=== autopilot_destination_queue_on_map_visualisation ===
'''Type''': [[Types/Animation|Animation]]

=== autopilot_destination_visualisation ===
'''Type''': [[Types/Animation|Animation]]

=== autopilot_destination_queue_visualisation ===
'''Type''': [[Types/Animation|Animation]]

=== autopilot_path_visualisation_line_width ===
'''Type''': [[Types/float|float]]

'''Default''': 0.125

=== autopilot_path_visualisation_on_map_line_width ===
'''Type''': [[Types/float|float]]

'''Default''': 2.0

=== light_positions ===
'''Type''': [[Types/table|array]] of [[Types/table|array]] of [[Types/vector|vector]]

Defines where each [[#eyelight]] is placed. One array per eye and each array should contain one position per body direction.

Prototype/Entity

2021-11-05T17:01:02Z

Xorimuth: /* Optional properties */ Added selection_priority tie-breaker information

{{Prototype parent|PrototypeBase}}
Abstract base of all entities in the game.
Entity is basically everything that can be on the map (except tiles).
For in game script access to entity, take a look at [http://lua-api.factorio.com/latest/LuaEntity.html LuaEntity]

{{Prototype TOC|''abstract''}}

== Extensions ==
<div class="factorio-list">
* [[Prototype/Arrow]] '''arrow'''
* [[Prototype/ArtilleryFlare]] '''artillery-flare'''
* [[Prototype/ArtilleryProjectile]] '''artillery-projectile'''
* [[Prototype/Beam]] '''beam'''
* [[Prototype/CharacterCorpse]] '''character-corpse'''
* [[Prototype/Cliff]] '''cliff'''
* [[Prototype/Corpse]] '''corpse'''
** [[Prototype/RailRemnants]] '''rail-remnants'''
* [[Prototype/DeconstructibleTileProxy]] '''deconstructible-tile-proxy'''
* [[Prototype/EntityGhost]] '''entity-ghost'''
* [[Prototype/EntityParticle]] '''particle''' (for migration, cannot be used)
** [[Prototype/LeafParticle]] '''leaf-particle''' (for migration, cannot be used)
* [[Prototype/EntityWithHealth]] <abstract>
** [[Prototype/Accumulator]] '''accumulator'''
** [[Prototype/ArtilleryTurret]] '''artillery-turret'''
** [[Prototype/Beacon]] '''beacon'''
** [[Prototype/Boiler]] '''boiler'''
** [[Prototype/BurnerGenerator]] '''burner-generator'''
** [[Prototype/Character]] '''character'''
** [[Prototype/Combinator]] <abstract>
*** [[Prototype/ArithmeticCombinator]] '''arithmetic-combinator'''
*** [[Prototype/DeciderCombinator]] '''decider-combinator'''
** [[Prototype/ConstantCombinator]] '''constant-combinator'''
** [[Prototype/Container]] '''container'''
*** [[Prototype/LogisticContainer]] '''logistic-container'''
**** [[Prototype/InfinityContainer]] '''infinity-container'''
** [[Prototype/CraftingMachine]] <abstract>
*** [[Prototype/AssemblingMachine]] '''assembling-machine'''
**** [[Prototype/RocketSilo]] '''rocket-silo'''
*** [[Prototype/Furnace]] '''furnace'''
** [[Prototype/ElectricEnergyInterface]] '''electric-energy-interface'''
** [[Prototype/ElectricPole]] '''electric-pole'''
** [[Prototype/EnemySpawner]] '''unit-spawner'''
** [[Prototype/Fish]] '''fish'''
** [[Prototype/FlyingRobot]] <abstract>
*** [[Prototype/CombatRobot]] '''combat-robot'''
*** [[Prototype/RobotWithLogisticInterface]] <abstract>
**** [[Prototype/ConstructionRobot]] '''construction-robot'''
**** [[Prototype/LogisticRobot]] '''logistic-robot'''
** [[Prototype/Gate]] '''gate'''
** [[Prototype/Generator]] '''generator'''
** [[Prototype/HeatInterface]] '''heat-interface'''
** [[Prototype/HeatPipe]] '''heat-pipe'''
** [[Prototype/Inserter]] '''inserter'''
** [[Prototype/Lab]] '''lab'''
** [[Prototype/Lamp]] '''lamp'''
** [[Prototype/LandMine]] '''land-mine'''
** [[Prototype/LinkedContainer]] '''linked-container'''
** [[Prototype/Market]] '''market'''
** [[Prototype/MiningDrill]] '''mining-drill'''
** [[Prototype/OffshorePump]] '''offshore-pump'''
** [[Prototype/Pipe]] '''pipe'''
*** [[Prototype/InfinityPipe]] '''infinity-pipe'''
** [[Prototype/PipeToGround]] '''pipe-to-ground'''
** [[Prototype/PlayerPort]] '''player-port'''
** [[Prototype/PowerSwitch]] '''power-switch'''
** [[Prototype/ProgrammableSpeaker]] '''programmable-speaker'''
** [[Prototype/Pump]] '''pump'''
** [[Prototype/Radar]] '''radar'''
** [[Prototype/Rail]] <abstract>
*** [[Prototype/CurvedRail]] '''curved-rail'''
*** [[Prototype/StraightRail]] '''straight-rail'''
** [[Prototype/RailSignalBase]] <abstract>
*** [[Prototype/RailChainSignal]] '''rail-chain-signal'''
*** [[Prototype/RailSignal]] '''rail-signal'''
** [[Prototype/Reactor]] '''reactor'''
** [[Prototype/Roboport]] '''roboport'''
** [[Prototype/SimpleEntity]] '''simple-entity'''
** [[Prototype/SimpleEntityWithOwner]] '''simple-entity-with-owner'''
** [[Prototype/SimpleEntityWithForce]] '''simple-entity-with-force'''
** [[Prototype/SolarPanel]] '''solar-panel'''
** [[Prototype/SpiderLeg]] '''spider-leg'''
** [[Prototype/StorageTank]] '''storage-tank'''
** [[Prototype/TrainStop]] '''train-stop'''
** [[Prototype/TransportBeltConnectable]] <abstract>
*** [[Prototype/LinkedBelt]] '''linked-belt'''
*** [[Prototype/Loader1x1]] '''loader-1x1'''
*** [[Prototype/Loader1x2]] '''loader'''
*** [[Prototype/Splitter]] '''splitter'''
*** [[Prototype/TransportBelt]] '''transport-belt'''
*** [[Prototype/UndergroundBelt]] '''underground-belt'''
** [[Prototype/Tree]] '''tree'''
** [[Prototype/Turret]] '''turret'''
*** [[Prototype/AmmoTurret]] '''ammo-turret'''
*** [[Prototype/ElectricTurret]] '''electric-turret'''
*** [[Prototype/FluidTurret]] '''fluid-turret'''
** [[Prototype/Unit]] '''unit'''
** [[Prototype/Vehicle]] <abstract>
*** [[Prototype/Car]] '''car'''
*** [[Prototype/RollingStock]] <abstract>
**** [[Prototype/ArtilleryWagon]] '''artillery-wagon'''
**** [[Prototype/CargoWagon]] '''cargo-wagon'''
**** [[Prototype/FluidWagon]] '''fluid-wagon'''
**** [[Prototype/Locomotive]] '''locomotive'''
*** [[Prototype/SpiderVehicle]] '''spider-vehicle'''
** [[Prototype/Wall]] '''wall'''
* [[Prototype/Explosion]] '''explosion'''
** [[Prototype/FlameThrowerExplosion]] '''flame-thrower-explosion'''
* [[Prototype/FireFlame]] '''fire'''
* [[Prototype/FluidStream]] '''stream'''
* [[Prototype/FlyingText]] '''flying-text'''
* [[Prototype/HighlightBoxEntity]] '''highlight-box'''
* [[Prototype/ItemEntity]] '''item-entity'''
* [[Prototype/ItemRequestProxy]] '''item-request-proxy'''
* [[Prototype/ParticleSource]] '''particle-source'''
* [[Prototype/Projectile]] '''projectile'''
* [[Prototype/ResourceEntity]] '''resource'''
* [[Prototype/RocketSiloRocket]] '''rocket-silo-rocket'''
* [[Prototype/RocketSiloRocketShadow]] '''rocket-silo-rocket-shadow'''
* [[Prototype/Smoke]] <abstract>
** [[Prototype/SimpleSmoke]] '''smoke''' (for migration, cannot be used)
** [[Prototype/SmokeWithTrigger]] '''smoke-with-trigger'''
* [[Prototype/SpeechBubble]] '''speech-bubble'''
* [[Prototype/Sticker]] '''sticker'''
* [[Prototype/TileGhost]] '''tile-ghost'''
</div>

== Mandatory properties ==
Inherits all properties from [[PrototypeBase]].

{{Prototype property|icons, icon, icon_size (IconSpecification)|[[Types/IconSpecification|IconSpecification]]}}
An icon is mandatory for entities that have at least one of these flags active: placeable-neutral, placeable-player, placeable-enemy.

The icon will be used in the editor building selection and the bonus gui.
<syntaxhighlight lang="lua">icon = "__base__/graphics/icons/wooden-chest.png"</syntaxhighlight>

== Optional properties ==

=== order ===
:''See [[PrototypeBase#order]]''
Inherited from [[PrototypeBase]].

The order string is taken from the items in <code>placeable_by</code> if they exist, or from an item that has its [[Prototype/Item#place_result|place_result]] set to this entity if it exists.

{{Prototype property|collision_box|[[Types/BoundingBox|BoundingBox]]|Empty=<nowiki>{{0, 0}, {0, 0}} means no collisions.</nowiki>|optional=true}}
Specification of the entity collision boundaries.

Empty collision box is used for smoke, projectiles, particles, explosions etc.
<syntaxhighlight lang="lua">collision_box = {{-0.4, -0.4}, {0.4, 0.4}}</syntaxhighlight>
The {0,0} coordinate in the collision box will match the entity position.

It should be near the center of the collision box, to keep correct entity drawing order. It must include the {0,0} coordinate.

Note, that for buildings, it is customary to leave 0.1 wide border between the edge of the tile and the edge of the building, this lets the player move between the building and electric poles/inserters etc.

{{Prototype property|collision_mask|[[Types/CollisionMask|CollisionMask]]|<nowiki>{"item-layer", "object-layer", "player-layer", "water-tile"}</nowiki>|optional=true}}

Two entities can collide only if they share a layer from the collision mask.

<div class="toccolours mw-collapsible mw-collapsed">
NOTE: '''Some entity types have their own default''' that differs from the above default. They are listed here:
<div class="mw-collapsible-content">
* [[Prototype/Arrow]] - no masks
* [[Prototype/ArtilleryFlare]] - no masks
* [[Prototype/ArtilleryProjectile]] - no masks
* [[Prototype/Beam]] - no masks
* [[Prototype/Car]] - <code>{"player-layer", "train-layer", "consider-tile-transitions"}</code>
* [[Prototype/Character]] - <code>{"player-layer", "train-layer", "consider-tile-transitions"}</code>
* [[Prototype/CharacterCorpse]] - no masks
* [[Prototype/Cliff]] - <code>{ "item-layer", "object-layer", "player-layer", "water-tile", "not-colliding-with-itself"}</code>
* [[Prototype/Corpse]] - no masks
* [[Prototype/DeconstructibleTileProxy]] - <code>{"ground-tile"}</code>
* [[Prototype/EntityGhost]] - <code>{"ghost-layer"}</code>
* [[Prototype/EntityParticle]] - no masks
* [[Prototype/Explosion]] - no masks
* [[Prototype/FireFlame]] - no masks
* [[Prototype/Fish]] - <code>{"ground-tile", "colliding-with-tiles-only"}</code>
* [[Prototype/FluidStream]] - no masks
* [[Prototype/FlyingRobot]] - no masks
* [[Prototype/FlyingText]] - no masks
* [[Prototype/Gate]] - <code>{"item-layer", "object-layer", "player-layer", "water-tile", "train-layer"}</code>
* [[Prototype/HeatPipe]] - <code>{"object-layer", "floor-layer", "water-tile"}</code>
* [[Prototype/HighlightBoxEntity]] - no masks
* [[Prototype/ItemEntity]] - <code>{"item-layer"}</code>
* [[Prototype/ItemRequestProxy]] - no masks
* [[Prototype/LandMine]] - <code>{"object-layer", "water-tile"}</code>
* [[Prototype/LinkedBelt]] - <code>{"object-layer", "item-layer", "transport-belt-layer", "water-tile"}</code>
* [[Prototype/Loader1x1]] - <code>{"object-layer", "item-layer", "transport-belt-layer", "water-tile"}</code>
* [[Prototype/Loader1x2]] - <code>{"object-layer", "item-layer", "transport-belt-layer", "water-tile"}</code>
* [[Prototype/ParticleSource]] - no masks
* [[Prototype/PlayerPort]] - <code>{"object-layer", "floor-layer", "water-tile"}</code>
* [[Prototype/Projectile]] - no masks
* [[Prototype/Rail]] - <code>{"item-layer", "object-layer", "rail-layer", "floor-layer", "water-tile"}</code>
* [[Prototype/RailSignalBase]] - <code>{"floor-layer", "rail-layer", "item-layer"}</code>
* [[Prototype/ResourceEntity]] - <code>{"resource-layer"}</code>
* [[Prototype/RollingStock]] - <code>{"train-layer"}</code>
* [[Prototype/Smoke]] - no masks
* [[Prototype/SpeechBubble]] - no masks
* [[Prototype/SpiderLeg]] - <code>{"player-layer", "rail-layer"}</code>
* [[Prototype/Splitter]] - <code>{"object-layer", "item-layer", "transport-belt-layer", "water-tile"}</code>
* [[Prototype/Sticker]] - no masks
* [[Prototype/TileGhost]] - <code>{"ghost-layer"}</code>
* [[Prototype/TransportBelt]] - <code>{"object-layer", "floor-layer", "transport-belt-layer", "water-tile"}</code>
* [[Prototype/UndergroundBelt]] - <code>{"object-layer", "item-layer", "transport-belt-layer", "water-tile"}</code>
* [[Prototype/Unit]] - <code>{"player-layer", "train-layer", "not-colliding-with-itself"}</code>
* [[Prototype/Vehicle]] - <code>{"player-layer", "train-layer"}</code>
</div></div>

{{Prototype property|map_generator_bounding_box|[[Types/BoundingBox|BoundingBox]]|The value of collision box.|optional=true}}
Used instead of the collision box during map generation. Allows space entities differently during map generation, for example if the box is bigger, the entities will be placed farther apart.

{{Prototype property|selection_box|[[Types/BoundingBox|BoundingBox]]|<nowiki>Empty = {{0, 0}, {0, 0}}</nowiki>|optional=true}}
Specification of the entity selection area.
When empty the entity will have no selection area (and thus is not selectable).
<syntaxhighlight lang="lua">selection_box = {{-0.5, -0.5}, {0.5, 0.5}}</syntaxhighlight>
The selection box is usually a little bit bigger than the collision box, for tilable entities (like buildings) it should match the tile size of the building.

{{Prototype property|drawing_box|[[Types/BoundingBox|BoundingBox]]|<nowiki>Empty = {{0, 0}, {0, 0}} (selection_box is used instead)</nowiki>|optional=true}}
Specification of space needed to see the whole entity.

This is used to calculate the correct zoom and positioning in the entity info gui.
<syntaxhighlight lang="lua">drawing_box = {{-0.5, -0.5}, {0.5, 0.5}}</syntaxhighlight>

{{Prototype property|sticker_box|[[Types/BoundingBox|BoundingBox]]|The value of collision box.|optional=true}}
Used to set the area of the entity that can have stickers on it, currently only used for units to specify the area where the green slow down stickers can appear.
It is optional and the collision box is used when not specified.
<syntaxhighlight lang="lua">sticker_box = {{-0.5, -0.5}, {0.5, 0.5}}</syntaxhighlight>

{{Prototype property|hit_visualization_box|[[Types/BoundingBox|BoundingBox]]|<nowiki>Empty = {{0, 0}, {0, 0}}</nowiki>|optional=true}}
Where beams should hit the entity. Useful if the bounding box only covers part of the entity (e.g. feet of the character) and beams only hitting there would look weird.

{{Prototype property|trigger_target_mask|[[Types/TriggerTargetMask|TriggerTargetMask]]|optional=true}}

{{Prototype property|flags|[[Types/EntityPrototypeFlags|EntityPrototypeFlags]]|optional=true}}

{{Prototype property|minable|[[Types/MinableProperties|MinableProperties]]|not minable|optional=true}}

{{Prototype property|subgroup|[[Types/string|string]]|optional=true}}
The name of the subgroup this entity should be sorted into in the map editor building selection.

{{Prototype property|allow_copy_paste|[[Types/bool|bool]]|true|optional=true}}

{{Prototype property|selectable_in_game|[[Types/bool|bool]]|true|optional=true}}

{{Prototype property|selection_priority|[[Types/uint8|uint8]]|50|optional=true}}
The entity with the higher number is selectable before the entity with the lower number. When two entities have the same selection priority, the one with the highest [[Types/CollisionMask|collision mask]] (as determined by the order on that page) is selected.

{{Prototype property|remove_decoratives|[[Types/string|string]]|"automatic"|optional=true}}
Either "automatic", "true" or "false". Whether this entity should remove decoratives that collide with it when this entity is built. When set to "automatic", if the entity type is considered a building (e.g. an assembling machine or a wall) it will remove decoratives.

{{Prototype property|emissions_per_second|[[Types/double|double]]|0|optional=true}}
Amount of emissions created (positive number) or cleaned (negative number) every second by the entity.
This is passive, and it is independent concept of the emissions of machines, these are created actively depending on the power consumption.
Currently used just for trees.

<syntaxhighlight lang="lua">emissions_per_second = -0.001 -- cleaning effect of big tree</syntaxhighlight>

{{Prototype property|shooting_cursor_size|[[Types/double|double]]|optional=true}}
The cursor size used when shooting at this entity.

{{Prototype property|created_smoke|[[Types/CreateTrivialSmokeEffectItem|CreateTrivialSmokeEffectItem]]|The "smoke-building"-smoke|optional=true}}
The smoke that is shown when the entity is placed.

{{Prototype property|working_sound|[[Types/WorkingSound|WorkingSound]]|optional=true}}
Will also work on entities that don't actually do work.

{{Prototype property|created_effect|[[Types/Trigger|Trigger]]|optional=true}}
The effect/trigger that happens when the entity is placed.

{{Prototype property|build_sound|[[Types/Sound|Sound]]|optional=true}}

{{Prototype property|mined_sound|[[Types/Sound|Sound]]|optional=true}}

{{Prototype property|mining_sound|[[Types/Sound|Sound]]|optional=true}}

{{Prototype property|rotated_sound|[[Types/Sound|Sound]]|optional=true}}

{{Prototype property|vehicle_impact_sound|[[Types/Sound|Sound]]|optional=true}}
When playing this sound, the volume is scaled by the speed of the vehicle when colliding with this entity.

{{Prototype property|open_sound|[[Types/Sound|Sound]]|optional=true}}

{{Prototype property|close_sound|[[Types/Sound|Sound]]|optional=true}}

{{Prototype property|radius_visualisation_specification|[[Types/RadiusVisualisationSpecification|RadiusVisualisationSpecification]]|optional=true}}

{{Prototype property|build_base_evolution_requirement|[[Types/double|double]]|0|optional=true}}

{{Prototype property|alert_icon_shift|[[Types/vector|vector]]|optional=true}}

{{Prototype property|alert_icon_scale|[[Types/float|float]]|optional=true}}

{{Prototype property|fast_replaceable_group|[[Types/string|string]]|""|optional=true}}
This allows you to replace an entity that's already placed, with a different one in your inventory. For example, replacing a burner inserter with a fast inserter.

This is simply a string, so any string can be used here. The entity that should be replaced simply has to use the same string here.

The ones the game uses are:

"container"
"furnace"
"transport-belt"
"electric-pole"
"steam-engine"
"inserter"
"long-handed-inserter"
"pipe"
"assembling-machine"
"wall"
"loader"
"rail-signal"
"mining-drill"
"pumpjack"

{{Prototype property|next_upgrade|[[Types/string|string]]|optional=true}}
Name of the entity that will be automatically selected as the upgrade of this entity when using the [[upgrade planner]] without configuration.

This entity may not have 'not-upgradable' flag set and must be minable. This entity mining result must not contain item product with "hidden" flag set. Mining results with no item products are allowed. The entity may not be a [[Prototype/RollingStock]].<br>
The upgrade target entity needs to have the same bounding box, collision mask, and fast replaceable group as this entity. The upgrade target entity must have least 1 item that builds it that isn't hidden.

{{Prototype property|placeable_by|[[Types/ItemToPlace|ItemToPlace]] or [[Types/table|table]] of [[Types/ItemToPlace|ItemToPlace]]|optional=true}}
Item that when placed creates this entity. Determines which item is picked when "Q" (smart pipette) is used on the entity, determines which item is needed in a blueprint of this entity.

The item count specified here can't be larger than the stack size of that item.

{{Prototype property|remains_when_mined|[[Types/string|string]] or [[Types/table|table]] of [[Types/string|string]]|optional=true}}
The entity that remains when this one is mined, deconstructed or fast-replaced. The entity wont actually be spawned if it would collide with the entity that is in the process of being mined.

{{Prototype property|additional_pastable_entities|[[Types/table|table]] of [[Types/string|string]]|optional=true}}
Names of the entity prototypes this entity prototype can be pasted on to in addition to the standard supported types.
This is used to allow copying between types that aren't compatible on the C++ code side, by allowing mods to receive the [https://lua-api.factorio.com/latest/events.html#on_entity_settings_pasted on_entity_settings_pasted] event for the given entity and do the setting pasting via script.<br>
additional_pastable_entities = {"steel-chest", "iron-chest"}

{{Prototype property|tile_width|[[Types/uint32|uint32]]|calculated by the collision box width rounded up.|optional=true}}
Used to determine how the center of the entity should be positioned when building (unless the offgrid [[Types/EntityPrototypeFlags|flag]] is specified).
When the tile width is odd, the center will be in the center of the tile, when it is even, the center is on the tile transition.

{{Prototype property|tile_height|[[Types/uint32|uint32]]|calculated by the collision box height rounded up.|optional=true}}

{{Prototype property|autoplace|[[Types/AutoplaceSpecification|AutoplaceSpecification]]|nil (entity is not autoplacable)|optional=true}}
Used to specify the rules for placing this entity during map generation.

{{Prototype property|map_color|[[Types/Color|Color]]|optional=true}}

{{Prototype property|friendly_map_color|[[Types/Color|Color]]|optional=true}}

{{Prototype property|enemy_map_color|[[Types/Color|Color]]|optional=true}}

{{Prototype property|water_reflection|[[Types/WaterReflectionDefinition|WaterReflectionDefinition]]|optional=true}}
May also be defined inside <code>graphics_set</code> instead of directly in the entity prototype. This is useful for entities that use the a <code>graphics_set</code> property to define their graphics, becausen then all graphics can be in defined one place.

== Example ==
<syntaxhighlight lang="lua">{
type = "container",
name = "wooden-chest",
icon = "__base__/graphics/icons/wooden-chest.png",
flags = {"placeable-neutral", "player-creation"},
minable = {mining_time = 1, result = "wooden-chest"},
max_health = 100,
corpse = "small-remnants",
collision_box = {{-0.35, -0.35}, {0.35, 0.35}},
fast_replaceable_group = "container",
selection_box = {{-0.5, -0.5}, {0.5, 0.5}},
inventory_size = 16,
open_sound = { filename = "__base__/sound/wooden-chest-open.ogg" },
close_sound = { filename = "__base__/sound/wooden-chest-close.ogg" },
vehicle_impact_sound = { filename = "__base__/sound/car-wood-impact.ogg", volume = 1.0 },
picture =
{
filename = "__base__/graphics/entity/wooden-chest/wooden-chest.png",
priority = "extra-high",
width = 46,
height = 33,
shift = {0.25, 0.015625}
},
circuit_wire_connection_point =
{
shadow =
{
red = {0.734375, 0.453125},
green = {0.609375, 0.515625},
},
wire =
{
red = {0.40625, 0.21875},
green = {0.40625, 0.375},
}
},
circuit_connector_sprites = get_circuit_connector_sprites({0.1875, 0.15625}, nil, 18),
circuit_wire_max_distance = 9
}</syntaxhighlight>

Types/CollisionMask

2021-11-05T16:06:55Z

Xorimuth: /* Layers */ Reorder list based on internal implementation order

The collision mask is specified as an Array ([[Types/table]]) of strings. Every entry is a specification of one layer the object collides with or a special collision option.

Supplying an empty table means that no layers and no collision options are set.

The base game provides common collision mask functions in a Lua file in the core lualib: [https://github.com/wube/factorio-data/blob/master/core/lualib/collision-mask-util.lua collision-mask-util.lua].

== Layers ==

* "ground-tile"
* "water-tile"
* "resource-layer"
* "doodad-layer"
* "floor-layer"
* "rail-layer"
* "transport-belt-layer"
* "item-layer"
* "ghost-layer"
* "object-layer"
* "player-layer"
* "train-layer"
* "layer-<code>N</code>" where <code>N</code> is between 13 and 55, inclusive (layer-13 through layer-55)

Layer-13 through layer-55 are currently unused by the core game. If a mod is going to use one of the unused layers it's recommended to use the <code>collision_mask_util.get_first_unused_layer()</code> from the above linked library. If the library is not used, it is recommended start at the higher layers because the base game will take from the lower ones.

== Collision options ==
These are not collision masks, instead they control other aspects of collision, but they are still specified here.
=== "not-colliding-with-itself" ===
Any 2 entities that both have this option enabled on their prototype and have an identical collision mask layers list will not collide. Other collision mask options are not included in the identical layer list check. This does mean that 2 different prototypes with the same collision mask layers and this option enabled will not collide.

=== "consider-tile-transitions" ===

Uses the prototypes position rather than its collision box when doing collision checks with tile prototypes. Allows the prototype to overlap colliding tiles up until its center point.
This is only respected for character movement and cars driven by players.

=== "colliding-with-tiles-only" ===
Any prototype with this collision option will only be checked for collision with other prototype's collision masks if they are a tile.

== Default collision masks ==
The default collision masks of all entity types can be found [[Prototype/Entity#collision_mask|here]].

Example (Most common collision mask of buildings):
<syntaxhighlight lang="lua">collision_mask = { "item-layer", "object-layer", "player-layer", "water-tile"}</syntaxhighlight>

Prototype/Shortcut

2021-08-09T21:12:59Z

Xorimuth: disabled_small_icon's default behaviour changed in 1.1.37 to inherit from disabled_icon instead of icon. Added internal links (`icon` -> `#icon`)

{{Prototype parent|PrototypeBase}}
Definition for a shortcut button in the [[shortcut bar]].<br>
This is ''not'' a custom keybinding (keyboard shortcut), for that see [[Prototype/CustomInput]]

{{Prototype TOC|shortcut}}

== Mandatory properties ==
Inherits all properties from [[PrototypeBase]].

{{Prototype property|action|[[Types/string|string]]}}
One of "toggle-alt-mode", "undo", "copy", "cut", "paste", "import-string", "toggle-personal-roboport", "toggle-equipment-movement-bonus", "spawn-item" and "lua".

{{Prototype property|icon|[[Types/Sprite|Sprite]]}}
Scales to fit a 16x16-pixel square.<br />
Note: The scale that can be defined in the sprite may not behave as expected because the game always scales the sprite to fill the GUI slot.

== Optional properties ==

{{Prototype property|item_to_spawn|[[Types/string|string]]|optional=true}}
Name of a [[Prototype/Item]]. The item to create when clicking on a shortcut with the action set to "spawn-item". The item must have the [[Types/ItemPrototypeFlags#.22spawnable.22|"spawnable"]] flag set.

{{Prototype property|technology_to_unlock|[[Types/string|string]]|optional=true}}
Name of a [[Prototype/Technology]]. The technology that must be researched before this shortcut can be used.

{{Prototype property|toggleable|[[Types/bool|bool]]|false|optional=true}}
Must be enabled for the Factorio API to be able to set the toggled state on the shortcut button, see [https://lua-api.factorio.com/latest/LuaPlayer.html#LuaPlayer.set_shortcut_toggled LuaPlayer.set_shortcut_toggled].

{{Prototype property|associated_control_input|[[Types/string|string]]|""|optional=true}}
Name of a custom input or vanilla control. Used to show the keybind in the tooltip of the shortcut.

{{Prototype property|small_icon|[[Types/Sprite|Sprite]]|Uses [[#icon]] definition|optional=true}}
The icon used in the panel for visible shortcuts, when the shortcut is usable.<br />
Note: The scale that can be defined in the sprite may not behave as expected because the game always scales the sprite to fill the GUI slot.

{{Prototype property|disabled_icon|[[Types/Sprite|Sprite]]|Uses [[#icon]] definition|optional=true}}
The icon used when the shortcut is shown in the quickbar, and is not usable.<br />
Note: The scale that can be defined in the sprite may not behave as expected because the game always scales the sprite to fill the GUI slot.

{{Prototype property|disabled_small_icon|[[Types/Sprite|Sprite]]| Uses [[#disabled_icon]] definition|optional=true}}
The icon used in the panel for visible shortcuts, when the shortcut is not usable.<br />
Note: The scale that can be defined in the sprite may not behave as expected because the game always scales the sprite to fill the GUI slot.

{{Prototype property|style|[[Types/string|string]]|"default"|optional=true}}
One of "default", "blue", "red" and "green".

== Example ==

<syntaxhighlight lang="lua"> {
type = "shortcut",
name = "give-deconstruction-planner",
order = "b[blueprints]-g[deconstruction-planner]",
action = "spawn-item",
localised_name = {"shortcut.make-deconstruction-planner"},
associated_control_input = "give-deconstruction-planner",
technology_to_unlock = "construction-robotics",
item_to_spawn = "deconstruction-planner",
style = "red",
icon =
{
filename = "__base__/graphics/icons/shortcut-toolbar/mip/new-deconstruction-planner-x32-white.png",
priority = "extra-high-no-scale",
size = 32,
mipmap_count = 2,
flags = {"gui-icon"}
},
small_icon =
{
filename = "__base__/graphics/icons/shortcut-toolbar/mip/new-deconstruction-planner-x24-white.png",
priority = "extra-high-no-scale",
size = 24,
mipmap_count = 2,
flags = {"gui-icon"}
},
disabled_small_icon =
{
filename = "__base__/graphics/icons/shortcut-toolbar/mip/new-deconstruction-planner-x24-white.png",
priority = "extra-high-no-scale",
size = 24,
mipmap_count = 2,
flags = {"gui-icon"}
}
}</syntaxhighlight>

Prototype/Shortcut

2021-07-18T21:33:48Z

Xorimuth: Add default info to optional icon properties; wording can probably be improved

{{Prototype parent|PrototypeBase}}
Definition for a shortcut button in the [[shortcut bar]].<br>
This is ''not'' a custom keybinding (keyboard shortcut), for that see [[Prototype/CustomInput]]

{{Prototype TOC|shortcut}}

== Mandatory properties ==
Inherits all properties from [[PrototypeBase]].

{{Prototype property|action|[[Types/string|string]]}}
One of "toggle-alt-mode", "undo", "copy", "cut", "paste", "import-string", "toggle-personal-roboport", "toggle-equipment-movement-bonus", "spawn-item" and "lua".

{{Prototype property|icon|[[Types/Sprite|Sprite]]}}
Scales to fit a 16x16-pixel square.<br />
Note: The scale that can be defined in the sprite may not behave as expected because the game always scales the sprite to fill the GUI slot.

== Optional properties ==

{{Prototype property|item_to_spawn|[[Types/string|string]]|optional=true}}
Name of a [[Prototype/Item]]. The item to create when clicking on a shortcut with the action set to "spawn-item". The item must have the [[Types/ItemPrototypeFlags#.22spawnable.22|"spawnable"]] flag set.

{{Prototype property|technology_to_unlock|[[Types/string|string]]|optional=true}}
Name of a [[Prototype/Technology]]. The technology that must be researched before this shortcut can be used.

{{Prototype property|toggleable|[[Types/bool|bool]]|false|optional=true}}
Must be enabled for the Factorio API to be able to set the toggled state on the shortcut button, see [https://lua-api.factorio.com/latest/LuaPlayer.html#LuaPlayer.set_shortcut_toggled LuaPlayer.set_shortcut_toggled].

{{Prototype property|associated_control_input|[[Types/string|string]]|""|optional=true}}
Name of a custom input or vanilla control. Used to show the keybind in the tooltip of the shortcut.

{{Prototype property|small_icon|[[Types/Sprite|Sprite]]|Uses icon definition|optional=true}}
The icon used in the panel for visible shortcuts, when the shortcut is usable.<br />
Note: The scale that can be defined in the sprite may not behave as expected because the game always scales the sprite to fill the GUI slot.

{{Prototype property|disabled_icon|[[Types/Sprite|Sprite]]|Uses icon definition|optional=true}}
The icon used when the shortcut is shown in the quickbar, and is not usable.<br />
Note: The scale that can be defined in the sprite may not behave as expected because the game always scales the sprite to fill the GUI slot.

{{Prototype property|disabled_small_icon|[[Types/Sprite|Sprite]]|Uses icon definition|optional=true}}
The icon used in the panel for visible shortcuts, when the shortcut is not usable.<br />
Note: The scale that can be defined in the sprite may not behave as expected because the game always scales the sprite to fill the GUI slot.

{{Prototype property|style|[[Types/string|string]]|"default"|optional=true}}
One of "default", "blue", "red" and "green".

== Example ==

<syntaxhighlight lang="lua"> {
type = "shortcut",
name = "give-deconstruction-planner",
order = "b[blueprints]-g[deconstruction-planner]",
action = "spawn-item",
localised_name = {"shortcut.make-deconstruction-planner"},
associated_control_input = "give-deconstruction-planner",
technology_to_unlock = "construction-robotics",
item_to_spawn = "deconstruction-planner",
style = "red",
icon =
{
filename = "__base__/graphics/icons/shortcut-toolbar/mip/new-deconstruction-planner-x32-white.png",
priority = "extra-high-no-scale",
size = 32,
mipmap_count = 2,
flags = {"gui-icon"}
},
small_icon =
{
filename = "__base__/graphics/icons/shortcut-toolbar/mip/new-deconstruction-planner-x24-white.png",
priority = "extra-high-no-scale",
size = 24,
mipmap_count = 2,
flags = {"gui-icon"}
},
disabled_small_icon =
{
filename = "__base__/graphics/icons/shortcut-toolbar/mip/new-deconstruction-planner-x24-white.png",
priority = "extra-high-no-scale",
size = 24,
mipmap_count = 2,
flags = {"gui-icon"}
}
}</syntaxhighlight>

Tutorial:Modding tutorial/Gangsir

2021-05-06T22:54:47Z

Xorimuth: Update from 1.0 to 1.1

{{Languages}}
This is a modding tutorial for Factorio version 1.1. In this tutorial, the author will explain how Factorio works behind the scenes, how to modify Factorio, where to find documentation, and explain concepts.

== 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 1.1, so any ''viewers in the future should take note that some minor changes may have been made'', and should look at the changelogs up to the current version.

== 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 or item 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, and many functionally identical entities/items 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.

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 scripting at their [https://lua-api.factorio.com/latest/ API site] and documentation all around prototypes on [[Prototype definitions|this wiki]]. Get used to using these sites, as they will become frequent visits you will make 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. [[Prototype definitions]] contains and links to information all around prototypes, listing their inheritance structure and their properties. You will need to check these sites often, so the author recommends bookmarking them. In addition to these sites, there is 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 three kinds of dependencies. There are required dependencies, and optional dependencies. The third kind, restrictive dependencies, does not affect mod order and instead prevents the game from loading if the other mod is found. Required dependencies are loaded first, always. The game will fail to initialize if one of these is not present. Optional dependencies are loaded first if present, but do not have to be present. This is useful for enabling bonus features if mods are used together. Required dependencies should be used for mod libraries, and similar infrastructure.

=== 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 here on the wiki: [[Prototype definitions]].

=== Migrations ===

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

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

=== 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/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 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>, or another file <code>require</code>d by one of these three.

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, etc
* 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 [[Tutorial:Mod structure|in a certain way]]. To start out, create a folder in your [[Application directory|user data directory]]/mods folder. This folder must have a specific name, <code>fire-armor_0.1.0</code>. When you're finished, the mod directory should look like this:

* (user data directory, sometimes called .factorio)
** mods
*** fire-armor_0.1.0

Then, inside fire-armor_0.1.0, 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_0.1.0
**** data.lua
**** info.json

=== The info.json file ===

Then, inside [[Tutorial:Mod_structure#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": "1.1",
"dependencies": ["base >= 1.1"],
"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, 1.1 in this case.
|-
| dependencies
| Any dependencies of your mod.
|-
| description
| A ''short'' description of your mod.
|}

And that's all for info.json! Next, in the data.lua file:

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

require("item")
</pre>

It's a pretty simple file, all we're doing here is just telling the game to execute the file called item.lua, which we're about to create. Create a file in fire-armor_0.1.0 called <code>item.lua</code>. Notice how our earlier require used the file name in it?

We are creating this file just for our own organisation inside the mod, so there are no naming or other requirements from the game's side. As long as we tell the game to load the file with "require", the file name or its exact location inside the mod does not matter.

=== Prototype creation ===

Now, there are two ways to create prototypes in Factorio. There's the short way, and the long way. The long way requires to create a complete prototype definition based on [[prototype definitions|the documentation]], and the short way just uses a lua function to copy and modify an already existing definition. For the sake of this tutorial, we'll do it the short way.

In item.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black">
--item.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,
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
}
}

local recipe = table.deepcopy(data.raw["recipe"]["heavy-armor"])
recipe.enabled = true
recipe.name = "fire-armor"
recipe.ingredients = {{"copper-plate",200},{"steel-plate",50}}
recipe.result = "fire-armor"

data:extend{fireArmor,recipe}

</pre>

What we've just done here is we've copied the definition of heavy armor, then changed it's 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 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 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 indentified 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.<br>
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 type of character with a mod. You can see all the available prototype fields of the charater in the documenation: [[Prototype/Character]].

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/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 wearing our armor
if player.character and 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
)

</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 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. Additionally, don't try submitting it 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.

== 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 mods: __fire-armor__/data.lua:1:__fire-armor__/prototypes/item.lua:36: syntax error near 'true'
</pre>

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

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

Going to line 36 of item.lua, we find:

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

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

=== 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/Global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Selective requiring ===

<pre style="background-color:#DDA0DD!important; color:black">
if setting1 then
require("settingOne.lua")
end
</pre>

Selective requiring, aka requiring different lua files based on settings can cause connection rejections as the checksum of the mods will not match, as they load different data. All clients' mods must require the same series of files.

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

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

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

== See also ==

* [[Modding]]
* [[Modding FAQ]]

Tutorial:Localisation

2021-05-03T15:48:08Z

Xorimuth: /* Localising alternate input names */ Update wording from Left click to Left-click, which is what the game actually produces

{{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</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.

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.

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

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

<source lang="lua">game.print({"time-left", 10, 45})</source>
<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 etc.:

<pre>big-iron-plate=Big __ITEM__iron-plate__</pre>

=== 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".
* "rest" to give the default plural.

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 chooses 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.

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

<source lang="lua">game.print({"", {"item-name.iron-plate"}, ": ", 60})</source>
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/LuaPlayer.html#LuaPlayer.request_translation LuaPlayer::request_translation] and [https://lua-api.factorio.com/latest/events.html#on_string_translated on_string_translated event].

== See also ==
* [[Types/LocalisedString|LocalisedString data stage doc]]
* [https://lua-api.factorio.com/latest/Concepts.html#LocalisedString LocalisedString control stage doc]

Types/GiveItemModifierPrototype

2021-04-09T15:24:10Z

Xorimuth: Fix 'most' -> 'must' typo

Extends [[Types/ModifierPrototype]].

== Mandatory properties ==
Inherits all properties from [[Types/ModifierPrototype]].

=== item ===
'''Type''': [[Types/string]]

Name of a [[Prototype/Item]].

== Optional properties ==

=== count ===
'''Type''': [[Types/ItemCountType]]

'''Default''': 1

Must be > 0.