Official Factorio Wiki - User contributions [en]

Quality

2025-05-04T12:43:30Z

Flurki: Spelling correction

{{Languages}}
{{About/Space age}}
[[File:Any quality.png|right]]
'''Quality''' is a feature of the [[Space Age]] expansion. It introduces four higher quality levels for all items, structures and equipment with improved attributes. The goal of quality is to allow vertical factory upgrading as alternative to expansion in size. Items of higher quality are created by chance when using quality modules in the producing structure. When Space Age itself is enabled, the two highest quality tiers require technology not available on Nauvis. Different buildings and items can have different attributes that can be upgraded. When hovering over something, the attributes that will be upgraded with quality will be marked with a blue diamond ([[File:Quality info.png]]) in the tooltip.

While players are required to own Space Age to access this feature, quality is a separate mod, and can be activated independent of most Space Age content.

== Quality tiers ==
There are 5 quality tiers in vanilla gameplay, with tier strength in brackets:
* [[File:quality_normal.png|15px]] Normal (0)
* [[File:quality_uncommon.png|15px]] Uncommon (1)
* [[File:quality_rare.png|15px]] Rare (2)
* [[File:quality_epic.png|15px]] Epic (3)
* [[File:quality_legendary.png|15px]] Legendary ('''5''')

Note that legendary quality represents a 2-tier improvement over epic.

== Technologies ==
Certain tiers of quality cannot be created until they have been researched.
{|class="wikitable"
|-
! Research !! Base Game !! {{SA}} Space Age !! Unlocks
|-
| {{icontech|Quality module (research)|}} [[Quality module (research)]]
| {{icon|Time|60}}{{icon|Automation science pack}}{{icon|Logistic science pack}}{{icon|Chemical science pack}}{{icon|Production science pack}} x 300
| {{icon|Time|30}}{{icon|Automation science pack}}{{icon|Logistic science pack}} x 500
| [[File:quality_uncommon.png|32px]] [[File:quality_rare.png|32px]]
|-
| {{icontech|Epic quality (research)|}} [[Epic quality (research)]]
| {{icon|Time|60}}{{icon|Automation science pack}}{{icon|Logistic science pack}}{{icon|Chemical science pack}}{{icon|Production science pack}}{{icon|Utility science pack}} x 5000
| {{icon|Time|60}}{{icon|Automation science pack}}{{icon|Logistic science pack}}{{icon|Chemical science pack}}{{icon|Utility science pack}}{{icon|Space science pack}}{{icon|Agricultural science pack}} x 5000
| [[File:quality_epic.png|32px]]
|-
| {{icontech|Legendary quality (research)|}} [[Legendary quality (research)]]
| {{icon|Time|60}}{{icon|Automation science pack}}{{icon|Logistic science pack}}{{icon|Chemical science pack}}{{icon|Production science pack}}{{icon|Utility science pack}}{{icon|Space science pack}} x 5000
| {{icon|Time|60}}{{icon|Automation science pack}}{{icon|Logistic science pack}}{{icon|Chemical science pack}}{{icon|Production science pack}}{{icon|Utility science pack}}{{icon|Space science pack}}{{icon|Metallurgic science pack}}{{icon|Electromagnetic science pack}}{{icon|Agricultural science pack}}{{icon|Cryogenic science pack}} x 5000
| [[File:quality_legendary.png|32px]]
|-
|}

== Quality effects ==
The currently known effects of each level of quality are as follows:
* +30% health
* +30% crafting speed
* +30% robot limit (rounded down)
* +1 robot recharge slot for [[personal roboport]]s (both tiers, but not [[roboport]]s)
* +30% robot recharge rate (all roboports)
* +30% positive module effects (rounded down for at least quality modules)
* +10% turret range
* +10% weapon range
* +1 tile reach and +2 wire reach on power poles
* +1 equipment grid size (both dimensions)
* +30% chest inventory size (rounded down)
* +30% increased ammo damage
* +30% inserter rotation speed
** The power consumption of inserters is defined as energy per angle of turn. A 30% faster inserter can turn 30% more angles in a given space of time, so it consumes 30% more energy.
* -16.67% (1/6) resource drain on miners and [[pumpjack]]s
** This is multiplicative with [[productivity]]
* +30% [[solar panel]] output
* +100% (+5 MJ) capacity on accumulators
* +30% capacity on [[personal battery|personal batteries]] (all three tiers)
* +30% output rate on [[boiler]]s, [[steam engine]]s, [[steam turbine]]s, [[accumulator]]s (also affects input rate), and [[nuclear reactor]]s
** Note that consumption and pollution are also increased at the same rate
* +30% reach and efficiency for lightning [[lightning rod|rods]] and [[lightning collector|collectors]]
* -16.67% (1/6) power consumption on [[beacon]]s
* +1 to both continuous coverage distance and exploration coverage distance in [[radar]]s
* +100% durability on consumable items ([[repair pack]]s, [[science pack]]s)
* +5% fork chance on the [[tesla turret]] and tesla ammo for the tesla gun
* [[Asteroid collector]]s:
** +5% arm speed
** +1 arm
** +10% active power consumption per arm and +10% drain
** +2 collection area size (both dimensions)
** +5 storage size

These effects are per quality strength and additive: a Legendary (5 tier-levels) [[Productivity module 3]] (base +10% productivity) would grant 25% productivity.

Some buildings only get increased health, with no special effect. Examples are:
*Buildings related to [[Circuit network]]s and [[Rail signal]]s
*[[Transport belt]]s
*[[Pipe]]s
*[[Wall]]s
*[[Locomotive|Trains]]
*[[Cargo wagon]]s

{| class="wikitable"
|+ Quality Effects
! Item !! Effect !! [[File:quality_normal.png|15px]] Normal !! [[File:quality_uncommon.png|15px]] Uncommon !! [[File:quality_rare.png|15px]] Rare !! [[File:quality_epic.png|15px]] Epic !! [[File:quality_legendary.png|15px]] Legendary

|-
| rowspan="2" | [[File:assembling_machine_1.png|15px]] [[Assembling machine 1]] || Health || 300 || 390 || 480 || 570 || 750
|-
| Crafting speed || 0.5 || 0.65 || 0.8 || 0.95 || 1.25

|-
| rowspan="2" | [[File:assembling_machine_2.png|15px]] [[Assembling machine 2]] || Health || 350 || 455 || 560 || 665 || 875
|-
| Crafting speed || 0.75 || 0.975 || 1.2 || 1.425 || 1.875

|-
| rowspan="2" | [[File:assembling_machine_3.png|15px]] [[Assembling machine 3]] || Health || 400 || 520 || 640 || 760 || 1000
|-
| Crafting speed || 1.25 || 1.625 || 2 || 2.375 || 3.125

|-
| rowspan="3" | [[File:construction_robot.png|15px]] [[Construction robot]] || Health || 100 || 130 || 160 || 190 || 250
|-
| Max flying reach || 571m || 1152m || 1728m || 2305m || 3457m
|-
| Energy capacity || 3MJ || 6MJ || 9MJ || 12MJ || 18MJ

|-
| rowspan="3" | [[File:inserter.png|15px]] [[Inserter]] || Health || 150 || 195 || 240 || 285 || 375
|-
| Energy consumption || 15.1kW || 19.51kW || 23.92kW || 28.33kW || 37.15kW
|-
| Rotation speed || 302°/s || 393°/s || 484°/s || 575°/s || 756°/s

|-
| rowspan="3" | [[File:fast_inserter.png|15px]] [[Fast inserter]] || Health || 150 || 195 || 240 || 285 || 375
|-
| Energy consumption || 59.3kW || 76.94kW || 94.58kW || 112kW || 148kW
|-
| Rotation speed || 864°/s || 1123°/s || 1382°/s || 1642°/s || 2160°/s

|-
| rowspan="2" | [[File:laser_turret.png|15px]] [[Laser turret]] || Health || 1000 || 1300 || 1600 || 1900 || 2500
|-
| Range || 24 tiles || 26.4 tiles || 28.8 tiles || 31.2 tiles || 36 tiles

|-
| rowspan="1" | [[File:pipe.png|15px]] [[Pipe]] || Health || 100 || 130 || 160 || 190 || 250

|-
| rowspan="3" | [[File:roboport.png|15px]] [[Roboport]] || Health || 500 || 650 || 800 || 950 || 1250
|-
| Energy consumption || 2.1MW || 2.7MW || 3.3MW || 3.9MW || 5.1MW
|-
| Robot recharge rate || 4 x 500kW || 4 x 650kW || 4 x 800kW || 4 x 950kW || 4 x 1.25MW

|-
| rowspan="3" | [[File:small_electric_pole.png|15px]] [[Small electric pole]] || Health || 100 || 130 || 160 || 190 || 250
|-
| Supply area || 5x5 || 7x7 || 9x9 || 11x11 || 15x15
|-
| Wire reach || 7.5 tiles || 9.5 tiles || 11.5 tiles || 13.5 tiles || 17.5 tiles

|-
| rowspan="2" | [[File:wooden_chest.png|15px]] [[Wooden chest]] || Health || 100 || 130 || 160 || 190 || 250
|-
| Storage size || 16 || 20 || 25 || 30 || 40

|-
| rowspan="2" | [[File:iron_chest.png|15px]] [[Iron chest]] || Health || 200 || 260 || 320 || 380 || 500
|-
| Storage size || 32 || 41 || 51 || 60 || 80

|-
| rowspan="2" | [[File:steel_chest.png|15px]] [[Steel chest]] || Health || 350 || 455 || 560 || 665 || 875
|-
| Storage size || 48 || 62 || 76 || 91 || 120
|}

== Creating high-quality items ==

There are two ways to create an item with above normal quality: The player must either use ingredient items of the same quality, or use quality modules for a random chance of a higher-quality item.

=== Quality ingredients ===
Recipes that consume items have variations for each quality that the items might take. When setting such a recipe in a production unit, an ingredient quality must be selected. For these variations, the set of ingredients required is the same, except that all item ingredients must have the specified quality. Recipes that consume only fluids do not have quality variations. If they produce items, those items will be normal quality unless affected by quality modules. Recipes that fill or empty [[barrel]]s and recipes that produce the same item they consume ([[kovarex enrichment process]] and [[fish breeding]]) do not accept quality modules.

Item ingredient quality requirements are exact, not minimum. For example, one can not combine uncommon [[iron plate]]s with rare [[battery|batteries]] to make an [[accumulator]] of any quality. One must therefore ensure that high-quality items do not clog up belts and starve production units of lower-quality items.

As fluids do not possess any quality, they are exempt from ingredient quality requirements; the same [[lubricant]] can be used to create [[electric engine unit]]s of any quality.

=== Quality modules ===
{{Main|Quality module}}
[[File:quality_module_animated.png|64px|right]]'''Quality modules''' allow crafting machines to produce items of a higher quality than their ingredients. Each module adds a quality chance to a machine, depending on its tier and quality. See the following table for all quality chances:

{|class="wikitable" style="text-align: center;"
! {{Diagonal split header|Module|Quality}} !! [[File:quality_normal.png|Normal|32px]] !! [[File:quality_uncommon.png|Uncommon|32px]] !! [[File:quality_rare.png|Rare|32px]] !! [[File:quality_epic.png|Epic|32px]] !! [[File:quality_legendary.png|Legendary|32px]]
|-
! {{Icon|quality_module}}
| +1% || +1.3% || +1.6% || +1.9% || +2.5%
|-
! {{Icon|quality_module_2}}
| +2% || +2.6% || +3.2% || +3.8% || +5%
|-
! {{Icon|quality_module_3}}
| +2.5% || +3.2% || +4% || +4.7% || +6.2%
|}

When working out the odds of improving quality, a machine starts with the sum of the quality chance of all its modules. When the machine produces an item, it performs a random roll with that chance to succeed. If it succeeds, the product is upgraded 1 level from its ingredients. If the product was upgraded, the machine repeats this process, now with a constant 10% chance of passing, rolling and upgrading until a roll fails.

When using quality ingredients as an input, the base quality is the quality of the recipe. You can only use items with the same quality as input.

Quality modules are only required to ''improve'' quality, crafting will always give the base quality of the used items. Additionally, the odds of improving from a given base quality is the same as improving the same number of tiers from Normal quality.

Where Q is quality chance, the following tables present expected outputs for each level of research.
<div style="display:inline-block; vertical-align:top; margin-right:20px;">
{| class="wikitable" style="text-align:center; vertical-align:middle;"
|+ {{icontech|Quality module (research)|}} [[Quality module (research)]]
!{{Diagonal split header|Input|Output}} !! [[File:quality_normal.png|Normal|20px]] !! [[File:quality_uncommon.png|Uncommon|20px]] !! [[File:quality_rare.png|Rare|20px]]
|-
! [[File:quality_normal.png|Normal|16px]]
| 1 - Q || Q * 9/10|| Q * 1/10
|-
! [[File:quality_uncommon.png|Uncommon|16px]]
| - || 1 - Q || Q
|-
! [[File:quality_rare.png|Rare|16px]]
| - || - || 1
|}
</div>
<div style="display:inline-block; vertical-align:top; margin-right:20px;">
{| class="wikitable" style="text-align:center; vertical-align:middle;"
|+ {{icontech|Epic quality (research)|}} [[Epic quality (research)]]
!{{Diagonal split header|Input|Output}} !! [[File:quality_normal.png|Normal|20px]] !! [[File:quality_uncommon.png|Uncommon|20px]] !! [[File:quality_rare.png|Rare|20px]] !! [[File:quality_epic.png|Epic|20px]]
|-
! [[File:quality_normal.png|Normal|16px]]
| 1 - Q || Q * 9/10|| Q * 9/100 ||Q * 1/100
|-
! [[File:quality_uncommon.png|Uncommon|16px]]
| - || 1 - Q || Q * 9/10|| Q * 1/10
|-
! [[File:quality_rare.png|Rare|16px]]
| - || - || 1 - Q || Q
|-
! [[File:quality_epic.png|Epic|16px]]
| - || - || - || 1
|}
</div>
<div style="display:inline-block; vertical-align:top; margin-right:20px;">
{| class="wikitable" style="text-align:center; vertical-align:middle;"
|+ {{icontech|Legendary quality (research)|}} [[Legendary quality (research)]]
!{{Diagonal split header|Input|Output}} !! [[File:quality_normal.png|Normal|20px]] !! [[File:quality_uncommon.png|Uncommon|20px]] !! [[File:quality_rare.png|Rare|20px]] !! [[File:quality_epic.png|Epic|20px]] !! [[File:quality_legendary.png|Legendary|20px]]
|-
! [[File:quality_normal.png|Normal|16px]]
| 1 - Q || Q * 9/10|| Q * 9/100 ||Q * 9/1000 || Q * 1/1000
|-
! [[File:quality_uncommon.png|Uncommon|16px]]
| - || 1 - Q || Q * 9/10|| Q * 9/100 || Q * 1/100
|-
! [[File:quality_rare.png|Rare|16px]]
| - || - || 1 - Q || Q * 9/10|| Q * 1/10
|-
! [[File:quality_epic.png|Epic|16px]]
| - || - || - || 1 - Q || Q
|-
! [[File:quality_legendary.png|Legendary|16px]]
| - || - || - || - || 1
|}
</div>

==== Examples ====
<div style="display:inline-block; margin-right:20px; vertical-align:top;">
{|class="wikitable" style="text-align: center;"
|+ 2× {{Icon|quality_module_2|[[File:quality_normal.png|Normal|16px]]}} → Q = 4%
! {{Diagonal split header|Input|Output}} !! [[File:quality_normal.png|Normal|32px]] !! [[File:quality_uncommon.png|Uncommon|32px]] !! [[File:quality_rare.png|Rare|32px]]
|-
! [[File:quality_normal.png|Normal|32px]]
| 96% || 3.6% || 0.4%
|-
! [[File:quality_uncommon.png|Uncommon|32px]]
| - || 96% || 4%
|-
! [[File:quality_rare.png|Rare|32px]]
| - || - || 100%
|}
</div><div style="display:inline-block; margin-right:20px;">
{|class="wikitable" style="text-align: center;"
|+ 4× {{Icon|quality_module_3|[[File:quality_normal.png|Normal|16px]]}} → Q = 10%
! {{Diagonal split header|Input|Output}} !! [[File:quality_normal.png|Normal|32px]] !! [[File:quality_uncommon.png|Uncommon|32px]] !! [[File:quality_rare.png|Rare|32px]] !! [[File:quality_epic.png|Epic|32px]] !! [[File:quality_legendary.png|Legendary|32px]]
|-
! [[File:quality_normal.png|Normal|32px]]
| 90% || 9% || 0.9% || 0.09% || 0.01%
|-
! [[File:quality_uncommon.png|Uncommon|32px]]
| - || 90% || 9% || 0.9% || 0.1%
|-
! [[File:quality_rare.png|Rare|32px]]
| - || - || 90% || 9% || 1%
|-
! [[File:quality_epic.png|Epic|32px]]
| - || - || - || 90% || 10%
|-
! [[File:quality_legendary.png|Legendary|32px]]
| - || - || - || - || 100%
|}
</div><div style="display:inline-block; margin-right:20px;">
{|class="wikitable" style="text-align: center;"
! {{Diagonal split header|Input|Output}} !! [[File:quality_normal.png|Normal|32px]] !! [[File:quality_uncommon.png|Uncommon|32px]] !! [[File:quality_rare.png|Rare|32px]] !! [[File:quality_epic.png|Epic|32px]] !! [[File:quality_legendary.png|Legendary|32px]]
|+ 4× {{Icon|quality_module_3|[[File:quality_legendary.png|Legendary|16px]]}} → Q = 24.8%
|-
! [[File:quality_normal.png|Normal|32px]]
| 75.2% || 22.32% || 2.232% || 0.2232% || 0.0248%
|-
! [[File:quality_uncommon.png|Uncommon|32px]]
| - || 75.2% || 22.32% || 2.232% || 0.248%
|-
! [[File:quality_rare.png|Rare|32px]]
| - || - || 75.2% || 22.32% || 2.48%
|-
! [[File:quality_epic.png|Epic|32px]]
| - || - || - || 75.2% || 24.8%
|-
! [[File:quality_legendary.png|Legendary|32px]]
| - || - || - || - || 100%
|}
</div>

==== Optimal module usage ====
It is optimal to improve quality on the lead-up to the target output item due to the [[recycler]] only giving back 25% of the input items, except for cases where the chosen item has a productivity research available, in which case looping through a recycler is optimal and has no added material cost (ignoring fluids).

The following tables summarize the number of normal crafts (rounded up) needed to produce 1 legendary output using ideal ratios of quality module 3s to productivity module 3s, with 4 matching quality module 3 in the recycler.

It is important to emphasize that these ratios maximize return per input material. If input capacity isn't a concern and the goal is speed rather than material efficiency, then switch out productivity modules for quality modules as needed. Beware, however, that in many cases material inefficiency nearly keeps pace with the legendary output rate.

<div style="display:inline-block; vertical-align:top; margin-right:20px;">
{| class="wikitable" style="border: 2px solid; text-align:center;"
! Max Modules !! Base Prod. !! No. of {{Icon|productivity_module_3|[[File:quality_rare.png|Rare|16px]]}} !! No. of {{Icon|quality_module_3|[[File:quality_rare.png|Rare|16px]]}} !! Crafts
|-
| 2 || 0% || 0 || 2 || 891
|-
| 3 || 0% || 0 || 3 || 533
|-
| 4 || 0% || 1 || 3 || 342
|-
| 4 || 50% || 0 || 4 || 97
|-
| 5 || 50% || 1 || 4 || 67
|-
| 8 || 0% || 4 || 4 || 70
|}</div>
<div style="display:inline-block; vertical-align:top; margin-right:20px;">
{| class="wikitable" style="border: 2px solid; text-align:center;"
! Max Modules !! Base Prod. !! No. of {{Icon|productivity_module_3|[[File:quality_epic.png|Epic|16px]]}} !! No. of {{Icon|quality_module_3|[[File:quality_epic.png|Epic|16px]]}} !! Crafts
|-
| 2 || 0% || 0 || 2 || 608
|-
| 3 || 0% || 1 || 2 || 356
|-
| 4 || 0% || 1 || 3 || 212
|-
| 4 || 50% || 1 || 3 || 62
|-
| 5 || 50% || 2 || 3 || 40
|-
| 8 || 0% || 5 || 3 || 34
|}</div>
<div style="display:inline-block; vertical-align:top; margin-right:20px;">
{| class="wikitable" style="border: 2px solid; text-align:center;"
! Max Modules !! Base Prod. !! No. of {{Icon|productivity_module_3|[[File:quality_legendary.png|Legendary|16px]]}} !! No. of {{Icon|quality_module_3|[[File:quality_legendary.png|Legendary|16px]]}} !! Crafts
|-
| 2 || 0% || 0 || 2 || 309
|-
| 3 || 0% || 1 || 2 || 153
|-
| 4 || 0% || 2 || 2 || 80
|-
| 4 || 50% || 3 || 1 || 25
|-
| 5 || 50% || 4 || 1 || 14
|-
| 8 || 0% || 8 || 0 || 7
|}</div>
For example, suppose legendary T3 modules are available and the goal is to produce legendary [[File:Processing_unit.png|link=Processing unit|20px]] processing units. If each electromagnetic plant producing epic quality or below has 4 legendary [[File:productivity_module_3.png|link=Productivity module 3|20px]] productivity module 3 and 1 legendary [[File:quality_module_3.png|link=Quality module 3|20px]] quality module 3, and the electromagnetic plant with the legendary recipe has 5 legendary [[File:productivity_module_3.png|link=Productivity module 3|20px]] productivity module 3, then on average an input of 280 normal [[File:Electronic_circuit.png|link=Electronic circuit|20px]] electronic circuits and 28 normal [[File:Advanced_circuit.png|link=Advanced circuit|20px]] advanced circuits is expected to produce 1 legendary [[File:Processing_unit.png|link=Processing unit|20px]] processing unit.

===== Derivation =====
Derivation of the tables above was as follows: Starting with 1 set of common ingredients, with an assembly quality chance of Q and total productivity bonus of P, the statistical expected number of product is as follows:
{| class="wikitable" style="text-align:center; vertical-align:middle;"
|+
! [[File:quality_normal.png|Normal|20px]] !! [[File:quality_uncommon.png|Uncommon|20px]] !! [[File:quality_rare.png|Rare|20px]] !! [[File:quality_epic.png|Epic|20px]] !! [[File:quality_legendary.png|Legendary|20px]]
|-
| (1 + P) * (1 - Q) || (1 + P) * (Q * (100 - 10-1))|| (1 + P) * (Q * (10-1 - 10-2)) || (1 + P) * (Q * (10-2 - 10-3)) || (1 + P) * (Q * 10-3)
|-
| (1 + P) * (1 - Q) || (1 + P) * Q * 9/10 || (1 + P) * Q * 9/100 || (1 + P) * Q * 9/1000 || (1 + P) * Q * 1/1000
|}

In a similar vein, the same calculations can be done for recycling products, except that there is, in effect, -75% productivity bonus, where only a quarter of the items are returned.

{| class="wikitable" style="text-align:center; vertical-align:middle;"
! [[File:quality_normal.png|Normal|20px]] !! [[File:quality_uncommon.png|Uncommon|20px]] !! [[File:quality_rare.png|Rare|20px]] !! [[File:quality_epic.png|Epic|20px]] !! [[File:quality_legendary.png|Legendary|20px]]
|-
| (1 + -0.75) * (1-Q) || (1 + -0.75) * (Q * (100 - 10-1)) || (1 + -0.75) * (Q * (10-1 - 10-2)) || (1 + -0.75) * (Q * (10-2 - 10-3)) || (1 + -0.75) * (Q * 10-3)
|-
| 0.25 * (1-Q) || 0.25 * Q * 9/10|| 0.25 * Q * 9/100 || 0.25 * Q * 9/1000 || 0.25 * Q * 1/1000
|}

For example, recycling an uncommon ingredient with a Q of 25%:
{| class="wikitable" style="text-align:center; vertical-align:middle;"
! {{Diagonal split header|Input|Output}} !! [[File:quality_normal.png|Normal|20px]] !! [[File:quality_uncommon.png|Uncommon|20px]] !! [[File:quality_rare.png|Rare|20px]] !! [[File:quality_epic.png|Epic|20px]] !! [[File:quality_legendary.png|Legendary|20px]]
|-
| style="background:#424242" | [[File:quality_uncommon.png|Uncommon|16px]] || - || 0.1875 || 0.05625 || 0.005625 || 0.000625
|}

Combining these results allows a 'Transition Matrix' to be developed (see the Wikipedia article [[Wikipedia:Stochastic matrix|Stochastic matrix]]) which after iteration can generate the expected number of legendary products from 1 set of common ingredients via matrix multiplication. An example matrix for P of 50% and Q of 25% for both recycling and assembly is copied below. Note that since legendary products are the goal, they are not recycled.

{| class="wikitable" style="border:2px solid; text-align:center;"
! !! style="border-left:2px solid" | I[[File:quality_normal.png|Normal|10px]] !! I[[File:quality_uncommon.png|Uncommon|10px]] !! I[[File:quality_rare.png|Rare|10px]] !! I[[File:quality_epic.png|Epic|10px]] !! I[[File:quality_legendary.png|Legendary|10px]]
! style="border-left:2px solid" | P[[File:quality_normal.png|Normal|10px]] !! P[[File:quality_uncommon.png|Uncommon|10px]] !! P[[File:quality_rare.png|Rare|10px]] !! P[[File:quality_epic.png|Epic|10px]] !! P[[File:quality_legendary.png|Legendary|10px]]
|- style="border-top:2px solid"
! I[[File:quality_normal.png|Normal|10px]]
| style="border-left:2px solid" | 0 || 0 || 0 || 0 || 0
| style="border-left:2px solid" | 1.125 || 0.3375 || 0.03375 || 0.003375 || 0.000375
|-
! I[[File:quality_uncommon.png|Uncommon|10px]]
| style="border-left:2px solid" | 0 || 0 || 0 || 0 || 0
| style="border-left:2px solid" | 0 || 1.125 || 0.3375 || 0.03375 || 0.00375
|-
! I[[File:quality_rare.png|Rare|10px]]
| style="border-left:2px solid" | 0 || 0 || 0 || 0 || 0
| style="border-left:2px solid" | 0 || 0 || 1.125 || 0.3375 || 0.0375
|-
! I[[File:quality_epic.png|Epic|10px]]
| style="border-left:2px solid" | 0 || 0 || 0 || 0 || 0
| style="border-left:2px solid" | 0 || 0 || 0 || 1.125 || 0.375
|-
! I[[File:quality_legendary.png|Legendary|10px]]
| style="border-left:2px solid" | 0 || 0 || 0 || 0 || 0
| style="border-left:2px solid" | 0 || 0 || 0 || 0 || 1.5
|- style="border-top:2px solid"
! P[[File:quality_normal.png|Normal|10px]]
| style="border-left:2px solid" | 0.1875 || 0.05625 || 0.005625 || 0.0005625 || 0.0000625
| style="border-left:2px solid" | 0 || 0 || 0 || 0 || 0
|-
! P[[File:quality_uncommon.png|Uncommon|10px]]
| style="border-left:2px solid" | 0 || 0.1875 || 0.05625 || 0.005625 || 0.000625
| style="border-left:2px solid" | 0 || 0 || 0 || 0 || 0
|-
! P[[File:quality_rare.png|Rare|10px]]
| style="border-left:2px solid" | 0 || 0 || 0.1875 || 0.05625 || 0.00625
| style="border-left:2px solid" | 0 || 0 || 0 || 0 || 0
|-
! P[[File:quality_epic.png|Epic|10px]]
| style="border-left:2px solid" | 0 || 0 || 0 || 0.1875 || 0.0625
| style="border-left:2px solid" | 0 || 0 || 0 || 0 || 0
|-
! P[[File:quality_legendary.png|Legendary|10px]]
| style="border-left:2px solid" | 0 || 0 || 0 || 0 || 0
| style="border-left:2px solid" | 0 || 0 || 0 || 0 || 1
|}

To iterate this matrix (M) apply the matrix to itself. For example, M6 would indicate 6 iterations, corresponding to 3 crafting steps and 3 recycling steps. To see how much 1 ingredient set produces after a given iteration, x, multiply an input vector by Mx. The vector format follows that of the matrix labels, so with the table arranged as above, left multiply a row vector of ingredient(s) by the matrix. In order to see the expected product of 1 set of normal ingredients, the vector will have '1' in the first column and '0's everywhere else. Likewise, a set of uncommon ingredients will correspond to '1' in the second column of the vector.

It is important to note that since the recycling step has a material loss of 75% most recycling loops will be well behaved and converge quickly.

Extreme productivity from research breaks this pattern and will prevent convergence, but this simply means that there is a positive material cycle, so 1 set of ingredients will produce infinite legendary crafts, on average. The closer the total productivity is to 400%, the slower the convergence of the matrix iteration and the higher you need to calculate x in Mx.


== Usage tips ==
=== Using quality to increase production ===
There are four ways in which quality can increase the output of a single production machine:
* Increasing the quality of the machine itself will improve its base crafting speed.
* Increasing the quality of [[speed module]]s will increase the effect of their speed improvements.
* Increasing the quality of [[productivity module]]s will increase their productivity bonus without reducing crafting speed. Since extra items obtained from the productivity bonus do not take extra time to produce, this will also increase the number of items produced over time.
* Increasing the quality of [[beacon]]s will increase their transmission efficiency. If they contain speed modules, then the effect of these modules is increased.

These four options share a powerful synergy, as they react multiplicatively with one another. This makes it possible to achieve very high production rates with very few machines when compared to only using normal quality items. For example, imagine a setup where [[electronic circuit]]s are made using one [[electromagnetic plant]] with five [[productivity module 3]]s, which is surrounded by 12 [[beacon]]s with two [[speed module 3]]s, each. With normal quality, this will achieve an output rate of almost 45 items per second (almost enough to saturate one non-layered [[express transport belt]]). However, if the electromagnetic plant and all beacons and modules have legendary quality, the output rate becomes slightly more than 600 items per second (enough to saturate two and a half [[turbo transport belt]]s with four layers of items). This is more than 13 times as many items as without quality.

It should be noted that quality beacons are the only one of these factors that may increase energy consumption over time, as the transmission effect is also applied to the energy cost of speed modules. However, this is offset or even negated by the reduced energy consumption of the beacons themselves (which is also affected by quality), especially with high beacon counts wherein the transmission effect is subject to diminishing returns. For speed modules, productivity modules, and the machine itself, only the speed increase, productivity bonus, and base crafting speed are affected, respectively.

The increased transmission effect of high-quality beacons is also notable because unlike when increasing the number of beacons, there are no diminishing returns for increasing their quality (aside from the exponentially increasing cost of producing those higher-quality beacons in the first place). This means that, despite a legendary beacon only being 1.66 times as powerful as a normal-quality beacon, one would need 0.36 times as many legendary beacons as normal ones to achieve the same effect. Aside from making more powerful beacon setups, this can also be used to save space by achieving the same effect with fewer beacons, thereby leaving more room for machines and belts.

Higher-quality machines are also particularly useful for producing quality items as, unlike speed modules, machine quality does not reduce the chance of increasing a product's quality.

=== Using quality to save space ===
Another use for quality is decreasing the amount of buildings needed to perform the same production. This is particularly useful in a [[space platform]], where small, compact designs are rewarded with increased speed, as well as needing fewer rockets to build the platform.

=== Notes ===
* In the below circumstances, quality modules have no useful effects.
** Placed in a [[Rocket silo]]
** Placed in a [[Lab]]
** Placed in a [[Biolab]]
** Fluid recipes (e.g [[holmium solution]])
* [[Barrel]]s cannot accept quality modules, most likely to stop quality upcycling with no loss.
* The [[Kovarex enrichment process]] recipe cannot accept quality modules, most likely to stop quality upcycling with no loss.

== Relevant Factorio Friday Facts ==
* [https://www.factorio.com/blog/post/fff-375 FFF 375 - Quality]
* [https://www.factorio.com/blog/post/fff-376 FFF 376 - Research and Technology]

== Achievements ==
{{Achievement|make-it-better}}
{{Achievement|look-at-my-shiny-rare-armor}}
{{Achievement|todays-fish-is-trout-a-la-creme}}
{{Achievement|crafting-with-quality}}
{{Achievement|my-modules-are-legendary}}
{{Achievement|no-room-for-more}}

== Trivia ==
* Quality is not technically exclusive to player-made entities; Though this does not occur naturally, quality is also allowed on enemies, asteroids, and even the [[player]] character.
** Some enemies with qualities above normal can even be created in regular sandbox gameplay: Big biters, behemoth biters, and big premature wriggler pentapods born from spoiled [[biter egg]]s, [[captive biter spawner]]s, and [[pentapod egg]]s inherit the quality of the spoiled items, with the latter two being possible to craft with quality modules. Furthermore, a starved captured biter spawner will retain its quality upon converting into a hostile biter spawner, with said quality even being inherited by the biters that it will spawn. Should these biters choose to expand, they may also create quality spitters and worms.

== History ==
{{history|2.0.7|
* Introduced in [[Space Age]]{{SA}} expansion.
}}

{{C|Main}}

Circuit network

2025-05-04T10:43:21Z

Flurki: Grammar correction

{{Languages}}
'''Circuit networks''' are built using [[Red wire|red]] or [[green wire]], and enable the control of receivers, based upon information broadcast onto the network by connected senders. Most senders are storage devices, and broadcast their information onto a specific channel, based on the item or liquid the storage device contains. Each circuit network contains a channel for every kind of item, as well as 48 extra [[#Virtual signals|virtual signals]] which act as user-definable channels. 'Everything', 'Anything' and 'Each' are also available wildcards.

[[File:shared_circuit_network.png|thumb|600px|right|Two circuit networks shared over one [[small electric pole]].]]

== Usage ==
=== Send information ===
Senders broadcast the amount of items or fluids they contain or other data definable by the player. Each amount is broadcast as a numeric value on a 'channel' corresponding to the item. For example, a Storage Tank containing 1000 Crude Oil will broadcast 1000 on the Crude Oil channel.

The channels are separated from each other, so each network can simultaneously carry a number for each item and fluid in the game, and for each of the extra user-defined channels (digits 0-9, letters A-Z, and 9 different colors). All unused channels have the value zero.

Multiple broadcasts of the same item or fluid are additive: If there are two connected Storage Tanks with 1000 Crude Oil each, the value of the Crude Oil channel within the network will be 2000.

All wires of the same color which are connected together by junctions form a network, i.e. they will pass their signals to each other. For example, if two red wires are connected to the same combinator input, each wire receives the content from the other. This can result in feedback if care is not taken; see Feedback (under [[#Combinators|arithmetic combinator]], below) for discussion.

Numbers are in the signed 32 bit integer range, i.e. from -2147483648 to 2147483647 inclusive, and are encoded in [https://en.wikipedia.org/wiki/Two%27s_complement two's complement representation]. The numbers wrap around on overflow, so e.g. 2147483647 + 10 becomes -2147483639. When entering a number in a combinator it can appear to exceed the 32 bit limit until the GUI is closed, at which point the number will overflow/underflow. [https://forums.factorio.com/58419]

=== Control devices ===
Receivers can use broadcast information, in most cases to enable/disable the device. They can either compare results between different channels, or compare a channel to a specific value.

Receiving devices sum all signals from each wire connected to them, even red and green wires. For example, if an inserter is connected to a red wire carrying a signal for 20 copper plates and a green wire with 10 copper plates, the input signal set for that receiver will be 30 copper plates.

Multiple wires of the same color will share & sum their signals. For example, 3 chests A, B and C connected in a row (A -> B -> C) with green wire will output the sum of their contents along any green wire connected to any of the chests. However, if a red wire connects chest A to an inserter, that inserter will only be given the contents of A as its input signal.

== Devices ==


Each device that is able to be connected to a circuit network has a [[File:Circuit network panel.png]] icon located in the top right corner of its info pane. Clicking this icon will display the available circuit network options for that device (note: a red or green wire must be connected, otherwise the message "not connected" will display instead). Clicking the [[File:Logistic network panel.png]] icon next to it, the device can be connected to a logistic network if in range of one, which also allows conditions to be set.

Conditions can be set for both circuit (signals of red and green wires are summed) and logistic network, which will together act as a logical AND.

The following devices can be connected to a circuit network:

{| class="wikitable mw-collapsible"
|-
! Icon !! Name !! Possible output signals !! Possible circuit control !! Possible logistic network control
|-
| {{Icon|Transport belt||Transport belts}} || [[Transport belts]] || Transport belts can send their content to the circuit network.
*''Pulse mode'': The signal is sent for only 1 tick when the item enters the belt.
*''Hold mode'': The signal is sent continuously as long as the items are on the belt.
*''Hold mode'' (All belts): The signal is sent continuously for all items on the entire transport belt line. The count continues through underground belts, but not splitters or side loading.
|| Transport belts can be enabled on a condition.
|| Transport belts can be enabled on a logistic network condition.
|-
| {{Icon|Inserter||Inserters}} || [[Inserters]] || All inserters can send their held items to the circuit network.
*''Pulse mode'': The signal is sent for only 1 tick when the item is picked up.
*''Hold mode'': The signal is sent continuously as long as the inserter is holding the item.
|| All inserters can be enabled on a condition. The inserter stack size can also be overridden from a control signal (configurable; values less than 1 are treated as 1). Filters can be set on a signal.
|| All inserters can be enabled on a logistic network condition.
|-
| {{Icon|Assembling machine}} {{Icon|Oil refinery}} {{Icon|Chemical plant}} {{Icon|Centrifuge}} {{Icon|Crusher|space-age=yes}} {{Icon|Foundry|space-age=yes}} {{Icon|Electromagnetic plant|space-age=yes}} {{Icon|Biochamber|space-age=yes}} {{Icon|Cryogenic plant|space-age=yes}} || [[Assembling machine]]s, [[Oil refinery]], [[Chemical plant]], [[Centrifuge]], [[Crusher]], [[Foundry]], [[Electromagnetic plant]], [[Biochamber]], [[Cryogenic plant]] || All crafting machines can output:
* Their contents, including fluids, in all slots
** Optionally, can include the items within the current crafting job
** If the machine has fuel, can optionally include the current fuel, including the unit of fuel currently being burned
* The ingredients of the set recipe
* A control signal, for 1 tick, when the recipe finishes crafting
** The signal value indicates the number of crafts finished last tick
** Includes productivity crafts
* A control signal, while the building is working
|| All crafting machines can enable on a condition and set their recipe based on a signal
||
|-
| {{Icon|Stone furnace}} {{Icon|Steel furnace}} {{Icon|Electric furnace}} {{Icon|Recycler}} || [[Furnace]]s and the [[Recycler]]{{SA}} || Furnace-style crafting machines can output:
* Their contents, including fluids, but not fuel, in all slots
** Optionally, can include the items within the current crafting job
** If the machine requires fuel, can optionally include the current fuel, including the unit of fuel currently being burned
* The ingredients of automatically determined recipe
* A control signal, for 1 tick, when the recipe finishes crafting
** The signal value indicates the number of crafts finished last tick
** Includes productivity crafts
* A control signal, while the building is working
|| All furnace-style crafting machines can enable on a condition
||
|-
| {{Icon|Wooden chest||Wooden chest}} {{Icon|Iron chest||Iron chest}} {{Icon|Steel chest||Steel chest}} || [[Chests]] || Can send its content to the circuit network. ||
|-
| {{Icon|Cargo landing pad}} || [[Cargo landing pad]] || The landing pad can send its contents to the circuit network. || The landing pad can have its requests set by the circuit network.{{SA}} ||
|-
| {{Icon|Rocket silo}} || [[Rocket silo]] || The rocket silo can output its contents or requests from space platforms.{{SA}} ||
||
|-
| {{Icon|Space platform hub|space-age=yes}} || [[Space platform hub]] || Can output its contents, destination and source planet, current speed, and damage taken
*''Default'': Read Speed = Signal ''V''
*''Default'': Read Damage Taken = Signal ''D''
| Platform hub can be sent the contents of the circuit network to use for wait conditions
||
|-
| {{Icon|Asteroid collector|space-age=yes}} || [[Asteroid collector]] || Can output its contents to the circuit network || Can enable on a condition and set filters on a signal ||
|-
| {{Icon|Requester chest}} {{Icon|Buffer chest}} {{Icon|Storage chest}} {{Icon|Passive provider chest}} {{Icon|Active provider chest}} || [[Requester chest]], [[Buffer chest]], [[Storage chest]], [[Passive provider chest]], [[Active provider chest]] || Can send its contents to the circuit network. || Buffer and requester chests can have their requested items set by the circuit network.

Can be enabled/disabled via a circuit network condition. When disabled, chests that provide items to the logistics network no longer provide those items. When disabled, chests that request items from the logistics network no longer request those items.
||
|-
| {{Icon|Storage tank}} || [[Storage tank]] || The storage tank can send its fluid content to the circuit network. ||
|-
| {{Icon|Gate}} || [[Gate]] || Gates can send a signal to the circuit network.
*''Default'': Player detected = [[File:Signal-G.png|16px]]
|| Gates can be opened on a condition. ||
|-
| {{Icon|Nuclear reactor}} {{Icon|Heating tower|space-age=yes}} || [[Nuclear reactor]], [[Heating tower]] || The reactor and heating tower can output any fuel, including the fuel currently being burned, to the circuit network, as well as its current temperature
*''Default'': Read temperature = [[File:Signal-T.png|16px]]
||
|-
| {{Icon|Agricultural tower|space-age=yes}} || [[Agricultural tower]] || Can output any seeds and harvested plants in its inventory || Agricultural tower can be enabled on a condition || Can be enabled on a logistic network condition
|-
| {{Icon|Gun turret}} {{Icon|Laser turret}} {{Icon|Flamethrower turret}} {{Icon|Rocket turret|space-age=yes}} {{Icon|Tesla turret|space-age=yes}} {{Icon|Railgun turret|space-age=yes}} || [[Gun turret]], [[Laser turret]], [[Flamethrower turret]], [[Rocket turret]], [[Tesla turret]], [[Railgun turret]] || Can send their respective ammunition to the circuit network
* Laser and tesla turrets will not send any signal if this option is selected, due to not using ammo
|| Can enable, set priorities, and ignore priorities on a condition || Can be enabled on a logistic network condition
|-
| {{Icon|Artillery turret}} || [[Artillery turret]] || Can send its ammunition to the circuit network || Can be enabled on a condition || Can be enabled on a logistic network condition
|-
| {{Icon|Rail signal}} || [[Rail signal]] || Rail signals can send their state to the circuit network.
*''Default'': [[File:Signal-Red.png|16px]][[File:Signal-Yellow.png|16px]][[File:Signal-Green.png|16px]]
Note: If red due to circuit network, does NOT output red signal
|| Rail signals can be set to red on a condition. ||
|-
| {{Icon|Rail chain signal}} || [[Rail chain signal]] || Rail chain signals can send their state to the circuit network.
*''Default'': [[File:Signal-Red.png|16px]][[File:Signal-Yellow.png|16px]][[File:Signal-Green.png|16px]][[File:Signal-Blue.png|16px]]
||
|-
| {{Icon|Train stop}} || [[Train stop]] ||
Train stops can output:
* The contents, except fuel, of a stopped train
** Any fluid amounts are rounded down to the nearest full number, except when the fluid is < 1, then it is rounded to 1.
* The unique Train ID of a stopped train, defaulting to [[File:Signal-T.png|16px]]
* The number of trains en-route to the current stop, including the currently stopped train, defaulting to [[File:Signal-C.png|16px]]
||
* Send the signal to the train, to use in wait conditions
* Enable the stop on a condition
** Disabled stops act as if their train limit = 0. Trains attempting to go here will enter the "Destination Full" state.
* Set the stop's train limit to the value of a control signal, defaulting to [[File:Signal-L.png|16px]]
* Set the stop's priority to the value of a control signal, defaulting to "P"
|| Train stops can be enabled on a logistic network condition.
|-
| {{Icon|Accumulator}} || [[Accumulator]] || It can send its charge level in percent to the circuit network.
*''Default'': Charge % = [[File:Signal-A.png|16px]]
||
||
|-
| {{Icon|Roboport}} || [[Roboport]] || It can send its logistic network contents and/or its robot statistics to the circuit network. The signals used for robot statistics are configurable.
*''Default'': Available Logistics Bots = [[File:Signal-X.png|16px]]
*''Default'': Total Logistics Bots = [[File:Signal-Y.png|16px]]
*''Default'': Available Construction Bots = [[File:Signal-Z.png|16px]]
*''Default'': Total Construction Bots = [[File:Signal-T.png|16px]]
*''Default'': Roboports in Network = [[File:Signal-R.png|16px]]
||
|-
| {{Icon|Radar}} || [[Radar]] || Radars will transmit any signals passed into it to all other radars on the same planet.
Unlike other machine outputs, signals from red and green wires are transmitted separately.
||
||
|-
| {{Icon|Display panel}} || [[Display panel]] || || Can display a label and/or custom message on a condition ||
|-
| {{Icon|Burner mining drill}} || [[Mining drill]]s || All mining drills can send the expected resources, either from the drill itself or from the whole ore patch the drill is on. || Mining drills can be enabled on a condition. || Mining drills can be enabled on a logistic network condition.
|-
| {{Icon|Pumpjack}} || [[Pumpjack]] || It can output the current oil mining rate. || It can be enabled on a condition. || It can be enabled on a logistic network condition.
|-
| {{Icon|Power switch}} || [[Power switch]] || || Power switches can connect power networks on a condition. || It can be enabled on a logistic network condition.
|-
| {{Icon|Programmable speaker}} || [[Programmable speaker]] || || Shows alerts and plays sounds based on circuit network signals. It can be used to make simple tunes.
|-
| {{Icon|Lamp}} || [[Lamp]] || || The lamp can be enabled on a condition.
*''Color mapping'': The color is set based on the provided color signals
*''Color components'': The color is set based on the values of incoming red, green, and blue color signals, which should be between 0 and 255
*''Packed RGB'': The color is set based on a single hex encoded RGB color on the white color signal. It should be between 0 and 16777215
|| The lamp can be enabled on a logistic network condition.
|-
| {{Icon|Offshore pump}} || [[Offshore pump]] || || The offshore pump can be enabled on a condition. || The offshore pump can be enabled on a logistic network condition.
|-
| {{Icon|Pump}} || [[Pump]] || || The pump can be enabled on a condition and set its filter on a signal || The pump can be enabled on a logistic network condition.
|}

== Physical network structure ==
A circuit network consists only of those devices connected together with the same color wire. Wire can be strung directly from device to device, or across any intervening power poles. Wire length is limited by its previous connection.

Note that each connected set of wires forms a separate network. For example, it's entirely possible to have four red-wire networks and three green-wire networks. If red and green wires happen to touch the same power pole or device, the red and green networks will remain separate and will not link up. However, two red cables or two green cables will link if they touch. Use different colored cables to separate networks in close proximity.

* To connect wires or cables to a power pole, simply click on one entity, then on the base of the power pole.
* To erase a wire or cable connection, place the same color wire over an existing connection. You don't get the wire/cable back.
* To remove '''all''' connections from a power pole, shift-click on the pole. The first shift-click will remove all electrical connections, and the second will remove all red and green wires.
* When connecting to a [[arithmetic combinator]] or [[decider combinator]], take care to connect the wire to the correct input or output side. Use "Show details" mode to see the orientation of the combinator.
* Hovering the mouse cursor over an item will highlight all wires which connect to the item.
* Hovering the mouse cursor over a power pole which is part of a network will display the signals on its network. Some items like combinators will also display their input and output signals when hovered over.
* Cut-pasting entities tries to preserve all wire connections to external entities and reconnect the new ghost to all its previous connection points, even when pasted multiple times, making it easy to rearrange entities without breaking connections.
* Deconstructing a power pole tries to keep all affected wire connections intact, forming new wires between previously-connected entities as needed. This can result in redundant wire connections forming when cut-pasting or undoing deconstruction. Note that this doesn't happen when the power pole is destroyed, though its ghost remains connected.

== Combinators ==
Combinators can function as both receiving and sending devices and allow more advanced functions to be used on a circuit network.

*The [[constant combinator]] broadcasts up to 20 values on any of the channels for whatever networks it is connected to. (You cannot currently specify whether a value should be on the red or green channel; if you need different values, use two combinators, one for each color wire.) You can use any item channel or any of the [[#Virtual signals|virtual signal]] channels.
**Note that using two of the 20 slots to broadcast values on the '''same''' channel is the same as broadcasting the sum of the two values from one slot.
*The [[arithmetic combinator]] performs arithmetic operations on input values and broadcasts the result to the specified output channel. The input and output channels can be any item channel or any of the virtual signal channels.
** Connecting: The arithmetic combinator connects to a red or green network on its '''input''' side (the terminals are set into the main body and look like spark plugs) and performs an arithmetic calculation which is broadcast into the specified channel on its '''output''' side (the output wires appear to stretch out a bit from the body of the device).
** Feedback: Note that the input network and the output network '''are not the same network'''. Connecting the output network back to the input network will result in a feedback loop. For example, adding 1 to the value for copper plates and broadcasting it as copper plates is an action that results in an infinite loop if output is connected back to input. The value for copper plates will rapidly (but not instantly) shoot upward. (The rate at which it climbs is determined by the current tick rate.) This technique can be combined with decider combinator logic to make electronic clocks, gates, and other systems; see [[Tutorial:Combinator tutorial|Combinator Tutorial]] for advanced techniques.
** Each: This combinator can use the 'Each' signal for both input and output, in which case '''all''' non-zero input channels will have the combinator's operation performed and broadcast on the output side. Having Each signals for input and output and using a non-changing operation (like adding zero) is equivalent to having a 'one-way' wire; all the information from the input network is copied to the output network, but the reverse is not true.
**Multi-network: The arithmetic combinator can be joined to both red and green networks on the input side and will sum their inputs.
*The [[decider combinator]] functions much like an arithmetic combinator, but is designed to compare values. Essentially, it is a conditional. In terms of connecting, feedback, and the Each signal it functions as specified above. In addition, it can handle the Everything and Anything signals, and performs more complex functions than summing when attached to multiple networks. See the [[decider combinator]] page for more details on how to use this.
* The [[selector combinator]] has various functions designed for filtering out and analyzing specific signals from its inputs. It is able to output the largest or smallest signal in a series of inputs, output the stack size of items, count the number of inputs, and output a random input every certain number of game ticks. If [[Space Age]]{{SA}} is enabled, it has three more functions for detecting an item's rocket capacity, and filtering/transferring [[quality]]{{SA}} grades.

== Virtual signals ==
[[File:Virtual_Signals_dialog_box.png|thumb|Some of the Virtual Signals available for use in the circuit network in the base game]]
Virtual signals are special signals that do not correspond to game items or fluids. Other than the three logic signals, virtual signals do not behave differently from item signals.

There are 177 virtual signals available (or 241 in [[Space Age]]{{SA}}) split between the Signals, Enemies, Environment, and Unsorted tabs. These include but are not limited to, numbers, letters, various lines & arrows, information icons, every [[enemies|enemy]] variant, environmental features, and the signal for the planet [[Nauvis]].

Additionally, if the "Show parameters in selection lists" option is enabled under game Settings > Interface > Interaction, the Unsorted tab receives 10 special purple "parameter" icons which can be used for blueprint [[Blueprint#Parameterisation|parameterisation]].

=== Logic signals ===
[[File:logic_signals.png|300px|thumb|The icons of the three logic signals]]
Three of the virtual signals cannot be sent over a network but apply special logic to multiple signals.

==== Everything ====
''Everything'' can be used on the left side in conditionals. The condition will be true when the condition is true for each input signal. The condition is also true if there are no signals. This means that the ''everything'' signal behaves as [[:Wikipedia:universal quantification|universal quantification]]. A signal is present if it is nonzero, so "Everything ≠ 0" is always true.

If a signal (rather than a constant number) is used on the right side of the comparison with ''everything'', it is implicitly excluded from the set of signals that ''everything'' checks, so the signal is not matched against itself. That means it is meaningful to test e.g. ''everything'' > ''X'', without getting a trivially false result on ''X'' > ''X''.

The output of a [[decider combinator]] may also use ''everything'', unless the input is set to ''each''. When used, the combinator will output a signal on every channel with non-zero input as long as the condition is true; the value will either be the input value or 1, depending on the corresponding setting.

==== Anything ====
''Anything'' can be used on the left side of conditions. It will be false when there are no inputs. The condition will be true when the condition is true for at least one signal. This means the ''anything'' signal behaves as [[:Wikipedia:existential quantification|existential quantification]]. A signal is present if it is nonzero, so "Anything = 0" is always false.

If a signal (rather than a constant number) is used on the right side of the comparison with ''anything'', it is implicitly excluded from the set of signals that ''anything'' checks, so the signal is not matched against itself. That means it is meaningful to test e.g. ''anything'' >= ''X'', without getting a trivially true result on ''X'' >= ''X''.

When used in both the input and output of a decider combinator, ''anything'' will return the first matching signal following the order of precendence as they appear in Factoriopedia, [[wooden chest]] being first in line.

==== Each ====
''Each'' can only be used in left input side and output of [[decider combinator|decider]] and [[arithmetic combinator|arithmetic]] combinators. The signal can only be used as an output when also used as an input. When used in both the input and output, it makes a combinator perform its action on each input signal individually. The combinator will output the sum of each of the actions if only used in the input.

A combinator using ''each'' is like a stack of combinators with all inputs connected and all outputs connected in parallel. For example, if there are signals "copper plate" and "iron plate" present, one combinator would be evaluating conditions for copper, and the other combinator would be evaluating conditions for iron. The different output signals would then be added together on the shared wire.

Unlike ''everything'' and ''anything'' above, if a signal is used on the right hand side of an ''each'' operation, it is ''not'' implicitly excluded. So if you have e.g. ''each'' * ''X'' then you will also get ''X'' multiplied with itself in the output.

Each as an input will only be processed on signals that have a non-zero value. If you have a [[decider combinator|decider]] condition that inputs and output each, but wants to output only one value for an input signal that passes the condition, it will never output 1 for a signal which has a zero value, even if the condition is one that would be passed for a zero value.

== Tutorials ==
*'''[[Tutorial:Circuit network cookbook]]''' - ''Example-heavy tutorials; for beginners who want to get to know and use the benefits of the circuit network.''
*'''[[Tutorial:Combinator tutorial]]''' - ''Mainly textual and detailed tutorials.''

== Logistic network ==
The logistic network used by [[logistic robot]]s is essentially a third network (a wireless one), along with the green and red wired networks. The logistic network is based on coverage by [[roboport]]s.

Some devices can also be connected to the logistic network and enabled based on a condition. If a device has conditions set for circuit and for logistic network, it will become activated if both conditions are true. Devices that can also be controlled with the logistic network:
* Agricultural tower{{SA}}
* Crafting machines
* Inserters
* Lamp
* Mining drills
* Offshore pump
* Power switch
* Pump
* Pumpjack
* Train stop
* Transport belts
* Turrets

See the [[logistic network]] and [[roboport]] articles for more information.

== History ==

{{history|2.0.35|
* Furnaces can be connected to circuit network.}}

{{history|2.0.34|
* Extended the virtual signals, and unified/changed graphics of some of the existing ones.}}

{{history|2.0.7|
* Added selector combinator. It allows to select one of the signals, or the signal count from an input.
* Added display panel. 1X1 entity which can show specified icon and/or text, possibly also on the map. It can be also controlled by the circuit network.
* Added editable description to combinator entities.
* Decider Combinators are now allowed to check multiple conditions and send multiple outputs per combinator.
* Radar can now be connected to circuit network, allowing to wirelessly transmit a single channel of red and green signals on each planet/surface.
* All turrets (including artillery) can now be connected to the circuit network to read their current ammo count and/or deactivate them.
* Assembling machines, chemical plants, oil refineries and centrifuges can now send the ingredient list of their recipes to the circuit network.}}

{{history|0.15.0|
* Significantly improved circuit network performance. Up to 25 times less CPU usage and 10% less memory usage.
* Added the Programmable Speaker: it shows alerts and plays sounds based on circuit network signals. It can be used to make simple songs.
* Train Stop can output the contents of the stopped train's cargo.
* Train Stop can be disabled using the circuit network. Trains will skip disabled Train Stops, allowing simple train control.
* Mining Drills can be turned on and off using the circuit network. They can also output the remaining expected resources.
* Pumpjacks can be turned on and off using the circuit network. They can also output the current oil mining rate.
* Added Modulo, Power, Left Bit Shift, Right Bit Shift, Bitwise AND, Bitwise OR and Bitwise XOR to the Arithmetic Combinator.
* Added additional operators to the Decider Combinator and Circuit Conditions.}}

{{history|0.13.0|
* Many machines are now connectible to the circuit network.
* Wire disconnecting is incorporated into the latency hiding.
* Wires are now highlighted on entity mouseover.
* Reduced memory usage of circuit network.}}

{{history|0.12.33|
* Fluid values are rounded to the closest value instead of rounding down when transmitted to circuit network.}}

{{history|0.12.1|
* One can copy paste circuit network conditions between the [[inserter]], [[lamp]], [[pump]] and [[offshore pump]]. }}

{{history|0.12.0|
* Improvements to circuit network connection, one can connect multiple wires of the same color to the same entity.
* The [[lamp]], [[storage tank]], [[pump]] and [[offshore pump]] can be connected to the circuit network.
}}

{{history|0.10.0|
* [[Blueprint]]s copy circuit network connections.}}

{{history|0.8.3|
* Circuit network contents info has colored slots to specify the network it represents.}}

{{history|0.1.0|
* Introduced}}

{{C|Logistics{{!}}#Circuit network}} {{C|Circuit network{{!}}#Circuit network}}

Circuit network

2025-05-04T10:42:16Z

Flurki: Grammar correction

{{Languages}}
'''Circuit networks''' are built using [[Red wire|red]] or [[green wire]], and enable the control of receivers, based upon information broadcast onto the network by connected senders. Most senders are storage devices, and broadcast their information onto a specific channel, based on the item or liquid the storage device contains. Each circuit network contains a channel for every kind of item, as well as 48 extra [[#Virtual signals|virtual signals]] which act as user-definable channels. 'Everything', 'Anything' and 'Each' are also available wildcards.

[[File:shared_circuit_network.png|thumb|600px|right|Two circuit networks shared over one [[small electric pole]].]]

== Usage ==
=== Send information ===
Senders broadcast the amount of items or fluids they contain or other data definable by the player. Each amount is broadcast as a numeric value on a 'channel' corresponding to the item. For example, a Storage Tank containing 1000 Crude Oil will broadcast 1000 on the Crude Oil channel.

The channels are separated from each other, so each network can simultaneously carry a number for each item and fluid in the game, and for each of the extra user-defined channels (digits 0-9, letters A-Z, and 9 different colors). All unused channels have the value zero.

Multiple broadcasts of the same item or fluid are additive: If there are two connected Storage Tanks with 1000 Crude Oil each, the value of the Crude Oil channel within the network will be 2000.

All wires of the same color which are connected together by junctions form a network, i.e. they will pass their signals to each other. For example, if two red wires are connected to the same combinator input, each wire receives the content from the other. This can result in feedback if care is not taken; see Feedback (under [[#Combinators|arithmetic combinator]], below) for discussion.

Numbers are in the signed 32 bit integer range, i.e. from -2147483648 to 2147483647 inclusive, and are encoded in [https://en.wikipedia.org/wiki/Two%27s_complement two's complement representation]. The numbers wrap around on overflow, so e.g. 2147483647 + 10 becomes -2147483639. When entering a number in a combinator it can appear to exceed the 32 bit limit until the GUI is closed, at which point the number will overflow/underflow. [https://forums.factorio.com/58419]

=== Control devices ===
Receivers can use broadcast information, in most cases to enable/disable the device. They can either compare results between different channels, or compare a channel to a specific value.

Receiving devices sum all signals from each wire connected to them, even red and green wires. For example, if an inserter is connected to a red wire carrying a signal for 20 copper plates and a green wire with 10 copper plates, the input signal set for that receiver will be 30 copper plates.

Multiple wires of the same color will share & sum their signals. For example, 3 chests A, B and C connected in a row (A -> B -> C) with green wire will output the sum of their contents along any green wire connected to any of the chests. However, if a red wire connects chest A to an inserter, that inserter will only be given the contents of A as its input signal.

== Devices ==


Each device that is able to be connected to a circuit network has a [[File:Circuit network panel.png]] icon located in the top right corner of its info pane. Clicking this icon will display the available circuit network options for that device (note: a red or green wire must be connected, otherwise the message "not connected" will display instead). Clicking the [[File:Logistic network panel.png]] icon next to it, the device can be connected to a logistic network if in range of one, which also allows conditions to be set.

Conditions can be set for both circuit (signals of red and green wires are summed) and logistic network, which will together act as a logical AND.

The following devices can be connected to a circuit network:

{| class="wikitable mw-collapsible"
|-
! Icon !! Name !! Possible output signals !! Possible circuit control !! Possible logistic network control
|-
| {{Icon|Transport belt||Transport belts}} || [[Transport belts]] || Transport belts can send their content to the circuit network.
*''Pulse mode'': The signal is sent for only 1 tick when the item enters the belt.
*''Hold mode'': The signal is sent continuously as long as the items are on the belt.
*''Hold mode'' (All belts): The signal is sent continuously for all items on the entire transport belt line. The count continues through underground belts, but not splitters or side loading.
|| Transport belts can be enabled on a condition.
|| Transport belts can be enabled on a logistic network condition.
|-
| {{Icon|Inserter||Inserters}} || [[Inserters]] || All inserters can send their held items to the circuit network.
*''Pulse mode'': The signal is sent for only 1 tick when the item is picked up.
*''Hold mode'': The signal is sent continuously as long as the inserter is holding the item.
|| All inserters can be enabled on a condition. The inserter stack size can also be overridden from a control signal (configurable; values less than 1 are treated as 1). Filters can be set on a signal.
|| All inserters can be enabled on a logistic network condition.
|-
| {{Icon|Assembling machine}} {{Icon|Oil refinery}} {{Icon|Chemical plant}} {{Icon|Centrifuge}} {{Icon|Crusher|space-age=yes}} {{Icon|Foundry|space-age=yes}} {{Icon|Electromagnetic plant|space-age=yes}} {{Icon|Biochamber|space-age=yes}} {{Icon|Cryogenic plant|space-age=yes}} || [[Assembling machine]]s, [[Oil refinery]], [[Chemical plant]], [[Centrifuge]], [[Crusher]], [[Foundry]], [[Electromagnetic plant]], [[Biochamber]], [[Cryogenic plant]] || All crafting machines can output:
* Their contents, including fluids, in all slots
** Optionally, can include the items within the current crafting job
** If the machine has fuel, can optionally include the current fuel, including the unit of fuel currently being burned
* The ingredients of the set recipe
* A control signal, for 1 tick, when the recipe finishes crafting
** The signal value indicates the number of crafts finished last tick
** Includes productivity crafts
* A control signal, while the building is working
|| All crafting machines can enable on a condition and set their recipe based on a signal
||
|-
| {{Icon|Stone furnace}} {{Icon|Steel furnace}} {{Icon|Electric furnace}} {{Icon|Recycler}} || [[Furnace]]s and the [[Recycler]]{{SA}} || Furnace-style crafting machines can output:
* Their contents, including fluids, but not fuel, in all slots
** Optionally, can include the items within the current crafting job
** If the machine requires fuel, can optionally include the current fuel, including the unit of fuel currently being burned
* The ingredients of automatically determined recipe
* A control signal, for 1 tick, when the recipe finishes crafting
** The signal value indicates the number of crafts finished last tick
** Includes productivity crafts
* A control signal, while the building is working
|| All furnace-style crafting machines can enable on a condition
||
|-
| {{Icon|Wooden chest||Wooden chest}} {{Icon|Iron chest||Iron chest}} {{Icon|Steel chest||Steel chest}} || [[Chests]] || Can send its content to the circuit network. ||
|-
| {{Icon|Cargo landing pad}} || [[Cargo landing pad]] || The landing pad can send its contents to the circuit network. || The landing pad can have its requests set by the circuit network.{{SA}} ||
|-
| {{Icon|Rocket silo}} || [[Rocket silo]] || The rocket silo can output its contents or requests from space platforms.{{SA}} ||
||
|-
| {{Icon|Space platform hub|space-age=yes}} || [[Space platform hub]] || Can output its contents, destination and source planet, current speed, and damage taken
*''Default'': Read Speed = Signal ''V''
*''Default'': Read Damage Taken = Signal ''D''
| Platform hub can be sent the contents of the circuit network to use for wait conditions
||
|-
| {{Icon|Asteroid collector|space-age=yes}} || [[Asteroid collector]] || Can output its contents to the circuit network || Can enable on a condition and set filters on a signal ||
|-
| {{Icon|Requester chest}} {{Icon|Buffer chest}} {{Icon|Storage chest}} {{Icon|Passive provider chest}} {{Icon|Active provider chest}} || [[Requester chest]], [[Buffer chest]], [[Storage chest]], [[Passive provider chest]], [[Active provider chest]] || Can send its contents to the circuit network. || Buffer and requester chests can have their requested items set by the circuit network.

Can be enabled/disabled via a circuit network condition. When disabled, chests that provide items to the logistics network no longer provide those items. When disabled, chests that request items from the logistics network no longer request those items.
||
|-
| {{Icon|Storage tank}} || [[Storage tank]] || The storage tank can send its fluid content to the circuit network. ||
|-
| {{Icon|Gate}} || [[Gate]] || Gates can send a signal to the circuit network.
*''Default'': Player detected = [[File:Signal-G.png|16px]]
|| Gates can be opened on a condition. ||
|-
| {{Icon|Nuclear reactor}} {{Icon|Heating tower|space-age=yes}} || [[Nuclear reactor]], [[Heating tower]] || The reactor and heating tower can output any fuel, including the fuel currently being burned, to the circuit network, as well as its current temperature
*''Default'': Read temperature = [[File:Signal-T.png|16px]]
||
|-
| {{Icon|Agricultural tower|space-age=yes}} || [[Agricultural tower]] || Can output any seeds and harvested plants in its inventory || Agricultural tower can be enabled on a condition || Can be enabled on a logistic network condition
|-
| {{Icon|Gun turret}} {{Icon|Laser turret}} {{Icon|Flamethrower turret}} {{Icon|Rocket turret|space-age=yes}} {{Icon|Tesla turret|space-age=yes}} {{Icon|Railgun turret|space-age=yes}} || [[Gun turret]], [[Laser turret]], [[Flamethrower turret]], [[Rocket turret]], [[Tesla turret]], [[Railgun turret]] || Can send their respective ammunition to the circuit network
* Laser and tesla turrets will not send any signal if this option is selected, due to not using ammo
|| Can enable, set priorities, and ignore priorities on a condition || Can be enabled on a logistic network condition
|-
| {{Icon|Artillery turret}} || [[Artillery turret]] || Can send its ammunition to the circuit network || Can be enabled on a condition || Can be enabled on a logistic network condition
|-
| {{Icon|Rail signal}} || [[Rail signal]] || Rail signals can send their state to the circuit network.
*''Default'': [[File:Signal-Red.png|16px]][[File:Signal-Yellow.png|16px]][[File:Signal-Green.png|16px]]
Note: If red due to circuit network, does NOT output red signal
|| Rail signals can be set to red on a condition. ||
|-
| {{Icon|Rail chain signal}} || [[Rail chain signal]] || Rail chain signals can send their state to the circuit network.
*''Default'': [[File:Signal-Red.png|16px]][[File:Signal-Yellow.png|16px]][[File:Signal-Green.png|16px]][[File:Signal-Blue.png|16px]]
||
|-
| {{Icon|Train stop}} || [[Train stop]] ||
Train stops can output:
* The contents, except fuel, of a stopped train
** Any fluid amounts are rounded down to the nearest full number, except when the fluid is < 1, then it is rounded to 1.
* The unique Train ID of a stopped train, defaulting to [[File:Signal-T.png|16px]]
* The number of trains en-route to the current stop, including the currently stopped train, defaulting to [[File:Signal-C.png|16px]]
||
* Send the signal to the train, to use in wait conditions
* Enable the stop on a condition
** Disabled stops act as if their train limit = 0. Trains attempting to go here will enter the "Destination Full" state.
* Set the stop's train limit to the value of a control signal, defaulting to [[File:Signal-L.png|16px]]
* Set the stop's priority to the value of a control signal, defaulting to "P"
|| Train stops can be enabled on a logistic network condition.
|-
| {{Icon|Accumulator}} || [[Accumulator]] || It can send its charge level in percent to the circuit network.
*''Default'': Charge % = [[File:Signal-A.png|16px]]
||
||
|-
| {{Icon|Roboport}} || [[Roboport]] || It can send its logistic network contents and/or its robot statistics to the circuit network. The signals used for robot statistics are configurable.
*''Default'': Available Logistics Bots = [[File:Signal-X.png|16px]]
*''Default'': Total Logistics Bots = [[File:Signal-Y.png|16px]]
*''Default'': Available Construction Bots = [[File:Signal-Z.png|16px]]
*''Default'': Total Construction Bots = [[File:Signal-T.png|16px]]
*''Default'': Roboports in Network = [[File:Signal-R.png|16px]]
||
|-
| {{Icon|Radar}} || [[Radar]] || Radars will transmit any signals passed into it to all other radars on the same planet.
Unlike other machine outputs, signals from red and green wires are transmitted separately.
||
||
|-
| {{Icon|Display panel}} || [[Display panel]] || || Can display a label and/or custom message on a condition ||
|-
| {{Icon|Burner mining drill}} || [[Mining drill]]s || All mining drills can send the expected resources, either from the drill itself or from the whole ore patch the drill is on. || Mining drills can be enabled on a condition. || Mining drills can be enabled on a logistic network condition.
|-
| {{Icon|Pumpjack}} || [[Pumpjack]] || It can output the current oil mining rate. || It can be enabled on a condition. || It can be enabled on a logistic network condition.
|-
| {{Icon|Power switch}} || [[Power switch]] || || Power switches can connect power networks on a condition. || It can be enabled on a logistic network condition.
|-
| {{Icon|Programmable speaker}} || [[Programmable speaker]] || || Shows alerts and plays sounds based on circuit network signals. It can be used to make simple tunes.
|-
| {{Icon|Lamp}} || [[Lamp]] || || The lamp can be enabled on a condition.
*''Color mapping'': The color is set based on the provided color signals
*''Color components'': The color is set based on the values of incoming red, green, and blue color signals, which should be between 0 and 255
*''Packed RGB'': The color is set based on a single hex encoded RGB color on the white color signal. It should be between 0 and 16777215
|| The lamp can be enabled on a logistic network condition.
|-
| {{Icon|Offshore pump}} || [[Offshore pump]] || || The offshore pump can be enabled on a condition. || The offshore pump can be enabled on a logistic network condition.
|-
| {{Icon|Pump}} || [[Pump]] || || The pump can be enabled on a condition and set its filter on a signal || The pump can be enabled on a logistic network condition.
|}

== Physical network structure ==
A circuit network consists only of those devices connected together with the same color wire. Wire can be strung directly from device to device, or across any intervening power poles. Wire length is limited by its previous connection.

Note that each connected set of wires forms a separate network. For example, it's entirely possible to have four red-wire networks and three green-wire networks. If red and green wires happen to touch the same power pole or device, the red and green networks will remain separate and will not link up. However, two red cables or two green cables will link if they touch. Use different colored cables to separate networks in close proximity.

* To connect wires or cables to a power pole, simply click on one entity, then on the base of the power pole.
* To erase a wire or cable connection, place the same color wire over an existing connection. You don't get the wire/cable back.
* To remove '''all''' connections from a power pole, shift-click on the pole. The first shift-click will remove all electrical connections, and the second will remove all red and green wires.
* When connecting to a [[arithmetic combinator]] or [[decider combinator]], take care to connect the wire to the correct input or output side. Use "Show details" mode to see the orientation of the combinator.
* Hovering the mouse cursor over an item will highlight all wires which connect to the item.
* Hovering the mouse cursor over a power pole which is part of a network will display the signals on its network. Some items like combinators will also display their input and output signals when hovered over.
* Cut-pasting entities tries to preserve all wire connections to external entities and reconnect the new ghost to all its previous connection points, even when pasted multiple times, making it easy to rearrange entities without breaking connections.
* Deconstructing a power pole tries to keep all affected wire connections intact, forming new wires between previously-connected entities as needed. This can result in redundant wire connections forming when cut-pasting or undoing deconstruction. Note that this doesn't happen when the power pole is destroyed, though its ghost remains connected.

== Combinators ==
Combinators can function as both receiving and sending devices and allow more advanced functions to be used on a circuit network.

*The [[constant combinator]] broadcasts up to 20 values on any of the channels for whatever networks it is connected to. (You cannot currently specify whether a value should be on the red or green channel; if you need different values, use two combinators, one for each color wire.) You can use any item channel or any of the [[#Virtual signals|virtual signal]] channels.
**Note that using two of the 20 slots to broadcast values on the '''same''' channel is the same as broadcasting the sum of the two values from one slot.
*The [[arithmetic combinator]] performs arithmetic operations on input values and broadcasts the result to the specified output channel. The input and output channels can be any item channel or any of the virtual signal channels.
** Connecting: The arithmetic combinator connects to a red or green network on its '''input''' side (the terminals are set into the main body and look like spark plugs) and performs an arithmetic calculation which is broadcast into the specified channel on its '''output''' side (the output wires appear to stretch out a bit from the body of the device).
** Feedback: Note that the input network and the output network '''are not the same network'''. Connecting the output network back to the input network will result in a feedback loop. For example, adding 1 to the value for copper plates and broadcasting it as copper plates is an action that results in an infinite loop if output is connected back to input. The value for copper plates will rapidly (but not instantly) shoot upward. (The rate at which it climbs is determined by the current tick rate.) This technique can be combined with decider combinator logic to make electronic clocks, gates, and other systems; see [[Tutorial:Combinator tutorial|Combinator Tutorial]] for advanced techniques.
** Each: This combinator can use the 'Each' signal for both input and output, in which case '''all''' non-zero input channels will have the combinator's operation performed and broadcast on the output side. Having Each signals for input and output and using a non-changing operation (like adding zero) is equivalent to having a 'one-way' wire; all the information from the input network is copied to the output network, but the reverse is not true.
**Multi-network: The arithmetic combinator can be joined to both red and green networks on the input side and will sum their inputs.
*The [[decider combinator]] functions much like an arithmetic combinator, but is designed to compare values. Essentially, it is a conditional. In terms of connecting, feedback, and the Each signal it functions as specified above. In addition, it can handle the Everything and Anything signals, and performs more complex functions than summing when attached to multiple networks. See the [[decider combinator]] page for more details on how to use this.
* The [[selector combinator]] has various functions designed for filtering out and analyzing specific signals from its inputs. It is able to output the largest or smallest signal in a series of inputs, output the stack size of items, count the number of inputs, and output a random input every certain number of game ticks. If [[Space Age]]{{SA}} is enabled, it has three more functions for detecting an item's rocket capacity, and filtering/transferring [[quality]]{{SA}} grades.

== Virtual signals ==
[[File:Virtual_Signals_dialog_box.png|thumb|Some of the Virtual Signals available for use in the circuit network in the base game]]
Virtual signals are special signals that do not correspond to game items or fluids. Other than the three logic signals, virtual signals do not behave differently from item signals.

There are 177 virtual signals available (or 241 in [[Space Age]]{{SA}}) split between the Signals, Enemies, Environment, and Unsorted tabs. These include but are not limited to, numbers, letters, various lines & arrows, information icons, every [[enemies|enemy]] variant, environmental features, and the signal for the planet [[Nauvis]].

Additionally, if the "Show parameters in selection lists" option is enabled under game Settings > Interface > Interaction, the Unsorted tab receives 10 special purple "parameter" icons which can be used for blueprint [[Blueprint#Parameterisation|parameterisation]].

=== Logic signals ===
[[File:logic_signals.png|300px|thumb|The icons of the three logic signals]]
Three of the virtual signals cannot be sent over a network but apply special logic to multiple signals.

==== Everything ====
''Everything'' can be used on the left side in conditionals. The condition will be true when the condition is true for each input signal. The condition is also true if there are no signals. This means that the ''everything'' signal behaves as [[:Wikipedia:universal quantification|universal quantification]]. A signal is present if it is nonzero, so "Everything ≠ 0" is always true.

If a signal (rather than a constant number) is used on the right side of the comparison with ''everything'', it is implicitly excluded from the set of signals that ''everything'' checks, so the signal is not matched against itself. That means it is meaningful to test e.g. ''everything'' > ''X'', without getting a trivially false result on ''X'' > ''X''.

The output of a [[decider combinator]] may also use ''everything'', unless the input is set to ''each''. When used, the combinator will output a signal on every channel with non-zero input as long as the condition is true; the value will either be the input value or 1, depending on the corresponding setting.

==== Anything ====
''Anything'' can be used on the left side of conditions. It will be false when there are no inputs. The condition will be true when the condition is true for at least one signal. This means the ''anything'' signal behaves as [[:Wikipedia:existential quantification|existential quantification]]. A signal is present if it is nonzero, so "Anything = 0" is always false.

If a signal (rather than a constant number) is used on the right side of the comparison with ''anything'', it is implicitly excluded from the set of signals that ''anything'' checks, so the signal is not matched against itself. That means it is meaningful test e.g. ''anything'' >= ''X'', without getting a trivially true result on ''X'' >= ''X''.

When used in both the input and output of a decider combinator, ''anything'' will return the first matching signal following the order of precendence as they appear in Factoriopedia, [[wooden chest]] being first in line.

==== Each ====
''Each'' can only be used in left input side and output of [[decider combinator|decider]] and [[arithmetic combinator|arithmetic]] combinators. The signal can only be used as an output when also used as an input. When used in both the input and output, it makes a combinator perform its action on each input signal individually. The combinator will output the sum of each of the actions if only used in the input.

A combinator using ''each'' is like a stack of combinators with all inputs connected and all outputs connected in parallel. For example, if there are signals "copper plate" and "iron plate" present, one combinator would be evaluating conditions for copper, and the other combinator would be evaluating conditions for iron. The different output signals would then be added together on the shared wire.

Unlike ''everything'' and ''anything'' above, if a signal is used on the right hand side of an ''each'' operation, it is ''not'' implicitly excluded. So if you have e.g. ''each'' * ''X'' then you will also get ''X'' multiplied with itself in the output.

Each as an input will only be processed on signals that have a non-zero value. If you have a [[decider combinator|decider]] condition that inputs and output each, but wants to output only one value for an input signal that passes the condition, it will never output 1 for a signal which has a zero value, even if the condition is one that would be passed for a zero value.

== Tutorials ==
*'''[[Tutorial:Circuit network cookbook]]''' - ''Example-heavy tutorials; for beginners who want to get to know and use the benefits of the circuit network.''
*'''[[Tutorial:Combinator tutorial]]''' - ''Mainly textual and detailed tutorials.''

== Logistic network ==
The logistic network used by [[logistic robot]]s is essentially a third network (a wireless one), along with the green and red wired networks. The logistic network is based on coverage by [[roboport]]s.

Some devices can also be connected to the logistic network and enabled based on a condition. If a device has conditions set for circuit and for logistic network, it will become activated if both conditions are true. Devices that can also be controlled with the logistic network:
* Agricultural tower{{SA}}
* Crafting machines
* Inserters
* Lamp
* Mining drills
* Offshore pump
* Power switch
* Pump
* Pumpjack
* Train stop
* Transport belts
* Turrets

See the [[logistic network]] and [[roboport]] articles for more information.

== History ==

{{history|2.0.35|
* Furnaces can be connected to circuit network.}}

{{history|2.0.34|
* Extended the virtual signals, and unified/changed graphics of some of the existing ones.}}

{{history|2.0.7|
* Added selector combinator. It allows to select one of the signals, or the signal count from an input.
* Added display panel. 1X1 entity which can show specified icon and/or text, possibly also on the map. It can be also controlled by the circuit network.
* Added editable description to combinator entities.
* Decider Combinators are now allowed to check multiple conditions and send multiple outputs per combinator.
* Radar can now be connected to circuit network, allowing to wirelessly transmit a single channel of red and green signals on each planet/surface.
* All turrets (including artillery) can now be connected to the circuit network to read their current ammo count and/or deactivate them.
* Assembling machines, chemical plants, oil refineries and centrifuges can now send the ingredient list of their recipes to the circuit network.}}

{{history|0.15.0|
* Significantly improved circuit network performance. Up to 25 times less CPU usage and 10% less memory usage.
* Added the Programmable Speaker: it shows alerts and plays sounds based on circuit network signals. It can be used to make simple songs.
* Train Stop can output the contents of the stopped train's cargo.
* Train Stop can be disabled using the circuit network. Trains will skip disabled Train Stops, allowing simple train control.
* Mining Drills can be turned on and off using the circuit network. They can also output the remaining expected resources.
* Pumpjacks can be turned on and off using the circuit network. They can also output the current oil mining rate.
* Added Modulo, Power, Left Bit Shift, Right Bit Shift, Bitwise AND, Bitwise OR and Bitwise XOR to the Arithmetic Combinator.
* Added additional operators to the Decider Combinator and Circuit Conditions.}}

{{history|0.13.0|
* Many machines are now connectible to the circuit network.
* Wire disconnecting is incorporated into the latency hiding.
* Wires are now highlighted on entity mouseover.
* Reduced memory usage of circuit network.}}

{{history|0.12.33|
* Fluid values are rounded to the closest value instead of rounding down when transmitted to circuit network.}}

{{history|0.12.1|
* One can copy paste circuit network conditions between the [[inserter]], [[lamp]], [[pump]] and [[offshore pump]]. }}

{{history|0.12.0|
* Improvements to circuit network connection, one can connect multiple wires of the same color to the same entity.
* The [[lamp]], [[storage tank]], [[pump]] and [[offshore pump]] can be connected to the circuit network.
}}

{{history|0.10.0|
* [[Blueprint]]s copy circuit network connections.}}

{{history|0.8.3|
* Circuit network contents info has colored slots to specify the network it represents.}}

{{history|0.1.0|
* Introduced}}

{{C|Logistics{{!}}#Circuit network}} {{C|Circuit network{{!}}#Circuit network}}

Time

2023-11-10T10:30:09Z

Flurki: typo

{{Languages}}__NOTOC__
[[File:clock_hi_res.png|80px|left]]
The concept of '''Time''' in Factorio is used for many different implements, most notably crafting time and game time.

== Crafting time and speed ==
When hovering over an item recipe, the player may see a clock symbol and a number. This is the amount of time needed to craft the item in seconds at crafting speed 1. The player always crafts at speed 1 while [[assembling machine]]s have different crafting speeds. [[Module]]s may also affect crafting time, either speeding it up or slowing it down for some other benefit. The player, when handcrafting, crafts with a multiplier of 1, so items that claim to take 10 seconds to craft will take 10 seconds, but an [[assembling machine 1]] with a multiplier of 0.5 will take 20 seconds. It is important to take this into consideration when creating setups with proper ratios.{{clear}}

== Ticks ==
The base unit of all time inside Factorio. When running at game speed 1, there should always be 60 ticks in every real-time second leading to the figure of 60 updates per second, short UPS. This means that 1 tick should ideally always take 1/60th of a real-time second (0.01667 seconds). However, it is possible to change the [http://lua-api.factorio.com/latest/LuaGameScript.html#LuaGameScript.speed game speed] using mods or console commands, so it is possible that ticks don't take 0.01667 real-time seconds. Furthermore, game speed will automatically slow down when the computer that is running the game is unable to do all needed calculations in the wanted 0.01667 real-time seconds. The "show-fps" [[debug mode|debug option]] allows to see the current UPS which can be used to estimate how long a tick currently takes.

== Seconds ==
As stated above, there should always be 60 ticks in every second, so 1 in-game second equals 60 in-game ticks. The 60 to 1 ratio is also applied when the game runs at lower speeds, so an in-game second can take longer than a real-time second.

== Days ==
[[File:day_night_comparison.png|thumb|270px|right|Juxtaposition of day and night.]]

An in-game day lasts 25000 ticks or 416.66~ in-game seconds.

The light varies throughout the day in a cycle consisting of 4 phases:
{| class="wikitable"
! Phase Name !! Internal name !! Behaviour !! Time of day at start !! Time of day at end !! Duration (in ticks) || Duration (in seconds)
|-
|day || dawn ||fully light ||0.75 ||0.25 ||12500 ||208.33~
|-
|sunset|| dusk ||darkening ||0.25 ||0.45 ||5000 ||83.33~
|-
|night || evening ||fully dark ||0.45 ||0.55 ||2500 ||41.66~
|-
|sunrise || morning ||lightening ||0.55 ||0.75 ||5000 ||83.33~
|}

------------- day -------><----- sunset ----->< night -><----- sunrise ----><-------- day ------------

% 0 5 10 15 20 25 30 35 40 45 50 55 60 65 70 75 80 85 90 95 100
|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|

During sunset, the light level decreases linearly from fully light to fully dark. During sunrise, it increases linearly from dark to light. This linear slope does not necessarily apply to the values returned by [https://lua-api.factorio.com/latest/LuaSurface.html#LuaSurface.darkness LuaSurface.darkness]. During night time, [[player]]s will passively activate their flashlights (or headlights if in a [[vehicle]]), and placed [[lamp]]s will turn on automatically if powered.

Note: The actual time between phases can vary +/- a tick due to rounding errors.

{{C|Main}}

Inserters

2023-11-10T09:29:53Z

Flurki: Added note explaining deviating number of ticks per rotation.

{{Languages}}
''For the common yellow electrical inserter, see [[Inserter]].''

'''Inserters''' are devices which are used to move items over short distances. When placed, they have a fixed direction. They can move items from behind and place them in front of them. By doing this, they can move items from one transport belt to another, but also extract items from—and insert items into—machines or storage devices.

== Types of inserters ==

{| class="wikitable"
| {{Imagelink|Burner inserter}} || The only [[fuel]]-powered inserter, with the slowest speed.
|-
| {{Imagelink|Inserter}} || The standard electrical inserter.
|-
| {{Imagelink|Long-handed inserter}} || Capable of inserting and removing items from a greater distance.
|-
| {{Imagelink|Fast inserter}} || Much faster than the inserter.
|-
| {{Imagelink|Filter inserter}} || Variant of the fast inserter that can filter items by type.
|-
| {{Imagelink|Stack inserter}} || As fast as the fast inserter, but can move many more items at the same time at once.
|-
| {{imagelink|Stack filter inserter}} || Variant of the stack inserter that can filter items by type.
|-
|}

==Mechanics==
Inserters '''will''':
* Pick up items off the ground, off of a [[Transport belts|transport belt]], or from any object that has storage space, including [[Chests|chests]], [[furnace]]s and [[assembling machine]]s.
* Place the item onto the ground, onto a transport belt, or into any object that has storage space.
* Run at slower speeds when starved for energy.
* Pick up as many items as their [[inserter capacity bonus (research)|stack size]] allows at once, if they do not have to wait too long to pick them up.

Inserters '''will not''':
* Pick up any items that can not be inserted into the adjacent entity.
* Pick up any items if the adjacent entity is a blueprint.
* Pick up items to place into an entity with a full inventory.
* Place more than one item at a time onto the same ground tile.
* Place items into an entity that can not hold them, for example due to [[Stack#Filtered_stacks|filtered]] or [[Stack#Stack_limitation|limited slots]].
* Fill up the entire target inventory of [[boiler]]s, [[nuclear reactor]]s, [[:Category:Producers|production building]]s, [[furnace]]s, and [[turret]]s.

If two or more inserters are picking up from the same tile, the inserter who can grab the items the fastest will grab them first. Besides faster inserters, this favors inserters taking from the inner lane of a transport belt.

=== Insertion limits ===
Depending on where an inserter is moving items, it does not always fill up the entire target inventory. This allows other inserters taking from the same transport belt to pick up their share of the items. For example, if a boiler has 5 or more items of fuel in it, an inserter will not insert additional fuel. This allows the other fuel to travel further down the transport belt. When the fuel drops below 5 items, the inserter will resume inserting fuel, up to the limit of 5 items.

{| class="wikitable"
! Entity !! Item type !! Automatic insertion limit
|-
| [[Boiler]]s, [[burner inserter]]s, [[furnace]]s, and [[nuclear reactor]]s || [[Fuel]] || align="center" | 5
|-
| [[Gun turret]]s || Bullet Magazines || align="center" | 10
|-
| [[Artillery turret]]s || [[Artillery shell]]s || align="center" | 5
|-
| [[Assembling machine]]s, [[furnace]]s, [[centrifuge]]s, [[chemical plant]]s, and [[Oil refinery|oil refineries]]|| Items needed for the recipe || The ingredients for 1 craft in addition to the ingredients for the number of crafts that can be completed during one full inserter swing; but at least the ingredients for 2 crafts and at most the ingredients for 100 crafts.[https://forums.factorio.com/viewtopic.php?p=309796#p309796]
|-
| [[Lab]]s || [[Science pack]]s || The number of science packs needed for one research unit in addition to the science packs for the number of research units that can be completed during one full inserter swing; but at least the ingredients for 2 research units and at most the ingredients for 100 research units.
|}

An inserter that has a higher [[inserter capacity bonus (research)|inserter capacity bonus]] than 1 can overfill the target building, due to the inserter picking up a higher amount of items than needed. Overfilling can also occur if multiple inserters are used to insert items into one building.

=== Inserters and transport belts ===
[[Transport belts]] have two lanes on which items can travel. Inserters only place items onto one side of the belt, either the far side from the inserter's perspective or if the belt is going the same or the opposite direction as the inserter the right side from the belt's perspective.

{|
| style="width:320px;" | [[File:Inserter_dropoff_locations.gif]] || [[File:Inserter_pickup_locations.gif]]
|-
| style="width:320px;" | Inserters place the item on the furthest lane. If a belt is in the same orientation as the inserter, the item will be placed on the right-hand lane, from the belt's perspective. In curves the inserter always places on the far side.
| style="width:320px;" | If the belt is perpendicular to the inserter, inserters '''prefer''' taking items from the nearest lane. If the nearest lane is empty, the inserter will take from the far lane. If the belt is the same/opposite orientation of the inserter or a curve, the inserter '''prefers''' taking from the left lane, from the belt's perspective. If the left lane is empty it will take from the right lane.
|}

=== Potential issues ===
Inserters may have problems picking up items:

* From very fast belts, because the items are moving too quickly.
* From the entry or exit of an underground belt (because the time they have to pick up is shorter)
* From turning belts if the item is on the inside of the corner

== Power usage ==
* Electric inserters drain energy even when they are not moving, as idle power
* The amount of energy used is the same for every turn
* The [[burner inserter]] does not drain energy when idle, but uses more energy when it is active.

== Inserter speed ==
[[File:all_inserter_speeds.gif|frame|right|Animation showing all inserter speeds at once.]]
{| class="wikitable"
! Type
! Rotation-speed (turns per [[Time#Ticks|tick]]) Extension-speed ([[Map_structure#Tile|Tiles]] per Tick)
! Turns per [[Time#Seconds|Game-second]]
! Game-second per full turn
! Ticks per full turn
|- align="center"
| align="left"| {{Imagelink|Burner inserter}} || 0.01 0.0214 || 0.60 || 1.667 || 100
|- align="center"
| align="left"| {{Imagelink|Inserter}} || 0.014 0.03 || 0.83 || 1.2 || 72
|- align="center"
| align="left"| {{Imagelink|Long-handed inserter}} || 0.02 0.0457 || 1.2 || 0.833 || 50
|- align="center"
| align="left"| {{Imagelink|Fast inserter}} {{Imagelink|Filter inserter}} {{Imagelink|Stack inserter}} {{imagelink|Stack filter inserter}} || 0.04 0.07 || 2.31 || 0.433 || 26
|-
|}

'''Note:''' These numbers come directly from the [https://github.com/wube/factorio-data/tree/master/base/prototypes/entity factorio-data github repository].

===Rotation Speed===
Convention: 2π rad = 100% of a circle rotation = '''1 turn''' (or one full rotation).

Note: an Inserter doesn't always need to make full turns. When grabbing from a transport belt, it is slightly faster when grabbing items from the closest lane.

Note: If the rotation speed of an inserter would result in an uneven number of ticks per full turn, the actual number of ticks per full turn for this inserter is the next higher even number. The reason for this is that the inserter needs to do two half turns to pick and drop an item. This takes a certain number of ticks two times, therefore the number of ticks for the full turn is always an even number. Example: The Fast inserter's rotation speed of 864°/s or 0.04 turns per tick would result in 25 ticks per full turn, but the inserter cannot do a half turn in "12.5 ticks", so it actually takes 2*13 = 26 ticks per full turn.

===Extension Speed===
The extension-speed is normally not visible (only when compared to other inserters), but there are measurable speed differences when taking - for example - from the near or the far side of a belt. Also Some mods can alter the pickup and drop locations of inserters, making this stat more relevant.

==Inserter Throughput==

The following is based on experimental data from [https://docs.google.com/spreadsheets/d/1Q4hxL69qrK3qeEKU8aDkuwM3gJy6I2dJ4FYSs-FQUpI/edit?usp=sharing 1.1].
Most of the 1.1 experimental data was gathered using the following circuit blueprint to measure the exact tick difference between inserter swings. A lot of the data on this page (specifically the belt to chest data) relies heavily on the conditions of the setup on which the measurements are done. If your setup differs from the ones tested on this page, you can use the following blueprint to do the measurements yourself.

{{BlueprintString|bp-string=0eNrtXF1v4kYU/SuRq75UkMz32GhbKY996FvfuivkwBCsBYNss20U8d87NiHAwMVzHdjsKKtIURzb1zPn3K85Y3iOHmYrsyyyvIoGz9HYlKMiW1bZIo8G0V8mLVeFKW+yvDRFZYqbalosVo/T5aq6WeVj+49xNpmYwuTVzWiRj7P6xvL2c/45n1bVshzc3f2bfc1uJ+moWhTZ4na0mN/9+WKs/GX71/DvV7Of86gXZdZWGQ3+eY7K7DFPZ/XIqqelsUPKKjO3V+TpvD4qq3T0tb8dXbS2t9pR/RcN6LrXenNaZNV0bqps1LfDesjy1I5xzwZbf+lFdmZ2UmYzmubgaZiv5g/2aQPaYqoXLRdltsHyObIW+/pW9qIn+we3jxlnhRltzopeZKdcFYvZ8MFM02+ZvdvesjM73KFbn5hkRVkNj+b3LSuqlf3PDp/miv59PavS1DZqQxa1mm1KetFiaYr0he07e99iVVkSUJbX62bw+WYuzfBo/asw433QMnvE7ZVZMVplVXNI11/svQy4mEp7el3z6MDO0LCr94HdpKPpHvI4uvaZ+fSpAzWbpyPYkUfs9KLHwpi8hUa2o/Hk5VQBRHI0kfJHjp9frx4/1GWod3Ca8RYm2HH8neJFoHnhHzuvKUxea1g6BbtEw85+5jUPdtj5qNFgnlO4PMcEQKxCE0s/dp4T5xnjtIUJ6Zfn9Osot5M9zwrZsmLjbn2aiUk2qzvb070rBA6JGmurGuw+JVonXFEWtzSzkDV6YI3HgjLC2V5XizHGDowlhBCaaLqzxlHW+J41O0+uBY2ZeDUmUMbEwdCojmWSiD1rEmVNHnKQCE05FztrCmVN7VljVHAWJ/vGNMqYPhialDROmIjJq7UYZS0+sKY4lbFgUr1aS1DWkgNrzP5IHu9ZowRl7v7kVHfWNoHftZ89zCKJX5KIscmbfOxeiFJMM8Qh2BMs7PRnL+TBDtzsuLy1dTucAczVLvcyyrEZZWNTnOVNvLDWlNQ93tRp3l5Mvo20NH+qpln+uMk221gh9cF8mRbNQAfRHx0IqSFvjC6fhk0eG06KxXyY5dZKNJiks9JAbJ1mhZ/XSNgRaRC9nms/iha12MfuVeOWXjVpiSPPMkTRqpfY71XbA+tSvLxEwBEzfXrIzG9dowsXPwTMaqfC6ehqh0zlSRaHFOojlnT7mmL7xPlibIaLyXAPxT0lrjDpeDhNN5hXdkAWmapYmd0VzcnmstpS46rdgQSnvhOPynk6m/Vn6Xx5Yi0Vb+dNt/P2G4cg0IN38sncjLPVvG9m1mJho2S5mJlzQyDgENo1uKYK2ieb7HH6sFg1Sz/Ge5x+OTVG5QeOPgIHdIrXWO0QquR8/fsUoUKNnY8dGkPEaT9Q1PcBhV4UFJpAs46RrkCuOmt22Vkrh3wBNosJkvzrwsAvC4N2YYCkX0b8YJBBJgaIfEb9Zi261goNPZgh4b6u14nLwk1cr4P23xjHlkzRqWTy8y2yaK+otrjz5FRFZZ7tBg8xcOT5ispAXqUfKCzEisrAoFZIVwipojLhkC+hPphpJPkhVVQmXRigdQjz7K9oiImBg+R7tlOkY0WV0Ds5nCDhDqqixq7XQTu9nGIrKulUUdX5ihq/oaJyv96IhBg3SYu8A9LKvTChIdZTDoa0wDlCSOWUu9RLSJ3gEkd9SNWUcxcFSK3gqsueDv2eezqvOy8/yHaO327N2a0B5blnw/1aPhZkqwMGZoybdEgNB3eFIwUJRzxBNhy8m+jd8uap1m9QxQXBbRkQXM9K3aWTAN97pbiB4LcuHFahBbxgOHH4ur4tLyuKus20gLouwXHa8HVRUJfeF3BQgNowIXC+cN3kri+KgnDbMAWJO0LifIEG1IYJtw1TUM0TCqdbh5QXmOsLAkRB47YNkPWCHenTUFcsYhwd13XK+LJO6W7hKRCFBEcHfhPH6TUg8UsSnAAcVHS4dEhoU01SnP4bUtVkri9I8LM0DOcLIVVN6faRGmpoJcf5QkhVUx6tQcCIEDhtOqS8wF1fkNCaQkrc1gC2aroNrYRaOalwdIRUNaW71tRggtI4OvAbNc5AoFWWjFEyb1DB4bKhwNYhQam8IdVM7nqCgqqFIihPCKpkuqKDhpbbiqI8IaiK6aZoDdUKxTrI/cRV+9n3VPv5ETaXVvvrl6lxkafObzcqhnk3XQnfr2fw3TZQHKWgB5X53XhXYLyLDq5O39XVXWx+7/YZl4tta6mWN7/dzYG2T2+fuv4kdRLlvyH1kcqVBDUkhimF27NgSPUFBF/jZGl2VfSTy2pfwleQVTFOlr4uCveXRUEei/OekqBKcMIoC6i0iNjXOTTBCaPY0ITQ1xSnfYUUmpL5qj6a4bSvkEJT8mMF0FN30BynvoQUmlJ5O4fAqS/I0AS1Ly1RS+yQIlMR39WlVqgldkiBqeixzuDZyGndYSHC3nUhwi6w5r7vuOJ+2wpZ4FYs51fm9Uf8e29bymjcy2whJWUlT+cFC1nzdayDvS+g7UWz9MHYMUbbb4a9eUxXj/VrbN9MUW48PKZCJ0xLQbkkcr3+HxANddo=}}

===Chest to chest===

'''Note:''' Experimental data from 1.1

{| class="wikitable"
! rowspan=2 | Type
! rowspan=2 | Arm cycles per second
! colspan=6 | Items/second at [[inserter capacity bonus (research)|capacity bonus]] level (stack size)
|-
! colspan=2 | No capacity bonus
! colspan=2 | Capacity bonus 2
! colspan=2 | Capacity bonus 7
|- align="center"
| align="left"| {{Imagelink|Burner inserter}} || 0.60 || 0.60 || (1) || 1.20 || (2) || 1.80 || (3)
|- align="center"
| align="left"| {{Imagelink|Inserter}} || 0.83 || 0.83 || (1) || 1.67 || (2) || 2.50 || (3)
|- align="center"
| align="left"| {{Imagelink|Long-handed inserter}} || 1.20 || 1.20 || (1) || 2.40 || (2) || 3.60 || (3)
|- align="center"
| align="left"| {{Imagelink|Fast inserter}} {{Imagelink|Filter inserter}} || 2.31 || 2.31 || (1) || 4.62 || (2) || 6.92 || (3)
|- align="center"
| align="left"| {{Imagelink|Stack inserter}} {{imagelink|Stack filter inserter}} || 2.31 || 4.62 || (2) || 9.23 || (4) || 27.69 || (12)
|-
|}

===Chest to belt===

Throughput going from chest to belt depends on how full the belt is. An inserter will not put down an item on a belt that have items back-to-back (aka full compression) - it waits until there is a gap. However, if the gap is narrower than the item then the items upstream on the belt will stop to make room for the item being inserted. The direction of the belt compared to the inserter does not matter however.

In these measurements inserters move items onto an empty belt. Values are given for the stack sizes at three different [[inserter capacity bonus (research)|capacity bonus]] levels.

'''Note:''' Experimental data from 1.1

{| class="wikitable"
! rowspan=3 | Type
! colspan=12 | Items/second at [[inserter capacity bonus (research)|capacity bonus]] level (stack size)
|-
! colspan=4 | No capacity bonus
! colspan=4 | Capacity bonus 2
! colspan=4 | Capacity bonus 7
|-
! [[File:Transport belt.png|link=Transport belt|32px]] || [[File:Fast transport belt.png|link=Fast transport belt|32px]] || [[File:Express transport belt.png|link=Express transport belt|32px]] ||
! [[File:Transport belt.png|link=Transport belt|32px]] || [[File:Fast transport belt.png|link=Fast transport belt|32px]] || [[File:Express transport belt.png|link=Express transport belt|32px]] ||
! [[File:Transport belt.png|link=Transport belt|32px]] || [[File:Fast transport belt.png|link=Fast transport belt|32px]] || [[File:Express transport belt.png|link=Express transport belt|32px]] ||
|- align="center"
| align="left"| {{Imagelink|Burner inserter}} || 0.60 || 0.60 || 0.60 || (1) || 1.19 || 1.19 || 1.19 || (2) || 1.67 || 1.73 || 1.76 || (3)
|- align="center"
| align="left"| {{Imagelink|Inserter}} || 0.83 || 0.83 || 0.83 || (1) || 1.64 || 1.64 || 1.64 || (2) || 2.25 || 2.37 || 2.43 || (3)
|- align="center"
| align="left"| {{Imagelink|Long-handed inserter}} || 1.20 || 1.20 || 1.20 || (1) || 2.35 || 2.35 || 2.35 || (2) || 3.10 || 3.33 || 3.46 || (3)
|- align="center"
| align="left"| {{Imagelink|Fast inserter}} {{Imagelink|Filter inserter}} || 2.31 || 2.31 || 2.31 || (1) || 4.44 || 4.44 || 4.44 || (2) || 5.29 || 6.00 || 6.43 || (3)
|- align="center"
| align="left"| {{Imagelink|Stack inserter}} {{imagelink|Stack filter inserter}} || 4.44 || 4.44 || 4.44 || (2) || 5.71 || 7.06 || 7.74 || (4) || 6.79 || 10.91 || 13.85 || (12)
|-
|}

===Chest to splitter===

When an inserter drops items onto the side of a perpendicular splitter, it always is considered to do so on the input side, enabling the splitter to move half of the items to the other belt (assuming that the splitter filter/priority settings allow it to do so and that there is available space on both belts). This allows the inserter to drop its items twice as fast. A fully upgraded stack inserter can drop twelve items onto an express splitter every 38 ticks (18.95 items/second) instead of the usual 52.

[[File:Inserter to splitter comparison.png|621px|thumb|center|By inserting onto the side of a splitter, a fully-upgraded stack inserter can fill 84% of an express belt lane instead of the usual 62%.]]

[[File:Inserter belt saturation.png|414px|thumb|center|Three stack inserters can saturate an express belt if one of them inserts onto a splitter.]]

===Belt to chest (perpendicular)===

'''Note:''' Experimental data from 1.1

When picking items from a belt, many more factors come into play besides belt fullness:

* How fast the items move (i.e. if they are queued up on the belt or move at belt speed).
* Whether the belt is perpendicular to the inserter or approaches it head on.
* Whether items are on the near or far lane of a perpendicular belt.
* Whether the belt turns or not, and whether the items are in the inner or outer side of the bend.
* If the belt is an underground entrance or exit. This shortens the time items are visible to the inserter for pickup.
* All sorts of intricate timing factors between the inserter and the items on the belt, since the game simulates the arm homing in on every item.

The test setup used below is with an inserter taking items from a perpendicular belt with items on the far lane only. The belt is fully compressed and timings are both for items that move at full speed and queued up as much as possible. Values are given for the stack sizes at three different [[inserter capacity bonus (research)|capacity bonus]] levels.

{| class="wikitable"
! rowspan=4 | Type
! colspan=15 | Items/second at [[inserter capacity bonus (research)|capacity bonus]] level (stack size)
|-
! colspan=5 | No capacity bonus
! colspan=5 | Capacity bonus 2
! colspan=5 | Capacity bonus 7
|-
! colspan=3 | Items at belt speed
! rowspan=2 | Items queued up
! rowspan=2 |
! colspan=3 | Items at belt speed
! rowspan=2 | Items queued up
! rowspan=2 |
! colspan=3 | Items at belt speed
! rowspan=2 | Items queued up
! rowspan=2 |
|-
! [[File:Transport belt.png|link=Transport belt|32px]] || [[File:Fast transport belt.png|link=Fast transport belt|32px]] || [[File:Express transport belt.png|link=Express transport belt|32px]]
! [[File:Transport belt.png|link=Transport belt|32px]] || [[File:Fast transport belt.png|link=Fast transport belt|32px]] || [[File:Express transport belt.png|link=Express transport belt|32px]]
! [[File:Transport belt.png|link=Transport belt|32px]] || [[File:Fast transport belt.png|link=Fast transport belt|32px]] || [[File:Express transport belt.png|link=Express transport belt|32px]]
|- align="center"
| align="left"| {{Imagelink|Burner inserter}} || 0.60 || '''0.65''' || 0.50 || 0.64 || (1) || 1.11 || '''1.20''' || 1.13 || 1.26 || (2) || 1.61 || 1.61 || '''1.65''' || 1.71 / 1.73 / 1.86 * || (3)
|- align="center"
| align="left"| {{Imagelink|Inserter}} || '''0.94''' || '''0.94''' || '''0.94''' || 0.88 || (1) || '''1.67''' || '''1.67''' || 1.50 || 1.74 || (2) || '''2.50''' || 2.25 || 2.33 || 2.37 / 2.37 / 2.54 * || (3)
|- align="center"
| align="left"| {{Imagelink|Long-handed inserter}} || 1.18 || 1.18 || '''1.25''' || 1.20 || (1) || 2.20 || 2.31 || '''2.40''' || 2.40 || (2) || 3.21 || 3.21 || '''3.46''' || 3.40 || (3)
|- align="center"
| align="left"| {{Imagelink|Fast inserter}} {{Imagelink|Filter inserter}} || '''2.50''' || 2.31 || '''2.50''' || 2.50 || (1) || 4.50 || 4.29 || '''5.00''' || 4.80 || (2) || '''6.43''' || 6.00 || '''6.43''' || 6.43 || (3)
|- align="center"
| align="left"| {{Imagelink|Stack inserter}} {{imagelink|Stack filter inserter}} || 4.50 || 4.29 || '''5.00''' || 4.80 || (2) || 7.50 || 7.50 || '''8.00''' || 7.50 / 8.57 / 8.28 * || (4) || 7.50 || 11.25 || '''15.00''' || 7.50 / 13.09 / 15.32 * || (12)
|-
|}

<nowiki>*)</nowiki> Throughput for basic/fast/express belt.

Since there are many more factors involved, these measurements exhibit a more complex pattern than chest-to-belt.

* Boldface cells show for which belt each inserter has the best throughput on each bonus level when items move at belt speed. Higher speed belts mean that inserters have to work harder to catch the fast moving items. The effect is most noticeable for slower inserters and smaller stack sizes.
* When items are queued up the belt type hardly matters, so there is only a single column for that. The exceptions are the stack inserters - for basic transport belts it's the belt that sets the limit for stack sizes above 4, and there is also a notable difference between fast and express belts.

=== Belt to Chest (facing inserter) ===

'''Note:''' Experimental data from 1.1

When picking up items from a belt facing the inserter, there are multiple small differences between different setups. The following throughput tests are performed with [[express transport belt]]s and [[stack inserter]]s with the maximum [[inserter capacity bonus (research)|capacity bonus]].
Each setup in the following picture shows the amount of ticks per cycle of the inserter and the amount of items per second the inserter moves. These measurements are consistent in all orientations of the setup.

[[File:Inserter_belt_to_chest_throughput.png|900px]]

==See Also==
* [[Electric system]]
* [[Belt transport system]]
* [[Inserter capacity bonus (research)]]: Inserter moves more than an item per turn.

{{C|Logistics{{!}}#Inserters}} {{C|Inserters{{!}}#Inserters}}

Inserters

2023-11-09T08:25:40Z

Flurki: grammar correction

{{Languages}}
''For the common yellow electrical inserter, see [[Inserter]].''

'''Inserters''' are devices which are used to move items over short distances. When placed, they have a fixed direction. They can move items from behind and place them in front of them. By doing this, they can move items from one transport belt to another, but also extract items from—and insert items into—machines or storage devices.

== Types of inserters ==

{| class="wikitable"
| {{Imagelink|Burner inserter}} || The only [[fuel]]-powered inserter, with the slowest speed.
|-
| {{Imagelink|Inserter}} || The standard electrical inserter.
|-
| {{Imagelink|Long-handed inserter}} || Capable of inserting and removing items from a greater distance.
|-
| {{Imagelink|Fast inserter}} || Much faster than the inserter.
|-
| {{Imagelink|Filter inserter}} || Variant of the fast inserter that can filter items by type.
|-
| {{Imagelink|Stack inserter}} || As fast as the fast inserter, but can move many more items at the same time at once.
|-
| {{imagelink|Stack filter inserter}} || Variant of the stack inserter that can filter items by type.
|-
|}

==Mechanics==
Inserters '''will''':
* Pick up items off the ground, off of a [[Transport belts|transport belt]], or from any object that has storage space, including [[Chests|chests]], [[furnace]]s and [[assembling machine]]s.
* Place the item onto the ground, onto a transport belt, or into any object that has storage space.
* Run at slower speeds when starved for energy.
* Pick up as many items as their [[inserter capacity bonus (research)|stack size]] allows at once, if they do not have to wait too long to pick them up.

Inserters '''will not''':
* Pick up any items that can not be inserted into the adjacent entity.
* Pick up any items if the adjacent entity is a blueprint.
* Pick up items to place into an entity with a full inventory.
* Place more than one item at a time onto the same ground tile.
* Place items into an entity that can not hold them, for example due to [[Stack#Filtered_stacks|filtered]] or [[Stack#Stack_limitation|limited slots]].
* Fill up the entire target inventory of [[boiler]]s, [[nuclear reactor]]s, [[:Category:Producers|production building]]s, [[furnace]]s, and [[turret]]s.

If two or more inserters are picking up from the same tile, the inserter who can grab the items the fastest will grab them first. Besides faster inserters, this favors inserters taking from the inner lane of a transport belt.

=== Insertion limits ===
Depending on where an inserter is moving items, it does not always fill up the entire target inventory. This allows other inserters taking from the same transport belt to pick up their share of the items. For example, if a boiler has 5 or more items of fuel in it, an inserter will not insert additional fuel. This allows the other fuel to travel further down the transport belt. When the fuel drops below 5 items, the inserter will resume inserting fuel, up to the limit of 5 items.

{| class="wikitable"
! Entity !! Item type !! Automatic insertion limit
|-
| [[Boiler]]s, [[burner inserter]]s, [[furnace]]s, and [[nuclear reactor]]s || [[Fuel]] || align="center" | 5
|-
| [[Gun turret]]s || Bullet Magazines || align="center" | 10
|-
| [[Artillery turret]]s || [[Artillery shell]]s || align="center" | 5
|-
| [[Assembling machine]]s, [[furnace]]s, [[centrifuge]]s, [[chemical plant]]s, and [[Oil refinery|oil refineries]]|| Items needed for the recipe || The ingredients for 1 craft in addition to the ingredients for the number of crafts that can be completed during one full inserter swing; but at least the ingredients for 2 crafts and at most the ingredients for 100 crafts.[https://forums.factorio.com/viewtopic.php?p=309796#p309796]
|-
| [[Lab]]s || [[Science pack]]s || The number of science packs needed for one research unit in addition to the science packs for the number of research units that can be completed during one full inserter swing; but at least the ingredients for 2 research units and at most the ingredients for 100 research units.
|}

An inserter that has a higher [[inserter capacity bonus (research)|inserter capacity bonus]] than 1 can overfill the target building, due to the inserter picking up a higher amount of items than needed. Overfilling can also occur if multiple inserters are used to insert items into one building.

=== Inserters and transport belts ===
[[Transport belts]] have two lanes on which items can travel. Inserters only place items onto one side of the belt, either the far side from the inserter's perspective or if the belt is going the same or the opposite direction as the inserter the right side from the belt's perspective.

{|
| style="width:320px;" | [[File:Inserter_dropoff_locations.gif]] || [[File:Inserter_pickup_locations.gif]]
|-
| style="width:320px;" | Inserters place the item on the furthest lane. If a belt is in the same orientation as the inserter, the item will be placed on the right-hand lane, from the belt's perspective. In curves the inserter always places on the far side.
| style="width:320px;" | If the belt is perpendicular to the inserter, inserters '''prefer''' taking items from the nearest lane. If the nearest lane is empty, the inserter will take from the far lane. If the belt is the same/opposite orientation of the inserter or a curve, the inserter '''prefers''' taking from the left lane, from the belt's perspective. If the left lane is empty it will take from the right lane.
|}

=== Potential issues ===
Inserters may have problems picking up items:

* From very fast belts, because the items are moving too quickly.
* From the entry or exit of an underground belt (because the time they have to pick up is shorter)
* From turning belts if the item is on the inside of the corner

== Power usage ==
* Electric inserters drain energy even when they are not moving, as idle power
* The amount of energy used is the same for every turn
* The [[burner inserter]] does not drain energy when idle, but uses more energy when it is active.

== Inserter speed ==
[[File:all_inserter_speeds.gif|frame|right|Animation showing all inserter speeds at once.]]
{| class="wikitable"
! Type
! Rotation-speed (turns per [[Time#Ticks|tick]]) Extension-speed ([[Map_structure#Tile|Tiles]] per Tick)
! Turns per [[Time#Seconds|Game-second]]
! Game-second per full turn
! Ticks per full turn
|- align="center"
| align="left"| {{Imagelink|Burner inserter}} || 0.01 0.0214 || 0.60 || 1.667 || 100
|- align="center"
| align="left"| {{Imagelink|Inserter}} || 0.014 0.03 || 0.83 || 1.2 || 72
|- align="center"
| align="left"| {{Imagelink|Long-handed inserter}} || 0.02 0.0457 || 1.2 || 0.833 || 50
|- align="center"
| align="left"| {{Imagelink|Fast inserter}} {{Imagelink|Filter inserter}} {{Imagelink|Stack inserter}} {{imagelink|Stack filter inserter}} || 0.04 0.07 || 2.31 || 0.433 || 26
|-
|}

'''Note:''' These numbers come directly from the [https://github.com/wube/factorio-data/tree/master/base/prototypes/entity factorio-data github repository].

===Rotation Speed===
Convention: 2π rad = 100% of a circle rotation = '''1 turn''' (or one full rotation).

Note: an Inserter doesn't always need to make full turns. When grabbing from a transport belt, it is slightly faster when grabbing items from the closest lane.

===Extension Speed===
The extension-speed is normally not visible (only when compared to other inserters), but there are measurable speed differences when taking - for example - from the near or the far side of a belt. Also Some mods can alter the pickup and drop locations of inserters, making this stat more relevant.

==Inserter Throughput==

The following is based on experimental data from [https://docs.google.com/spreadsheets/d/1Q4hxL69qrK3qeEKU8aDkuwM3gJy6I2dJ4FYSs-FQUpI/edit?usp=sharing 1.1].
Most of the 1.1 experimental data was gathered using the following circuit blueprint to measure the exact tick difference between inserter swings. A lot of the data on this page (specifically the belt to chest data) relies heavily on the conditions of the setup on which the measurements are done. If your setup differs from the ones tested on this page, you can use the following blueprint to do the measurements yourself.

{{BlueprintString|bp-string=0eNrtXF1v4kYU/SuRq75UkMz32GhbKY996FvfuivkwBCsBYNss20U8d87NiHAwMVzHdjsKKtIURzb1zPn3K85Y3iOHmYrsyyyvIoGz9HYlKMiW1bZIo8G0V8mLVeFKW+yvDRFZYqbalosVo/T5aq6WeVj+49xNpmYwuTVzWiRj7P6xvL2c/45n1bVshzc3f2bfc1uJ+moWhTZ4na0mN/9+WKs/GX71/DvV7Of86gXZdZWGQ3+eY7K7DFPZ/XIqqelsUPKKjO3V+TpvD4qq3T0tb8dXbS2t9pR/RcN6LrXenNaZNV0bqps1LfDesjy1I5xzwZbf+lFdmZ2UmYzmubgaZiv5g/2aQPaYqoXLRdltsHyObIW+/pW9qIn+we3jxlnhRltzopeZKdcFYvZ8MFM02+ZvdvesjM73KFbn5hkRVkNj+b3LSuqlf3PDp/miv59PavS1DZqQxa1mm1KetFiaYr0he07e99iVVkSUJbX62bw+WYuzfBo/asw433QMnvE7ZVZMVplVXNI11/svQy4mEp7el3z6MDO0LCr94HdpKPpHvI4uvaZ+fSpAzWbpyPYkUfs9KLHwpi8hUa2o/Hk5VQBRHI0kfJHjp9frx4/1GWod3Ca8RYm2HH8neJFoHnhHzuvKUxea1g6BbtEw85+5jUPdtj5qNFgnlO4PMcEQKxCE0s/dp4T5xnjtIUJ6Zfn9Osot5M9zwrZsmLjbn2aiUk2qzvb070rBA6JGmurGuw+JVonXFEWtzSzkDV6YI3HgjLC2V5XizHGDowlhBCaaLqzxlHW+J41O0+uBY2ZeDUmUMbEwdCojmWSiD1rEmVNHnKQCE05FztrCmVN7VljVHAWJ/vGNMqYPhialDROmIjJq7UYZS0+sKY4lbFgUr1aS1DWkgNrzP5IHu9ZowRl7v7kVHfWNoHftZ89zCKJX5KIscmbfOxeiFJMM8Qh2BMs7PRnL+TBDtzsuLy1dTucAczVLvcyyrEZZWNTnOVNvLDWlNQ93tRp3l5Mvo20NH+qpln+uMk221gh9cF8mRbNQAfRHx0IqSFvjC6fhk0eG06KxXyY5dZKNJiks9JAbJ1mhZ/XSNgRaRC9nms/iha12MfuVeOWXjVpiSPPMkTRqpfY71XbA+tSvLxEwBEzfXrIzG9dowsXPwTMaqfC6ehqh0zlSRaHFOojlnT7mmL7xPlibIaLyXAPxT0lrjDpeDhNN5hXdkAWmapYmd0VzcnmstpS46rdgQSnvhOPynk6m/Vn6Xx5Yi0Vb+dNt/P2G4cg0IN38sncjLPVvG9m1mJho2S5mJlzQyDgENo1uKYK2ieb7HH6sFg1Sz/Ge5x+OTVG5QeOPgIHdIrXWO0QquR8/fsUoUKNnY8dGkPEaT9Q1PcBhV4UFJpAs46RrkCuOmt22Vkrh3wBNosJkvzrwsAvC4N2YYCkX0b8YJBBJgaIfEb9Zi261goNPZgh4b6u14nLwk1cr4P23xjHlkzRqWTy8y2yaK+otrjz5FRFZZ7tBg8xcOT5ispAXqUfKCzEisrAoFZIVwipojLhkC+hPphpJPkhVVQmXRigdQjz7K9oiImBg+R7tlOkY0WV0Ds5nCDhDqqixq7XQTu9nGIrKulUUdX5ihq/oaJyv96IhBg3SYu8A9LKvTChIdZTDoa0wDlCSOWUu9RLSJ3gEkd9SNWUcxcFSK3gqsueDv2eezqvOy8/yHaO327N2a0B5blnw/1aPhZkqwMGZoybdEgNB3eFIwUJRzxBNhy8m+jd8uap1m9QxQXBbRkQXM9K3aWTAN97pbiB4LcuHFahBbxgOHH4ur4tLyuKus20gLouwXHa8HVRUJfeF3BQgNowIXC+cN3kri+KgnDbMAWJO0LifIEG1IYJtw1TUM0TCqdbh5QXmOsLAkRB47YNkPWCHenTUFcsYhwd13XK+LJO6W7hKRCFBEcHfhPH6TUg8UsSnAAcVHS4dEhoU01SnP4bUtVkri9I8LM0DOcLIVVN6faRGmpoJcf5QkhVUx6tQcCIEDhtOqS8wF1fkNCaQkrc1gC2aroNrYRaOalwdIRUNaW71tRggtI4OvAbNc5AoFWWjFEyb1DB4bKhwNYhQam8IdVM7nqCgqqFIihPCKpkuqKDhpbbiqI8IaiK6aZoDdUKxTrI/cRV+9n3VPv5ETaXVvvrl6lxkafObzcqhnk3XQnfr2fw3TZQHKWgB5X53XhXYLyLDq5O39XVXWx+7/YZl4tta6mWN7/dzYG2T2+fuv4kdRLlvyH1kcqVBDUkhimF27NgSPUFBF/jZGl2VfSTy2pfwleQVTFOlr4uCveXRUEei/OekqBKcMIoC6i0iNjXOTTBCaPY0ITQ1xSnfYUUmpL5qj6a4bSvkEJT8mMF0FN30BynvoQUmlJ5O4fAqS/I0AS1Ly1RS+yQIlMR39WlVqgldkiBqeixzuDZyGndYSHC3nUhwi6w5r7vuOJ+2wpZ4FYs51fm9Uf8e29bymjcy2whJWUlT+cFC1nzdayDvS+g7UWz9MHYMUbbb4a9eUxXj/VrbN9MUW48PKZCJ0xLQbkkcr3+HxANddo=}}

===Chest to chest===

'''Note:''' Experimental data from 1.1

{| class="wikitable"
! rowspan=2 | Type
! rowspan=2 | Arm cycles per second
! colspan=6 | Items/second at [[inserter capacity bonus (research)|capacity bonus]] level (stack size)
|-
! colspan=2 | No capacity bonus
! colspan=2 | Capacity bonus 2
! colspan=2 | Capacity bonus 7
|- align="center"
| align="left"| {{Imagelink|Burner inserter}} || 0.60 || 0.60 || (1) || 1.20 || (2) || 1.80 || (3)
|- align="center"
| align="left"| {{Imagelink|Inserter}} || 0.83 || 0.83 || (1) || 1.67 || (2) || 2.50 || (3)
|- align="center"
| align="left"| {{Imagelink|Long-handed inserter}} || 1.20 || 1.20 || (1) || 2.40 || (2) || 3.60 || (3)
|- align="center"
| align="left"| {{Imagelink|Fast inserter}} {{Imagelink|Filter inserter}} || 2.31 || 2.31 || (1) || 4.62 || (2) || 6.92 || (3)
|- align="center"
| align="left"| {{Imagelink|Stack inserter}} {{imagelink|Stack filter inserter}} || 2.31 || 4.62 || (2) || 9.23 || (4) || 27.69 || (12)
|-
|}

===Chest to belt===

Throughput going from chest to belt depends on how full the belt is. An inserter will not put down an item on a belt that have items back-to-back (aka full compression) - it waits until there is a gap. However, if the gap is narrower than the item then the items upstream on the belt will stop to make room for the item being inserted. The direction of the belt compared to the inserter does not matter however.

In these measurements inserters move items onto an empty belt. Values are given for the stack sizes at three different [[inserter capacity bonus (research)|capacity bonus]] levels.

'''Note:''' Experimental data from 1.1

{| class="wikitable"
! rowspan=3 | Type
! colspan=12 | Items/second at [[inserter capacity bonus (research)|capacity bonus]] level (stack size)
|-
! colspan=4 | No capacity bonus
! colspan=4 | Capacity bonus 2
! colspan=4 | Capacity bonus 7
|-
! [[File:Transport belt.png|link=Transport belt|32px]] || [[File:Fast transport belt.png|link=Fast transport belt|32px]] || [[File:Express transport belt.png|link=Express transport belt|32px]] ||
! [[File:Transport belt.png|link=Transport belt|32px]] || [[File:Fast transport belt.png|link=Fast transport belt|32px]] || [[File:Express transport belt.png|link=Express transport belt|32px]] ||
! [[File:Transport belt.png|link=Transport belt|32px]] || [[File:Fast transport belt.png|link=Fast transport belt|32px]] || [[File:Express transport belt.png|link=Express transport belt|32px]] ||
|- align="center"
| align="left"| {{Imagelink|Burner inserter}} || 0.60 || 0.60 || 0.60 || (1) || 1.19 || 1.19 || 1.19 || (2) || 1.67 || 1.73 || 1.76 || (3)
|- align="center"
| align="left"| {{Imagelink|Inserter}} || 0.83 || 0.83 || 0.83 || (1) || 1.64 || 1.64 || 1.64 || (2) || 2.25 || 2.37 || 2.43 || (3)
|- align="center"
| align="left"| {{Imagelink|Long-handed inserter}} || 1.20 || 1.20 || 1.20 || (1) || 2.35 || 2.35 || 2.35 || (2) || 3.10 || 3.33 || 3.46 || (3)
|- align="center"
| align="left"| {{Imagelink|Fast inserter}} {{Imagelink|Filter inserter}} || 2.31 || 2.31 || 2.31 || (1) || 4.44 || 4.44 || 4.44 || (2) || 5.29 || 6.00 || 6.43 || (3)
|- align="center"
| align="left"| {{Imagelink|Stack inserter}} {{imagelink|Stack filter inserter}} || 4.44 || 4.44 || 4.44 || (2) || 5.71 || 7.06 || 7.74 || (4) || 6.79 || 10.91 || 13.85 || (12)
|-
|}

===Chest to splitter===

When an inserter drops items onto the side of a perpendicular splitter, it always is considered to do so on the input side, enabling the splitter to move half of the items to the other belt (assuming that the splitter filter/priority settings allow it to do so and that there is available space on both belts). This allows the inserter to drop its items twice as fast. A fully upgraded stack inserter can drop twelve items onto an express splitter every 38 ticks (18.95 items/second) instead of the usual 52.

[[File:Inserter to splitter comparison.png|621px|thumb|center|By inserting onto the side of a splitter, a fully-upgraded stack inserter can fill 84% of an express belt lane instead of the usual 62%.]]

[[File:Inserter belt saturation.png|414px|thumb|center|Three stack inserters can saturate an express belt if one of them inserts onto a splitter.]]

===Belt to chest (perpendicular)===

'''Note:''' Experimental data from 1.1

When picking items from a belt, many more factors come into play besides belt fullness:

* How fast the items move (i.e. if they are queued up on the belt or move at belt speed).
* Whether the belt is perpendicular to the inserter or approaches it head on.
* Whether items are on the near or far lane of a perpendicular belt.
* Whether the belt turns or not, and whether the items are in the inner or outer side of the bend.
* If the belt is an underground entrance or exit. This shortens the time items are visible to the inserter for pickup.
* All sorts of intricate timing factors between the inserter and the items on the belt, since the game simulates the arm homing in on every item.

The test setup used below is with an inserter taking items from a perpendicular belt with items on the far lane only. The belt is fully compressed and timings are both for items that move at full speed and queued up as much as possible. Values are given for the stack sizes at three different [[inserter capacity bonus (research)|capacity bonus]] levels.

{| class="wikitable"
! rowspan=4 | Type
! colspan=15 | Items/second at [[inserter capacity bonus (research)|capacity bonus]] level (stack size)
|-
! colspan=5 | No capacity bonus
! colspan=5 | Capacity bonus 2
! colspan=5 | Capacity bonus 7
|-
! colspan=3 | Items at belt speed
! rowspan=2 | Items queued up
! rowspan=2 |
! colspan=3 | Items at belt speed
! rowspan=2 | Items queued up
! rowspan=2 |
! colspan=3 | Items at belt speed
! rowspan=2 | Items queued up
! rowspan=2 |
|-
! [[File:Transport belt.png|link=Transport belt|32px]] || [[File:Fast transport belt.png|link=Fast transport belt|32px]] || [[File:Express transport belt.png|link=Express transport belt|32px]]
! [[File:Transport belt.png|link=Transport belt|32px]] || [[File:Fast transport belt.png|link=Fast transport belt|32px]] || [[File:Express transport belt.png|link=Express transport belt|32px]]
! [[File:Transport belt.png|link=Transport belt|32px]] || [[File:Fast transport belt.png|link=Fast transport belt|32px]] || [[File:Express transport belt.png|link=Express transport belt|32px]]
|- align="center"
| align="left"| {{Imagelink|Burner inserter}} || 0.60 || '''0.65''' || 0.50 || 0.64 || (1) || 1.11 || '''1.20''' || 1.13 || 1.26 || (2) || 1.61 || 1.61 || '''1.65''' || 1.71 / 1.73 / 1.86 * || (3)
|- align="center"
| align="left"| {{Imagelink|Inserter}} || '''0.94''' || '''0.94''' || '''0.94''' || 0.88 || (1) || '''1.67''' || '''1.67''' || 1.50 || 1.74 || (2) || '''2.50''' || 2.25 || 2.33 || 2.37 / 2.37 / 2.54 * || (3)
|- align="center"
| align="left"| {{Imagelink|Long-handed inserter}} || 1.18 || 1.18 || '''1.25''' || 1.20 || (1) || 2.20 || 2.31 || '''2.40''' || 2.40 || (2) || 3.21 || 3.21 || '''3.46''' || 3.40 || (3)
|- align="center"
| align="left"| {{Imagelink|Fast inserter}} {{Imagelink|Filter inserter}} || '''2.50''' || 2.31 || '''2.50''' || 2.50 || (1) || 4.50 || 4.29 || '''5.00''' || 4.80 || (2) || '''6.43''' || 6.00 || '''6.43''' || 6.43 || (3)
|- align="center"
| align="left"| {{Imagelink|Stack inserter}} {{imagelink|Stack filter inserter}} || 4.50 || 4.29 || '''5.00''' || 4.80 || (2) || 7.50 || 7.50 || '''8.00''' || 7.50 / 8.57 / 8.28 * || (4) || 7.50 || 11.25 || '''15.00''' || 7.50 / 13.09 / 15.32 * || (12)
|-
|}

<nowiki>*)</nowiki> Throughput for basic/fast/express belt.

Since there are many more factors involved, these measurements exhibit a more complex pattern than chest-to-belt.

* Boldface cells show for which belt each inserter has the best throughput on each bonus level when items move at belt speed. Higher speed belts mean that inserters have to work harder to catch the fast moving items. The effect is most noticeable for slower inserters and smaller stack sizes.
* When items are queued up the belt type hardly matters, so there is only a single column for that. The exceptions are the stack inserters - for basic transport belts it's the belt that sets the limit for stack sizes above 4, and there is also a notable difference between fast and express belts.

=== Belt to Chest (facing inserter) ===

'''Note:''' Experimental data from 1.1

When picking up items from a belt facing the inserter, there are multiple small differences between different setups. The following throughput tests are performed with [[express transport belt]]s and [[stack inserter]]s with the maximum [[inserter capacity bonus (research)|capacity bonus]].
Each setup in the following picture shows the amount of ticks per cycle of the inserter and the amount of items per second the inserter moves. These measurements are consistent in all orientations of the setup.

[[File:Inserter_belt_to_chest_throughput.png|900px]]

==See Also==
* [[Electric system]]
* [[Belt transport system]]
* [[Inserter capacity bonus (research)]]: Inserter moves more than an item per turn.

{{C|Logistics{{!}}#Inserters}} {{C|Inserters{{!}}#Inserters}}

Tutorial:Inspecting a live mod

2021-11-22T11:16:59Z

Flurki: Syntax correction

== Introduction ==
Welcome to the Inspecting-a-live-mod tutorial!

In this tutorial I will take you on an annotated tour of my mod
''Eradicator's Hand Crank Generator Deluxe''. That's a rather
long name so I'll often call it just HCG hereafter.
HCG is a fully functional mod that you can
download and play with right now! It has extensive
comments in the code to explain how and why it works.

This is an advanced tutorial that assumes that you already know how Lua works and that
you have familiarized yourself with at least the basic concepts
of Factorio modding. On that basis this tutorial aims to provide a rough overview
on how real-life mods work and shows you how to assemble the
theoretical concepts you have learned so far into a working whole. If you are not yet familiar with the basics,
[[Tutorial:Modding tutorial/Gangsir|Gangsir's modding tutorial]] is a good starting point for learning them.

First <code>settings.lua</code> shows creation of some basic setting prototypes.
Then <code>data.lua</code> covers most basic operations like creating new item,
recipe, building and technology prototypes. And how to interact with
prototypes of other mods. Finally in <code>control.lua</code> I explain how
to make custom behavior for buildings - namely how to make the
Hand Crank Generator produce power when the player presses a key on the keyboard.

You can read the files on the web on GitHub or download and extract
the mod locally to your hard-drive.

== Tutorial ==

I recommend reading in the order that the files are loaded by the game. Have fun!

* Chapter 1 : [https://github.com/lossycrypt/eradicators-hand-crank-generator/blob/master/settings.lua settings.lua]
* Chapter 2 : [https://github.com/lossycrypt/eradicators-hand-crank-generator/blob/master/data.lua data.lua]
* Bonus Chapter : [https://github.com/lossycrypt/eradicators-hand-crank-generator/blob/master/migrations/2020-08-28_HCG_2.0.0.json migration.json]
* Chapter 3 : [https://github.com/lossycrypt/eradicators-hand-crank-generator/blob/master/control.lua control.lua]

== Full mod ==

HCG is available in full on
[https://github.com/lossycrypt/eradicators-hand-crank-generator GitHub]
or on the
[https://mods.factorio.com/mod/eradicators-hand-crank-generator Factorio Mod Portal].

== See also ==
* [[Tutorial:Modding tutorial|Modding tutorial overview]]
* [[Prototype definitions|Prototype documentation]]
* [http://lua-api.factorio.com/latest/ Factorio runtime API documentation]

Tutorial:Modding tutorial/Gangsir

2021-11-22T10:29:36Z

Flurki: Grammar correction

{{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, 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 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 the game to setup the Factorio universe. In fact, it contains the function <code>extend(self, prototypes)</code> and a table called <code>raw</code>. The former is a customary way to add new stuff to the latter. It is actually data.raw that holds the prototypes for the game. (You can view the implementation in the file [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). It is important to note that data.raw only exists during the data loading stage of the game. During the control stage, when the game is running and being played, you cannot read this data; instead you read processed values through the API from the various types like LuaEntityPrototype.

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

=== More on data.raw ===

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

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

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

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

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

Because the character is ''the'' character, his type matches his name. You could define a new 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 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. 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:Modding tutorial/Gangsir

2021-11-22T10:18:24Z

Flurki: Spelling correction

{{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, 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 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 the game to setup the Factorio universe. In fact, it contains the function <code>extend(self, prototypes)</code> and a table called <code>raw</code>. The former is a customary way to add new stuff to the latter. It is actually data.raw that holds the prototypes for the game. (You can view the implementation in the file [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). It is important to note that data.raw only exists during the data loading stage of the game. During the control stage, when the game is running and being played, you cannot read this data; instead you read processed values through the API from the various types like LuaEntityPrototype.

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

=== More on data.raw ===

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

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

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

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

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

Because the character is ''the'' character, his type matches his name. You could define a new 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:Modding tutorial/Gangsir

2021-11-22T10:12:23Z

Flurki: Grammar correction

{{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, 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 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 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 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. 
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]]

Railway/Train path finding

2021-08-31T20:13:30Z

Flurki: Grammar and punctuation corrected.

{{Languages}}
Before a train moves to a target (in this case, a [[Train stop]]), it calculates the best route based on the railway network at that time.

== Path finding penalties ==

For calculation it uses a simple [[WIKIPEDIA:A*_search_algorithm|A*-algorithm]][https://www.factorio.com/blog/post/fff-331]: The pathfinder first builds a list of non-disabled stops that match the name in the schedule, then searches outward from both ends of the train at once, if applicable, in segments. A segment is an uninterrupted plain sequence of rails, with no intersections, stops, or signals (all of which define segment borders). The cost (distance) is calculated using the following weighting rules:
* Base cost for a block/segment is the length of the segment (linear grid length along the center of the rail).
* When the rail block is occupied by a train -> Add a penalty of 2 * length of the block divided by block distance from the start, so the far away occupied paths don't matter much.
* When the rail block is guarded by a [[rail signal]] set to red by the [[circuit network]] -> Add a penalty of 1000.
* When the path includes a train stop -> Add a penalty of 2000.
* When the rail block contains a train that is stopped at a train stop -> Add a penalty of 500.
* When the rail block contains a train that is stopped at a train stop and the train doesn't have other valid stops in its schedule -> Add a penalty of 1000.
* When the rail block contains a manually controlled stopped train with a passenger -> Add a penalty of 2000.
* When the rail block contains a manually controlled stopped train without a passenger -> Add a penalty of 7000.
* When the rail block contains an automatic train without a schedule -> Add a penalty of 7000.
* When the rail block contains a train currently arriving to a train stop -> Add a penalty of 100.
* When the rail block contains a train currently arriving to a rail signal -> Add a penalty of 100.
* When the rail block contains a train currently waiting at a rail signal -> Add a penalty of 100 + 0.1 for every tick the train has already waited.
* When the rail block contains a train that doesn't have a path -> Add a penalty of 1000.

== Path Revalidation ==
A rail path will be revalidated if any event happens that could make this trains path invalid. If the path is found to be invalid then the game will repath the train. Path revalidation just confirms that the current path is still valid and does not confirm that it is still the best.
The following events cause path revalidation:
* A rail is destroyed (all trains are revalidated).
* A rail is created and invalidates a signal (all trains are revalidated) .
* A signal (chain or regular) is created or destroyed (all trains are revalidated).
* A rail block changes and invalidates a signal (chain or regular) (all trains are revalidated).
* [https://lua-api.factorio.com/latest/LuaTrain.html#LuaTrain.recalculate_path LuaTrain::recalculate_path()] is called on the train by a script.
* The train's schedule is changed.
* The train's braking force gets changed and the train is currently driving normally, arriving at a signal (chain or regular) or arriving at a station.
* The train has waited at a chain signal for a multiple of 5 seconds.

== Repath events ==
There are a number of events that can cause a train to repath listed below. When one of these conditions is met the game considers possible paths from the trains current location to its destination train stop and will chose the path with the lowest score according to the penalties listed above.
=== User / script generated events ===
* A locomotive that is part of the train is rotated.
* [https://lua-api.factorio.com/latest/LuaTrain.html#LuaTrain.recalculate_path LuaTrain::recalculate_path(true)] is called on the train by a script.
* The train is switched to automatic control when it was previously manually controlled.
* The train is set to go to a station using the "Go to stop" button in the train's GUI.
* A waypoint (train stop without wait condition) is removed from the train's schedule.

=== Repaths that happen as part of normal train operation ===
* A train fails a revalidation.
* The train stop a train is heading to is renamed or destroyed.
* The train is preparing to stop at a signal (chain or regular) that changes so that the train can now continue.
* The train is braking for a signal (chain or regular) it cant reserve.
* The train enters a new rail block and can't reserve the next needed signal (chain or regular).
* The train has waited at a chain signal for a multiple of 5 seconds and there are multiple train stops with the same name as the destination.
* The train has waited at a chain signal for a multiple of 30 seconds and there is only a single train stop with the same name as the destination.
* The train wants to depart from a signal (chain or regular) that it stopped at.
* The train wants to depart from a train stop.
* The train is pathing to a train stop that gets disabled.

=== Destination full / No path trains ===
* A rail gets created.
* A train stop that is part of the train's schedule gets enabled, renamed or created.
* The train limit of a train stop that is part of the train's schedule becomes not full.
* The train stop that it currently cannot reach gets disabled or destroyed.

=== Others ===
* The train collides with something that is not a train (like a player).

== History ==

{{History|0.18.1|
* Train stop at train's starting segment exit is no longer counted into penalty. (Not mentioned above)}}

{{History|0.17.38|
* When a train performs path finding while in a chain signal sequence, the pathfinding will have a constraint to not go through reserved block before exiting the chain sequence. This solves a problem of train intersections being possible to be deadlocked even with proper chain signals usage in cases of using temporary stops or when path is changed because of station is being enabled/disabled by a circuit network. This also allowed us to to let train recalculate path spontaneously even in chain signal sequence, as it shouldn't break anything now.}}

{{History|0.16.42|
* Added train path finding penalty for train with no path equal to 1000 tiles}}

{{History|0.16.0|
* The specific penalties can now be found in the utility constants, which allows mods to change them. (Undocumented)}}

{{History|0.15.0|
* Train station adds 2000 tiles penalty when path finding, so trains try to avoid stations not related to their path.}}

{{History|0.11.17|
* Increased the pathing penalty for non-moving train in manual mode from 200 to 1000.}}

{{History|0.11.13|
* Stopped, manually controlled train adds additional penalty (related to train path finding) of 200 tiles to the block it occupies.}}

{{History|0.11.11|
* The pathfinding is based on penalties for blocked segments now. For trains waiting in station, the more remaining time in the station, the bigger penalty.}}

== See also ==

* [https://gist.github.com/Rseding91/c0d4d08d6feaed618ed4a03f6c6a8fe6 Train pathfinding code]
* [https://www.factorio.com/blog/post/fff-331 FFF #331]
* [https://www.factorio.com/blog/post/fff-68 FFF #68]
* [[Railway]]

Oil refinery

2021-05-30T11:26:11Z

Flurki: Minor layout change: made table under 'Recipes' more compact.

{{Languages}}
{{:Infobox:Oil refinery}}

The '''Oil Refinery''' processes [[crude oil]] into 3 different fluids: [[heavy oil]], [[light oil]] and [[petroleum gas]].

Oil products have many uses. Although they can be turned into [[solid fuel]] to fuel [[boiler]]s and furnaces, they are usually used to create [[plastic bar]]s, which are used in [[advanced circuit]]s, and [[sulfur]], which is used in more advanced items. They are also used as ammunition for [[flamethrower turret]]s.

== Recipes ==

The refinery has three available recipes, out of which one must be set before it can begin processing.

{|class="wikitable"
|-
! Process !! Input !! Output
|-
| {{Imagelink|Basic oil processing}} || {{Icon|Crude oil|100}} {{icon|time|5}} || {{Icon|Petroleum gas|45}}
|-
| {{Imagelink|Advanced oil processing}} (requires [[Advanced oil processing (research)]])
| {{Icon|Crude oil|100}} {{icon|water|50}} {{icon|time|5}}
| {{Icon|Heavy oil|25}} {{Icon|Light oil|45}} {{Icon|Petroleum gas|55}}
|-
| {{imagelink|Coal liquefaction}} (requires [[Coal liquefaction (research)]])
| {{icon|coal|10}} {{Icon|Heavy oil|25}} {{icon|steam|50}} {{icon|time|5}}
| {{Icon|Heavy oil|90}} {{Icon|Light oil|20}} {{Icon|Petroleum gas|10}}
|-
|}

== Notes ==
* When placing the refinery, it can be rotated, but otherwise neither input nor output tiles can be swapped in any way. (For advanced oil processing, the water input is to the right when the inputs are coming into the top.)

== Troubleshooting ==

When the refinery is working, a flame comes out of the chimney.

* You need to choose the recipe, otherwise it won't work.
* It will stop working if any of the products are not properly drained from it (that is, 100.0 heavy oil at output will prevent production of the 2 other fluids).

== History ==

{{history|0.17.60|
* Basic oil processing produces only Petroleum gas, for more streamlined oil setup in the beginning.
* Basic oil processing keeps some of the refinery input/output slots unused, so it is more clear which ones will be used by Advanced oil processing.}}

{{history|0.15.0|
* Module slots increased from 2 to 3.}}

{{history|0.11.6|
* Now disconnects from pipes when recipe is reset.}}

{{history|0.9.1|
* Now accepts modules
* Added cracking recipes}}

{{history|0.9.0|
* Introduced}}

== See also ==
* [[Oil processing]]
* [[Fluid system]]

{{ProductionNav}}
{{C|Producers}}