Official Factorio Wiki - User contributions [en]

Rich text

2026-01-07T01:22:33Z

Honktown: /* Tags */ remove period for consistency

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

== Tags ==

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

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

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

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

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

name: see below

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

tier is the internal-name of the quality

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

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

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

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

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

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

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

The color and font of text can be changed

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

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

{{C|GUI}}

Rich text

2026-01-07T01:10:59Z

Honktown: /* Tags */ added airborne-pollutant as valid class for img= icon

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

== Tags ==

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

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

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

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

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

name: see below

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

tier is the internal-name of the quality

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

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

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

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

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

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

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

The color and font of text can be changed

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

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

{{C|GUI}}

Tutorial:Mod settings

2025-05-14T01:44:57Z

Honktown: /* Reading settings */ Slight wording to clarify startup settings are also in runtime + what runtime-global is seen as

{{Languages}}
This tutorial aims to explain how to create and use mod settings. Basic knowledge of modding is assumed, so you should have at least understood [[Tutorial:Modding tutorial/Gangsir|Gangsir's modding tutorial]].

== Overview ==
Each mod can specify settings that users can change. The values of these settings can be accessed from inside the data stage or the control stage depending on their [[#The_setting_type_property|setting_type]] and allow to conditionally create or modify prototypes and to add configuration options to control scripts. They allow modders to easily create a graphical interface for their configuration options, instead of using on text files that have to be edited manually by users.

== Location ==

Mod settings are defined in the [https://lua-api.factorio.com/latest/Data-Lifecycle.html settings stage]. This stage is loaded before the data stage. There are three files in which settings can be defined:
* settings.lua
* settings-updates.lua
* settings-final-fixes.lua

First the settings.lua file is called for each mod, in the order of their dependencies and then in the [[:Wikipedia:natural sort order|natural sort order]]. After settings.lua has been called for all mods, the settings-updates.lua file is called for each mod (in the same order) and finally the settings-final-fixes.lua file is called for each mod (in the same order). These 3 different phases of the settings stage allow to change settings of other mods without needing to rely on dependencies to load last. The settings are all defined in the same stage and their user defined values are not available, therefore mods cannot conditionally create settings depending on the values of other mod settings. Since the settings stage gets loaded first, there is also no prototype data or [http://lua-api.factorio.com/latest/LuaRemote.html remote interface] available.

The "mod-settings.dat" file stored in the [[Application_directory#User_Data_directory|mods folder]] for the game contains the local players settings between game sessions similar to the player-data.json file.

== Creation ==

Mod settings are defined and modified by using the data table during the settings stage. This works [[Tutorial:Modding_tutorial/Gangsir#Prototype_creation|the same way as other prototypes]]. An example would be:
<syntaxhighlight lang="lua">
data:extend({
{
type = "bool-setting",
name = "my-mod-test-setting",
setting_type = "runtime-global",
default_value = true
}
})
</syntaxhighlight>

As you can see, the setting has multiple properties. Each setting supports the following standard prototype properties:
* name - [https://lua-api.factorio.com/latest/types/string.html string] - Mandatory.
* type - [https://lua-api.factorio.com/latest/types/string.html string] - Mandatory.
* localised_name - [https://lua-api.factorio.com/latest/types/LocalisedString.html LocalisedString] - Optional.
* localised_description - [https://lua-api.factorio.com/latest/types/LocalisedString.html LocalisedString] - Optional.
* [https://lua-api.factorio.com/latest/types/Order.html order] - [https://lua-api.factorio.com/latest/types/string.html string] - Optional.

In addition to the standard properties, mod settings also contain:

* hidden - [https://lua-api.factorio.com/latest/types/boolean.html boolean] - Optional.
* setting_type - [https://lua-api.factorio.com/latest/types/string.html string] - Mandatory.

=== The name property ===

The name of the settings prototype should be unique to avoid mod conflicts since the mod settings are global across all mods. Because of that it is recommened to prefix mod settings with your mod name, "my-mod" in this example.

=== The type property ===

There are four types of mod settings:

* bool-setting - a true/false checkbox
* int-setting - a signed 64 bit integer textfield (or selection dropdown)
* double-setting - a double precision floating point textfield (or selection dropdown)
* string-setting - a string textfield (or selection dropdown)
* color-setting - a color picker (sliders), with whole number textfields. Includes alpha.

Depending on the type, the prototype also allows or requires additional properties, these are listed below.

==== bool-setting ====
* default_value - [https://lua-api.factorio.com/latest/types/boolean.html boolean] - Mandatory.
** Defines the default value of the setting, in this case whether the checkbox is checked or not.
* forced_value - [https://lua-api.factorio.com/latest/types/boolean.html boolean] - Optional.
** Only loaded if <code>hidden = true</code>. This forces the setting to be of this value. This can be useful for mod compatiblity.[https://forums.factorio.com/viewtopic.php?p=531322#p531322]


==== int-setting ====
* default_value - [https://lua-api.factorio.com/latest/types/int64.html int64] - Mandatory.
** Defines the default value of the setting.
* minimum_value - [https://lua-api.factorio.com/latest/types/int64.html int64] - Optional.
** Defines the lowest possible number.
* maximum_value - [https://lua-api.factorio.com/latest/types/int64.html int64] - Optional.
** Defines the highest possible number.
* allowed_values - array of [https://lua-api.factorio.com/latest/types/int64.html int64] - Optional.
** Makes it possible to force the player to choose between the defined numbers, creates a dropdown instead of a texfield.
** If only one allowed value is given, the settings is forced to be of that value.

==== double-setting ====
* default_value - [https://lua-api.factorio.com/latest/types/double.html double] - Mandatory.
** Defines the default value of the setting.
* minimum_value - [https://lua-api.factorio.com/latest/types/double.html double] - Optional.
** Defines the lowest possible number.
* maximum_value - [https://lua-api.factorio.com/latest/types/double.html double] - Optional.
** Defines the highest possible number.
* allowed_values - array of [https://lua-api.factorio.com/latest/types/double.html double] - Optional.
** Makes it possible to force the player to choose between the defined numbers, creates a dropdown instead of a textfield.
** If only one allowed value is given, the settings is forced to be of that value.

==== string-setting ====
* default_value - [https://lua-api.factorio.com/latest/types/string.html string] - Mandatory.
** Defines the default value of the setting.
* allow_blank - [https://lua-api.factorio.com/latest/types/boolean.html boolean] - Optional. - Default: false
** Defines whether it's possible for the user to set the textfield to empty and apply the setting.
* auto_trim - [https://lua-api.factorio.com/latest/types/boolean.html boolean] - Optional. - Default: false
** Whether values that are input by the user should have whitespace removed from both ends of the string.
* allowed_values - array of [https://lua-api.factorio.com/latest/types/string.html string] - Optional.
** Makes it possible to force the player to choose between the defined strings, creates a dropdown instead of a textfield. The strings in the dropdown can be localized (translated) and can have a tooltip, see below.
** If only one allowed value is given, the settings is forced to be of that value.

==== color-setting ====
* default_value - [https://lua-api.factorio.com/latest/types/Color.html Color] - Mandatory.
** Defines the default value of the setting.

=== The order property ===

The order property can be used to change how the mod settings are ordered in the settings gui. Mod settings are sorted
* first by mod
* then by the setting "order" string
* then finally by the setting name.

For more info on how to use the order string, see [https://lua-api.factorio.com/latest/types/Order.html Order].

=== The hidden property ===

The hidden property can be used to hide mod settings from GUIs, so that they cannot be seen or changed by players. However, other mods can still access hidden settings.[https://forums.factorio.com/83316]

=== The setting_type property ===
[[File:Mod_settings_gui.png|right|300px|thumb|The mod settings gui. Can be reached from the main menu → Settings → Mod settings.]]
There are the overall kinds of settings:

* '''startup''': This kind of setting is available in the prototype stage, and can not be changed runtime. They have to be set to the same values for all players on a server.
* '''runtime-global''': This kind of setting is global to an entire save game and can be changed runtime. On servers, only admins can change these settings.
* '''runtime-per-user''': This kind of setting is only available runtime in the control.lua stage and each player has their own instance of this setting. When a player joins a server their local setting of "keep mod settings per save" determines if the local settings they have set are synced to the loaded save or if the save's settings are used.

This "setting_type" also determines in which tab the setting is showed in the mod settings menu.

=== Locale ===
The locale for mod settings works like any other locale in the game. The names of the groups for the setting name and description (tooltip) are "mod-setting-name" and "mod-setting-description". The dropdown items of a string setting can be localized in the "string-mod-setting" group, but the game falls back to just showing the name of the dropdown item if no localization is found. An example for mod setting localization that would be set within "locale/en/locale.cfg", is:
<pre>
[mod-setting-name]
my-mod-string-test-setting=Localized test setting name

[mod-setting-description]
my-mod-string-test-setting=Localized test setting description

[string-mod-setting]
#<setting-name>-<dropdown-item-name>=<translated dropdown item>
my-mod-string-test-setting-item-1=Item 1 localized string

[string-mod-setting-description]
#<setting-name>-<dropdown-item-name>=<tooltip of dropdown item>
my-mod-string-test-setting-item-1=Item 1 localized tooltip

</pre>

== Usage ==
=== Reading settings ===
When accessing any mod setting, you will have to specifically access the ''value'' of the setting. The data type of the value depends on the type of the setting. For string settings that use a selection of allowed values, the value of the setting is one of the original string values defined in the prototype, the localization is ignored. See also: [http://lua-api.factorio.com/latest/Concepts.html#ModSetting ModSetting concept].

In the prototype stage you can access settings of the setting_type "startup" by indexing <code>settings.startup</code> with the name of the setting. Example:
<syntaxhighlight lang="lua">
--in settings.lua:
data:extend({
{
type = "int-setting",
name = "my-mod-stone-wall-stack-size",
setting_type = "startup",
minimum_value = 1,
default_value = 100
}
})

--in data.lua:
data.raw.item["stone-wall"].stack_size = settings.startup["my-mod-stone-wall-stack-size"].value
</syntaxhighlight>

<div class="plainlinks">
In the control stage, the same start-up settings are available. More settings become available: "runtime-global" (the ''current'' settings, under the Map tab in Mod Settings) can be accessed using <code>settings.global["setting-name"]</code> (see [https://lua-api.factorio.com/latest/LuaSettings.html LuaSettings]). Settings of the setting_type "runtime-per-user" are accessed using <code>settings.get_player_settings([https://lua-api.factorio.com/latest/Concepts.html#PlayerIdentification <PlayerIdentification>])["setting-name"]</code> or <code>game.players[[https://lua-api.factorio.com/latest/Concepts.html#PlayerIdentification <PlayerIdentification>]].mod_settings["setting-name"]</code>.
</div>
Example:
<syntaxhighlight lang="lua">
--in settings.lua:
data:extend({
{
type = "string-setting",
name = "my-mod-always-difficult",
setting_type = "runtime-global",
default_value = "yes",
allowed_values = {"yes", "no"}
},
{
type = "bool-setting",
name = "my-mod-kill-player-on-entity-built",
setting_type = "runtime-per-user",
default_value = false
}
})

--in control.lua:
script.on_init(function()
if settings.global["my-mod-always-difficult"].value == "yes" then
game.difficulty_settings.recipe_difficulty = 1
game.difficulty_settings.technology_difficulty = 1
game.difficulty_settings.technology_price_multiplier = 4
end
end)

script.on_event(defines.events.on_built_entity, function(event)
local setting_value = settings.get_player_settings(event.player_index)["my-mod-kill-player-on-entity-built"].value
if setting_value then
game.get_player(event.player_index).die()
end
end)
</syntaxhighlight>

=== Writing to your own settings ===
It is possible for mods to write to their own runtime (global or per player) mod settings. This is done by writing a new [https://lua-api.factorio.com/latest/Concepts.html#ModSetting ModSetting] table to the setting.

Example:
<syntaxhighlight lang="lua">
--in settings.lua:
data:extend({
{
type = "string-setting",
name = "my-mod-always-difficult",
setting_type = "runtime-global",
default_value = "yes",
allowed_values = {"yes", "no"}
}
})

--in control.lua:
script.on_event(defines.events.on_rocket_launched, function()
settings.global["my-mod-always-difficult"] = {value = "yes"}
end)
</syntaxhighlight>

=== Changing another mod's settings ===
After creating a setting in the settings stage, it is stored in data.raw until the end of the stage, so it can be altered from another mod.

Example:
<syntaxhighlight lang="lua">
--in settings-updates.lua:
data.raw["string-setting"]["my-mod-always-difficult"].order = "abc"
</syntaxhighlight>

If the intent is to force the setting to be of a certain value that cannot be modified by players, the properties [[#The_hidden_property|hidden]], allowed_values and forced_value can be used. Modifying existing settings of other mods can be useful for mod packs or other mod compatibility goals.[https://forums.factorio.com/viewtopic.php?p=531322#p531322]

Example:
<syntaxhighlight lang="lua">
--in settings-updates.lua:
data.raw["string-setting"]["my-mod-always-difficult"].hidden = true
data.raw["string-setting"]["my-mod-always-difficult"].allowed_values = {"no"}
data.raw["string-setting"]["my-mod-always-difficult"].default_value = "no"
</syntaxhighlight>

=== Tips ===
* Do not conditionally 'require(...)' things depending on mod settings: This breaks the CRC checks and people will get errors trying to use your mod in multiplayer. 'require(...)' everything and then conditionally add the values to data.raw using the settings.
* You should cache the settings table inside the event you use it in. Accessing it is relatively expensive (about as expensive as accessing game.*prototypes[...]), so when accessing it mutliple times within the same event, you should set a local variable to it (within the event) to improve performance.
** If you want to cache startup/and runtime settings outside of events, you will have to makes sure that the local variable of settings of the setting_type "runtime-global" are updated in the <code>on_runtime_mod_setting_changed</code> event.
* If you want to detect whether a certain mod is installed in the settings stage, you can use <code>if mods["another-mods-name"] then</code>, just like in the data stage.

== See also ==
* [https://forums.factorio.com/viewtopic.php?p=207275 Forum post documenting mod settings]
* [https://forums.factorio.com/viewtopic.php?p=305644#p305644 per_user is not a valid property and has no effects!]
* [http://lua-api.factorio.com/latest/LuaSettings.html Lua api documentation on the settings table]

[[Category:Modding]]

Tutorial:Mod structure

2023-11-06T06:58:25Z

Honktown: /* dependencies */

{{Languages}}Mods are expected to have a certain structure in order to be loaded by the game. This page aims to explain that file structure and what each file is used for.

== Mod folder and file structure ==

The mod must either be in a folder, or in a folder inside a zip file. The mod folder (no zip file) must either be named in the pattern of <code>{mod-name}_{version-number}</code> or just <code>{mod-name}</code>, for example <code>test-mod-thing</code>. The mod zip must be named in the pattern of <code>{mod-name}_{version-number}</code>, for example <code>test-mod-thing_0.0.1</code>. When using a zip file for the mod, the folder inside the zip file does not have any naming restrictions; only the zip file itself must be named with the <code>{mod-name}_{version-number}</code> pattern. The mod name and its version number are defined in the [[#info.json|info.json]] file.

=== Files ===
Inside the mod folder, the game automatically reads the following files during load:
* info.json — The only mandatory file. The [[#info.json|info.json]] identifies the mod, defines its version and other general properties.
* changelog.txt — Version history of the mod, to be shown in the mod browser. The changelog file must follow the strict [[Tutorial:Mod changelog format|formatting requirements]].
* thumbnail.png — Thumbnail to be shown on the mod portal and in the mod browser in-game. Ideally a 144x144px image file.
* settings.lua — This and the next two files are used to set up mod [[Tutorial:Mod settings|configuration options]].
* settings-updates.lua
* settings-final-fixes.lua
* data.lua — This and the next two files are used to define [https://lua-api.factorio.com/latest/index-prototype.html prototypes].
* data-updates.lua — The load order of the three data*.lua files is explained on [https://lua-api.factorio.com/latest/auxiliary/data-lifecycle.html Data lifecycle].
* data-final-fixes.lua
* control.lua — This file is used for runtime scripting. Runtime scripting is documented on [https://lua-api.factorio.com/latest/index-runtime.html lua-api.factorio.com].

=== Subfolders ===
Furthermore, the following folders inside the mod folder are recognized by the game:
* locale — Can contain up to one subfolder per language, identified with the language code, for example <code>en</code> for English. The subfolder then has to contain at least one *.cfg file which defines the [[Tutorial:Localisation|translations]] for that language.
* scenarios — Custom [[scenario system|scenarios]] can be placed in subfolders of this folder.
* campaigns — Custom campaigns can be placed in subfolders of this folder.
* tutorials — Custom [[Prototype/Tutorial|tutorials]] can be placed in subfolders of this folder.
* migrations — [https://lua-api.factorio.com/latest/auxiliary/migrations.html Migration files] are placed in this folder. They are a way to handle prototype changes and mod data structure changes between mod versions or game versions.

=== Example ===
Here is an example directory structure for a mod titled <code>my-armor-mod</code> with a version number of <code>0.3.6</code>:

<pre>
my-armor-mod_0.3.6.zip
|- aFolderName/
|- control.lua
|- data.lua
|- info.json
|- thumbnail.png
</pre>

== info.json ==

The info.json file identifies the mod and defines its version. If the game encounters a problem when parsing the file, the error message can be found in the [[log file]]. A minimal info.json file can look like this:
{
"name": "test-mod-thing",
"version": "0.0.1",
"title": "My best test mod",
"author": "A very great tester",
"factorio_version": "1.1",
"dependencies": ["? optional-mod"]
}

The info.json file supports the following fields:

=== name ===
'''Type''': [[Types/string|string]]

Mandatory field. The internal name of mod. The game accepts anything as a mod name, however the mod portal restricts mod names to only consist of alphanumeric characters, dashes and underscores. Note that the mod folder or mod zip file name has to contain the mod name, where the restrictions of the file system apply.

The game accepts mod names with a maximum length of 100 characters. The mod portal only accepts mods with names that are longer than 3 characters and shorter than 50 characters.

=== version ===
'''Type''': [[Types/string|string]]

Mandatory field. Defines the version of the mod in the format <code>"number.number.number"</code> for <code>"Major.Middle.Minor"</code>, for example <code>"0.6.4"</code>. Each number can range from 0 to 65535.

=== title ===
'''Type''': [[Types/string|string]]

Mandatory field. The display name of the mod, so it is not recommended to use someUgly_pRoGrAmMeR-name here. Can be overwritten with a locale entry in the <code>mod-name</code> category, using the internal mod name as the key.

The game will reject a title field that is longer than 100 characters. However, this can be worked around by using the locale entry. The mod portal does not restrict mod title length.

=== author ===
'''Type''': [[Types/string|string]]

Mandatory field. The author of the mod. This field does not have restrictions, it can also be a list of authors etc. The mod portal ignores this field, it will simply display the uploader's name as the author.

=== contact ===
'''Type''': [[Types/string|string]]

Optional field. How the mod author can be contacted, for example an email address.

=== homepage ===
'''Type''': [[Types/string|string]]

Optional field. Where the mod can be found on the internet. Note that the in-game mod browser shows the mod portal link additionally to this field. Please don't put "None" here, it makes the field on the mod portal website look ugly. Just leave the field empty if the mod doesn't have a website/forum thread/discord.

=== description ===
'''Type''': [[Types/string|string]]

Optional field. A short description of what your mod does. This is all that people get to see in-game. Can be overwritten with a locale entry in the <code>mod-description</code> category, using the internal mod name as the key.

=== factorio_version ===
'''Type''': [[Types/string|string]]

'''Default''': "0.12"

Optional field in the format <code>"major.minor"</code>. The Factorio version that this mod supports. This can only be one Factorio version, not multiple. However, it includes all <code>.sub</code> versions. While the field is optional, usually mods are developed for versions higher than the default 0.12, so the field has to be added anyway.

Adding a sub part, e.g. "0.18.'''27'''" will make the mod portal reject the mod and the game act weirdly. That means this shouldn't be done; use only the major and minor components <code>"major.minor"</code>, for example <code>"1.0"</code>.

Mods with the factorio_version "0.18" can also be loaded in 1.0 and the mod portal will return them when queried for factorio_version 1.0 mods.

=== dependencies ===
'''Type''': array of [[#Dependency]]

'''Default''': ["base"]

Optional field. Mods that this mod depends on or is incompatible with. If this mod depends on another, the other mod will load first, see [https://lua-api.factorio.com/latest/auxiliary/data-lifecycle.html Data lifecycle]. An empty array allows to work around the default and have no dependencies at all.

Example:
<pre>"dependencies": ["mod-a", "? mod-c > 0.4.3", "! mod-g"]</pre>

: <h4>Dependency</h4>
: Each dependency is a string that consists of up to three parts: <code>"<prefix> internal-mod-name <equality-operator version>"</code>, for example <code>"? some-mod-everyone-loves >= 4.2.0"</code>.

:The equality operator (<code><, <=, =, >= or ></code>) combined with the version allows to define dependencies that require certain mod versions, but it is not required. Incompatibility does not support versions; if incompatibility is used, version is ignored.

:The possible prefixes are:
:* <code>!</code> for incompatibility
:* <code>?</code> for an optional dependency. A false match on version marks the mod as having unsatisfied requirements. (A red label)
:* <code>(?)</code> for a hidden optional dependency
:* <code>~</code> for a dependency that does not affect load order
:* no prefix for a hard requirement for the other mod.

== See also ==
* [[Tutorial:Modding tutorial|Modding tutorial overview]]
* [https://lua-api.factorio.com/latest/index-prototype.html Prototype documentation]
* [https://lua-api.factorio.com/latest/index-runtime.html Runtime API documentation]

Tutorial:Mod structure

2023-11-06T06:54:59Z

Honktown: /* dependencies */ detail on false match for optional dependency with version

{{Languages}}Mods are expected to have a certain structure in order to be loaded by the game. This page aims to explain that file structure and what each file is used for.

== Mod folder and file structure ==

The mod must either be in a folder, or in a folder inside a zip file. The mod folder (no zip file) must either be named in the pattern of <code>{mod-name}_{version-number}</code> or just <code>{mod-name}</code>, for example <code>test-mod-thing</code>. The mod zip must be named in the pattern of <code>{mod-name}_{version-number}</code>, for example <code>test-mod-thing_0.0.1</code>. When using a zip file for the mod, the folder inside the zip file does not have any naming restrictions; only the zip file itself must be named with the <code>{mod-name}_{version-number}</code> pattern. The mod name and its version number are defined in the [[#info.json|info.json]] file.

=== Files ===
Inside the mod folder, the game automatically reads the following files during load:
* info.json — The only mandatory file. The [[#info.json|info.json]] identifies the mod, defines its version and other general properties.
* changelog.txt — Version history of the mod, to be shown in the mod browser. The changelog file must follow the strict [[Tutorial:Mod changelog format|formatting requirements]].
* thumbnail.png — Thumbnail to be shown on the mod portal and in the mod browser in-game. Ideally a 144x144px image file.
* settings.lua — This and the next two files are used to set up mod [[Tutorial:Mod settings|configuration options]].
* settings-updates.lua
* settings-final-fixes.lua
* data.lua — This and the next two files are used to define [https://lua-api.factorio.com/latest/index-prototype.html prototypes].
* data-updates.lua — The load order of the three data*.lua files is explained on [https://lua-api.factorio.com/latest/auxiliary/data-lifecycle.html Data lifecycle].
* data-final-fixes.lua
* control.lua — This file is used for runtime scripting. Runtime scripting is documented on [https://lua-api.factorio.com/latest/index-runtime.html lua-api.factorio.com].

=== Subfolders ===
Furthermore, the following folders inside the mod folder are recognized by the game:
* locale — Can contain up to one subfolder per language, identified with the language code, for example <code>en</code> for English. The subfolder then has to contain at least one *.cfg file which defines the [[Tutorial:Localisation|translations]] for that language.
* scenarios — Custom [[scenario system|scenarios]] can be placed in subfolders of this folder.
* campaigns — Custom campaigns can be placed in subfolders of this folder.
* tutorials — Custom [[Prototype/Tutorial|tutorials]] can be placed in subfolders of this folder.
* migrations — [https://lua-api.factorio.com/latest/auxiliary/migrations.html Migration files] are placed in this folder. They are a way to handle prototype changes and mod data structure changes between mod versions or game versions.

=== Example ===
Here is an example directory structure for a mod titled <code>my-armor-mod</code> with a version number of <code>0.3.6</code>:

<pre>
my-armor-mod_0.3.6.zip
|- aFolderName/
|- control.lua
|- data.lua
|- info.json
|- thumbnail.png
</pre>

== info.json ==

The info.json file identifies the mod and defines its version. If the game encounters a problem when parsing the file, the error message can be found in the [[log file]]. A minimal info.json file can look like this:
{
"name": "test-mod-thing",
"version": "0.0.1",
"title": "My best test mod",
"author": "A very great tester",
"factorio_version": "1.1",
"dependencies": ["? optional-mod"]
}

The info.json file supports the following fields:

=== name ===
'''Type''': [[Types/string|string]]

Mandatory field. The internal name of mod. The game accepts anything as a mod name, however the mod portal restricts mod names to only consist of alphanumeric characters, dashes and underscores. Note that the mod folder or mod zip file name has to contain the mod name, where the restrictions of the file system apply.

The game accepts mod names with a maximum length of 100 characters. The mod portal only accepts mods with names that are longer than 3 characters and shorter than 50 characters.

=== version ===
'''Type''': [[Types/string|string]]

Mandatory field. Defines the version of the mod in the format <code>"number.number.number"</code> for <code>"Major.Middle.Minor"</code>, for example <code>"0.6.4"</code>. Each number can range from 0 to 65535.

=== title ===
'''Type''': [[Types/string|string]]

Mandatory field. The display name of the mod, so it is not recommended to use someUgly_pRoGrAmMeR-name here. Can be overwritten with a locale entry in the <code>mod-name</code> category, using the internal mod name as the key.

The game will reject a title field that is longer than 100 characters. However, this can be worked around by using the locale entry. The mod portal does not restrict mod title length.

=== author ===
'''Type''': [[Types/string|string]]

Mandatory field. The author of the mod. This field does not have restrictions, it can also be a list of authors etc. The mod portal ignores this field, it will simply display the uploader's name as the author.

=== contact ===
'''Type''': [[Types/string|string]]

Optional field. How the mod author can be contacted, for example an email address.

=== homepage ===
'''Type''': [[Types/string|string]]

Optional field. Where the mod can be found on the internet. Note that the in-game mod browser shows the mod portal link additionally to this field. Please don't put "None" here, it makes the field on the mod portal website look ugly. Just leave the field empty if the mod doesn't have a website/forum thread/discord.

=== description ===
'''Type''': [[Types/string|string]]

Optional field. A short description of what your mod does. This is all that people get to see in-game. Can be overwritten with a locale entry in the <code>mod-description</code> category, using the internal mod name as the key.

=== factorio_version ===
'''Type''': [[Types/string|string]]

'''Default''': "0.12"

Optional field in the format <code>"major.minor"</code>. The Factorio version that this mod supports. This can only be one Factorio version, not multiple. However, it includes all <code>.sub</code> versions. While the field is optional, usually mods are developed for versions higher than the default 0.12, so the field has to be added anyway.

Adding a sub part, e.g. "0.18.'''27'''" will make the mod portal reject the mod and the game act weirdly. That means this shouldn't be done; use only the major and minor components <code>"major.minor"</code>, for example <code>"1.0"</code>.

Mods with the factorio_version "0.18" can also be loaded in 1.0 and the mod portal will return them when queried for factorio_version 1.0 mods.

=== dependencies ===
'''Type''': array of [[#Dependency]]

'''Default''': ["base"]

Optional field. Mods that this mod depends on or is incompatible with. If this mod depends on another, the other mod will load first, see [https://lua-api.factorio.com/latest/auxiliary/data-lifecycle.html Data lifecycle]. An empty array allows to work around the default and have no dependencies at all.

Example:
<pre>"dependencies": ["mod-a", "? mod-c > 0.4.3", "! mod-g"]</pre>

: <h4>Dependency</h4>
: Each dependency is a string that consists of up to three parts: <code>"<prefix> internal-mod-name <equality-operator version>"</code>, for example <code>"? some-mod-everyone-loves >= 4.2.0"</code>.

:The equality operator (<code><, <=, =, >= or ></code>) combined with the version allows to define dependencies that require certain mod versions, but it is not required. Incompatibility does not support versions; if incompatibility is used, version is ignored.

:The possible prefixes are:
:* <code>!</code> for incompatibility
:* <code>?</code> for an optional dependency. A false match on version disables the mod with the optional and version dependency. (incompatibility)
:* <code>(?)</code> for a hidden optional dependency
:* <code>~</code> for a dependency that does not affect load order
:* no prefix for a hard requirement for the other mod.

== See also ==
* [[Tutorial:Modding tutorial|Modding tutorial overview]]
* [https://lua-api.factorio.com/latest/index-prototype.html Prototype documentation]
* [https://lua-api.factorio.com/latest/index-runtime.html Runtime API documentation]

Types/MapGenPreset

2023-08-15T23:52:24Z

Honktown: /* default */

== Basics ==
A map gen preset. Used in [[Prototype/MapGenPresets]].

== Mandatory properties ==

=== order ===
'''Type''': [[Types/Order]]

Specifies the ordering in the [[map generator]] gui.

== Optional properties ==

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

'''Default''': true

Whether this is the default preset. If set to true, this preset may not have any other properties besides this and order.

If no MapGenPreset has <code>default = true</code>, the preset selector will have a blank preset label, having default settings. The "blank" preset goes away when another preset is selected.

=== basic_settings ===
'''Type''': [[Types/table]]

This is a table with the below key/value pairs. All key/value pairs are optional. If not set they will just use the default values.

* terrain_segmentation - [[Types/MapGenSize]]
:: This is the inverse of "water scale" in the map generator GUI. So a water scale that shows as 50% in the GUI is a value of <code>1/0.5 = 2</code> for <code>terrain_segmentation</code>.
* water - [[Types/MapGenSize]]
:: Shown as water coverage in the map generator GUI.
* default_enable_all_autoplace_controls - [[Types/bool]] - Default: true
:: Whether undefined autoplace_controls should fall back to the default controls or not.
* autoplace_controls - [[Types/table]]
:: Table of [[Data.raw#autoplace-control]] name keys mapped to table values. Each table can have the following fields:
::* frequency - [[Types/MapGenSize]]
::* size - [[Types/MapGenSize]]
::* richness - [[Types/MapGenSize]]
::Example:
::<syntaxhighlight lang="lua">autoplace_controls =
{
["iron-ore"] = { richness = 2, size = 0.5, frequency=2},
["enemy-base"] = { size = 1},
["trees"] = { richness = 4}
}</syntaxhighlight>
* autoplace_settings - [[Types/table]] of [https://lua-api.factorio.com/latest/Concepts.html#AutoplaceSettings AutoplaceSettings]
:: Each setting in this table maps the string type to the settings for that type. Valid types are "entity", "tile" and "decorative".
* property_expression_names - [[Types/table]]
:: Map of property name (e.g. "elevation") to name of [[Prototype/NamedNoiseExpression|noise expression]] that will provide it. Entries may be omitted. A notable usage is changing autoplace behavior of an entity based on the preset, which cannot be read from a noise expression.
* starting_points - [[Types/table]] of [[Types/Position]]
:: Array of the positions of the starting areas.
* seed - [[Types/uint32]]
:: Read by the game, but not used or set in the GUI.
* width - [[Types/uint32]]
:: Amount of tiles from left to right. Silently limited to 2,000,000, +/- 1 million tiles from the center.
* height - [[Types/uint32]]
:: Amount of tiles from top to bottom. Silently limited to 2,000,000, +/- 1 million tiles from the center.
* starting_area - [[Types/MapGenSize]]
:: Size of the starting area. The starting area only effects enemy placement, and has no effect on resources.
* peaceful_mode - [[Types/bool]]
* cliff_settings - [https://lua-api.factorio.com/latest/Concepts.html#CliffPlacementSettings CliffPlacementSettings]

=== advanced_settings ===
'''Type''': [[Types/table]]

This is a table with the below key/value pairs. All key/value pairs are optional, if not set they will just use the existing values.
* pollution - [[Types/table]]
:{| class="wikitable"
|-
! Property name !! Type !! Comment
|-
| enabled || [[Types/bool]]
|-
| diffusion_ratio || [[Types/double]] || Must be <= 0.25.
|-
| ageing || [[Types/double]] || Also known as dissipation rate. Must be >= 0.5.
|-
| enemy_attack_pollution_consumption_modifier || [[Types/double]]
|-
| min_pollution_to_damage_trees || [[Types/double]]
|-
| pollution_restored_per_tree_damage || [[Types/double]]
|-
|}
* enemy_evolution - [[Types/table]]
:{| class="wikitable"
|-
! Property name !! Type
|-
| enabled || [[Types/bool]]
|-
| time_factor || [[Types/double]]
|-
| destroy_factor || [[Types/double]]
|-
| pollution_factor || [[Types/double]]
|-
|}
* enemy_expansion - [[Types/table]]
:{| class="wikitable"
|-
! Property name !! Type !! Comment
|-
| enabled || [[Types/bool]]
|-
| max_expansion_distance || [[Types/double]]
|-
| settler_group_min_size || [[Types/double]]
|-
| settler_group_max_size || [[Types/double]]
|-
| min_expansion_cooldown || [[Types/double]] || In ticks.
|-
| max_expansion_cooldown || [[Types/double]] || In ticks.
|-
|}

* difficulty_settings - [[Types/table]]
:{| class="wikitable"
|-
! Property name !! Type !! Comment
|-
| recipe_difficulty || [https://lua-api.factorio.com/latest/defines.html#defines.difficulty_settings defines.difficulty_settings.recipe_difficulty]
|-
| technology_difficulty || [https://lua-api.factorio.com/latest/defines.html#defines.difficulty_settings defines.difficulty_settings.technology_difficulty]
|-
| technology_price_multiplier || [[Types/double]]
|-
| research_queue_setting || [[Types/string]] || Either "after-victory", "always" or "never".
|-
|}

Types/MapGenPreset

2023-08-15T23:51:35Z

Honktown: /* default */ when there is not any default

== Basics ==
A map gen preset. Used in [[Prototype/MapGenPresets]].

== Mandatory properties ==

=== order ===
'''Type''': [[Types/Order]]

Specifies the ordering in the [[map generator]] gui.

== Optional properties ==

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

'''Default''': true

Whether this is the default preset. If set to true, this preset may not have any other properties besides this and order.

If no MapGenPreset has <code>default = true</code>, the preset selector will have a blank preset label, having default settings, which goes away when another preset is selected.

=== basic_settings ===
'''Type''': [[Types/table]]

This is a table with the below key/value pairs. All key/value pairs are optional. If not set they will just use the default values.

* terrain_segmentation - [[Types/MapGenSize]]
:: This is the inverse of "water scale" in the map generator GUI. So a water scale that shows as 50% in the GUI is a value of <code>1/0.5 = 2</code> for <code>terrain_segmentation</code>.
* water - [[Types/MapGenSize]]
:: Shown as water coverage in the map generator GUI.
* default_enable_all_autoplace_controls - [[Types/bool]] - Default: true
:: Whether undefined autoplace_controls should fall back to the default controls or not.
* autoplace_controls - [[Types/table]]
:: Table of [[Data.raw#autoplace-control]] name keys mapped to table values. Each table can have the following fields:
::* frequency - [[Types/MapGenSize]]
::* size - [[Types/MapGenSize]]
::* richness - [[Types/MapGenSize]]
::Example:
::<syntaxhighlight lang="lua">autoplace_controls =
{
["iron-ore"] = { richness = 2, size = 0.5, frequency=2},
["enemy-base"] = { size = 1},
["trees"] = { richness = 4}
}</syntaxhighlight>
* autoplace_settings - [[Types/table]] of [https://lua-api.factorio.com/latest/Concepts.html#AutoplaceSettings AutoplaceSettings]
:: Each setting in this table maps the string type to the settings for that type. Valid types are "entity", "tile" and "decorative".
* property_expression_names - [[Types/table]]
:: Map of property name (e.g. "elevation") to name of [[Prototype/NamedNoiseExpression|noise expression]] that will provide it. Entries may be omitted. A notable usage is changing autoplace behavior of an entity based on the preset, which cannot be read from a noise expression.
* starting_points - [[Types/table]] of [[Types/Position]]
:: Array of the positions of the starting areas.
* seed - [[Types/uint32]]
:: Read by the game, but not used or set in the GUI.
* width - [[Types/uint32]]
:: Amount of tiles from left to right. Silently limited to 2,000,000, +/- 1 million tiles from the center.
* height - [[Types/uint32]]
:: Amount of tiles from top to bottom. Silently limited to 2,000,000, +/- 1 million tiles from the center.
* starting_area - [[Types/MapGenSize]]
:: Size of the starting area. The starting area only effects enemy placement, and has no effect on resources.
* peaceful_mode - [[Types/bool]]
* cliff_settings - [https://lua-api.factorio.com/latest/Concepts.html#CliffPlacementSettings CliffPlacementSettings]

=== advanced_settings ===
'''Type''': [[Types/table]]

This is a table with the below key/value pairs. All key/value pairs are optional, if not set they will just use the existing values.
* pollution - [[Types/table]]
:{| class="wikitable"
|-
! Property name !! Type !! Comment
|-
| enabled || [[Types/bool]]
|-
| diffusion_ratio || [[Types/double]] || Must be <= 0.25.
|-
| ageing || [[Types/double]] || Also known as dissipation rate. Must be >= 0.5.
|-
| enemy_attack_pollution_consumption_modifier || [[Types/double]]
|-
| min_pollution_to_damage_trees || [[Types/double]]
|-
| pollution_restored_per_tree_damage || [[Types/double]]
|-
|}
* enemy_evolution - [[Types/table]]
:{| class="wikitable"
|-
! Property name !! Type
|-
| enabled || [[Types/bool]]
|-
| time_factor || [[Types/double]]
|-
| destroy_factor || [[Types/double]]
|-
| pollution_factor || [[Types/double]]
|-
|}
* enemy_expansion - [[Types/table]]
:{| class="wikitable"
|-
! Property name !! Type !! Comment
|-
| enabled || [[Types/bool]]
|-
| max_expansion_distance || [[Types/double]]
|-
| settler_group_min_size || [[Types/double]]
|-
| settler_group_max_size || [[Types/double]]
|-
| min_expansion_cooldown || [[Types/double]] || In ticks.
|-
| max_expansion_cooldown || [[Types/double]] || In ticks.
|-
|}

* difficulty_settings - [[Types/table]]
:{| class="wikitable"
|-
! Property name !! Type !! Comment
|-
| recipe_difficulty || [https://lua-api.factorio.com/latest/defines.html#defines.difficulty_settings defines.difficulty_settings.recipe_difficulty]
|-
| technology_difficulty || [https://lua-api.factorio.com/latest/defines.html#defines.difficulty_settings defines.difficulty_settings.technology_difficulty]
|-
| technology_price_multiplier || [[Types/double]]
|-
| research_queue_setting || [[Types/string]] || Either "after-victory", "always" or "never".
|-
|}

Prototype/ResourceEntity

2023-05-20T17:03:30Z

Honktown: /* Optional properties */ description of randomize_visual_position

{{Prototype parent|Prototype/Entity}}
A mineable/gatherable entity. Its [[Types/CollisionMask|collision_mask]] must contain "resource-layer" if it should be minable with a [[Prototype/MiningDrill]].

{{Prototype TOC|resource}}

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

{{Prototype property|stages|[[Types/AnimationVariations|AnimationVariations]]}}
Entity's graphics, using a graphic sheet, with variation and depletion. At least one stage must be defined.

When using [[Types/AnimationVariations#sheet]], frame_count is the amount of frames per row in the spritesheet. variation_count is the amount of rows in the spritesheet. Each row in the spritesheet is one stage of the animation.

{{Prototype property|stage_counts|[[Types/table|table]] of [[Types/uint32|uint32]]}}
Number of stages the animation has.

== Optional properties ==

{{Prototype property|infinite|[[Types/bool|bool]]|false|optional=true}}
If the ore is infinitely minable, or if it will eventually run out of resource.

{{Prototype property|highlight|[[Types/bool|bool]]|false|optional=true}}
If the resource should be highlighted when holding a mining drill that can mine it (holding a pumpjack highlights crude-oil in the base game).

{{Prototype property|randomize_visual_position|[[Types/bool|bool]]|true|optional=true}}
If there is a slight offset to graphics of the resource. Used to make patches a little less uniform in appearance.

{{Prototype property|map_grid|[[Types/bool|bool]]|true|optional=true}}
Whether the resource should have a grid pattern on the map instead of a solid map color.

{{Prototype property|minimum|[[Types/uint32|uint32]]|0|optional=true}}
Must be not 0 when <code>infinite = true</code>.

{{Prototype property|normal|[[Types/uint32|uint32]]|1|optional=true}}
Must be not 0 when <code>infinite = true</code>.

{{Prototype property|infinite_depletion_amount|[[Types/uint32|uint32]]|1|optional=true}}
''Every time an infinite-type resource "ticks" lower it's lowered by that amount.'' -- [https://forums.factorio.com/viewtopic.php?t=47093&p=271243#p271115 Rseding91]

{{Prototype property|resource_patch_search_radius|[[Types/uint32|uint32]]|3|optional=true}}
When hovering over this resource in the map view: How far to search for other resource patches of this type to display as one (summing amount, white outline).

{{Prototype property|category|[[Types/string|string]]|"basic-solid"|optional=true}}
The category for the resource. Available categories in vanilla can be found here: [[Data.raw#resource-category]]

{{Prototype property|walking_sound|[[Types/Sound|Sound]]|optional=true}}
Sound played when the player walks over this resource.

{{Prototype property|stages_effect|[[Types/AnimationVariations|AnimationVariations]]|optional=true}}
An effect that can be overlayed above the normal ore graphics. Used in the base game to make [[uranium ore]] glow.

{{Prototype property|effect_animation_period|[[Types/float|float]]|0.0|optional=true}}
How long it takes <code>stages_effect</code> to go from <code>min_effect_alpha</code> to <code>max_effect_alpha</code>.

{{Prototype property|effect_animation_period_deviation|[[Types/float|float]]|0.0|optional=true}}
How much <code>effect_animation_period</code> can deviate from its original value. Used to make the stages effect alpha change look less uniform.

{{Prototype property|effect_darkness_multiplier|[[Types/float|float]]|1.0|optional=true}}
How much the surface darkness should affect the alpha of <code>stages_effect</code>.

{{Prototype property|min_effect_alpha|[[Types/float|float]]|0.0|optional=true}}
Minimal alpha value of <code>stages_effect</code>.

{{Prototype property|max_effect_alpha|[[Types/float|float]]|1.0|optional=true}}
Maximal alpha value of <code>stages_effect</code>.

{{Prototype property|tree_removal_probability|[[Types/double|double]]|0|optional=true}}
Must be positive.

{{Prototype property|tree_removal_max_distance|[[Types/double|double]]|0|optional=true}}
Must be positive when <code>tree_removal_probability</code> is set.

{{Prototype property|mining_visualisation_tint|[[Types/Color|Color]]|unset|optional=true}}
Defaults to the resources map color if left unset and map color is set, otherwise defaults to white if left unset.

== Example ==
<syntaxhighlight lang="lua">{
type = "resource",
name = "crude-oil",
icon = "__base__/graphics/icons/crude-oil.png",
icon_size = 32,
flags = {"placeable-neutral"},
category = "basic-fluid",
order="a-b-a",
infinite = true,
highlight = true,
minimum = 60000,
normal = 300000,
infinite_depletion_amount = 10,
resource_patch_search_radius = 12,
tree_removal_probability = 0.7,
tree_removal_max_distance = 32 * 32,
minable =
{
mining_time = 1,
results =
{
{
type = "fluid",
name = "crude-oil",
amount_min = 10,
amount_max = 10,
probability = 1
}
}
},
collision_box = {{ -1.4, -1.4}, {1.4, 1.4}},
selection_box = {{ -0.5, -0.5}, {0.5, 0.5}},
autoplace = resource_autoplace.resource_autoplace_settings{
name = "crude-oil",
order = "c", -- Other resources are "b"; oil won't get placed if something else is already there.
base_density = 8.2,
base_spots_per_km2 = 1.8,
random_probability = 1/48,
random_spot_size_minimum = 1,
random_spot_size_maximum = 1, -- don't randomize spot size
additional_richness = 220000, -- this increases the total everywhere, so base_density needs to be decreased to compensate
has_starting_area_placement = false,
resource_index = resource_autoplace.resource_indexes["crude-oil"],
regular_rq_factor_multiplier = 1
},
stage_counts = {0},
stages =
{
sheet =
{
filename = "__base__/graphics/entity/crude-oil/crude-oil.png",
priority = "extra-high",
width = 75,
height = 61,
frame_count = 4,
variation_count = 1
}
},
map_color = {r=0.78, g=0.2, b=0.77},
map_grid = false
}</syntaxhighlight>

Tutorial:Modding tutorial/Gangsir

2023-04-07T00:50:22Z

Honktown: /* The info.json file */ description phrasing

{{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</code>. When you're finished, the mod directory should look like this:

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

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

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

=== The info.json file ===

Then, inside [[Tutorial:Mod_structure#info.json|info.json]], copy and paste the following into it:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "fire-armor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"factorio_version": "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, which appears in game. The mod portal is better for a long description.
|}

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

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

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

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

2023-04-07T00:47:05Z

Honktown: /* The info.json file */ description "length" was nondescript

{{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</code>. When you're finished, the mod directory should look like this:

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

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

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

=== The info.json file ===

Then, inside [[Tutorial:Mod_structure#info.json|info.json]], copy and paste the following into it:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "fire-armor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"factorio_version": "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, which appears in game. A longer description is better kept to the mod portal.
|}

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

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

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

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

Prototype/Recipe

2023-04-06T09:02:59Z

Honktown: /* General properties */ reword icon(s)

{{Prototype parent|PrototypeBase}}
A recipe. It can be a crafting recipe, a smelting recipe, or a custom type of recipe (see [[Prototype/RecipeCategory]]).

{{Prototype TOC|recipe}}

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

{{Prototype property|category|[[Types/string|string]]|"crafting"|optional=true}}
Optional. Name of a [[Prototype/RecipeCategory]]. The category of the recipe is used to control which machines can craft the recipe. The built-in categories can be found [[Data.raw#recipe-category|here]].

The recipe category "crafting" cannot contain recipes with fluid ingredients or products.

{{Prototype property|subgroup|[[Types/string|string]]||optional=true}}
Optional. Name of a [[Prototype/ItemSubGroup]]. The subgroup of this recipe. If not specified, defaults to the subgroup of the product if there is only 1, or main_product if multiple products exist. If multiple products exist and no main_product is specified, or if there is no product, the subgroup is required.

{{Prototype property|icons, icon, icon_size (IconSpecification)|[[Types/IconSpecification|IconSpecification]]|optional=true}}
If given, this determines the recipe's icon. Mandatory for a recipe with more than 1 product and no main_product, or, no product.

Otherwise, the icon of main_product or the only product is used.

{{Prototype property|crafting_machine_tint|[[Types/table|table]] of [[Types/Color|Color]]|optional=true}}
Optional. Used by crafting machine <code>[[Prototype/CraftingMachine#working_visualisations|working_visualisations]]</code> to tint certain layers with the recipe color. [[Types/WorkingVisualisation#apply_recipe_tint|apply_recipe_tint]] on the working visualisation determines which of the 4 colors is used for that layer (if any).

Format:
<syntaxhighlight lang="lua">crafting_machine_tint = { primary = {r=0,g=0,b=0,a=0}, secondary = {r=0,g=0,b=0,a=0}, tertiary = {r=0,g=0,b=0,a=0}, quaternary = {r=0,g=0,b=0,a=0}}</syntaxhighlight>

Each key/value pair is optional and defaults to the above value.

== Recipe data ==
{{#subobject:normal
|Prototype property name=normal
|Prototype property type=[[Prototype/Recipe#Recipe_data|Recipe data]] or [[Types/bool|bool]]
|Prototype property optional=true
|Prototype property pagename={{FULLPAGENAME}}
}}{{#subobject:expensive
|Prototype property name=expensive
|Prototype property type=[[Prototype/Recipe#Recipe_data|Recipe data]] or [[Types/bool|bool]]
|Prototype property optional=true
|Prototype property pagename={{FULLPAGENAME}}
}}
If the recipe does not have a difficulty, this is located directly in the prototype. Otherwise, if the "'''normal'''" or "'''expensive'''" property exists, the recipe has difficulty. Then, the recipe data has to be specified for each difficulty instead of directly in the prototype. If at least one difficulty has recipe data defined, the other difficulty can be set to <code>false</code>. This will disable the recipe for the difficulty, same as setting it <code>enabled = false</code>. If it is enabled (by technologies etc), it will use the data from the other difficulty. Not setting a difficulty, e.g. <code>normal = nil</code>, is possible and gives that difficulty the exact same properties as the difficulty that is defined. Setting one or both difficulties to <code>true</code> is not valid and will produce an error. See below for examples of difficulty.

{{Prototype property|ingredients|[[Types/table|table]] of [[Types/IngredientPrototype|IngredientPrototype]]}}
A table containing ingredient names and counts. Can also contain information about fluid temperature and catalyst amounts. The catalyst amounts are automatically calculated from the recipe, or can be set manually in the [[Types/IngredientPrototype|IngredientPrototype]].[https://factorio.com/blog/post/fff-256] 
Maximum ingredient amount is 65535. 
<code>ingredients</code> can be set to an empty table to create a recipe that needs no ingredients. 
Duplicate ingredients, e.g. two entries for the "wood" item, are ''not'' allowed. 
In-game, the item ingredients are ordered by [[Prototype/ItemGroup#order_in_recipe|item group order_in_recipe]].
<syntaxhighlight lang="lua">
ingredients = {{"iron-stick", 2}, {"iron-plate", 3}}
</syntaxhighlight>
The same with full format:
<syntaxhighlight lang="lua">
ingredients = {{type = "item", name = "iron-stick", amount = 2}, {type = "item", name = "iron-plate", amount = 3}}
</syntaxhighlight>
For fluids, the full format always has to be used:
<syntaxhighlight lang="lua">
ingredients = {{type="fluid", name="water", amount=50}, {type="fluid", name="crude-oil", amount=100}}
</syntaxhighlight>

{{Prototype property|result|[[Types/string|string]]|optional=true}}
Can be replaced with the results parameter. The item created by this recipe. Must be the name of an item, such as "iron-gear-wheel".
Note that <code>results</code> takes priority over <code>result</code>. So if a recipe has both keys set, <code>result</code> will be ignored. 

{{Prototype property|result_count|[[Types/uint32|uint32]]|1|optional=true}}
Optional. The number of items created by this recipe.

{{Prototype property|results|[[Types/table|table]] of [[Types/ProductPrototype|ProductPrototype]]|optional=true}}
A table containing result names and counts. Can also contain information about fluid temperature and catalyst amounts. The catalyst amounts are automatically calculated from the recipe, or can be set manually in the [[Types/ProductPrototype|ProductPrototype]].[https://factorio.com/blog/post/fff-256] 
<code>results</code> can be set to an empty table to create a recipe that produces nothing. 
Duplicate results, e.g. two entries for the "iron-plate" item, are allowed.

<syntaxhighlight lang="lua">
results=
{
{type="fluid", name="heavy-oil", amount=3},
{type="fluid", name="light-oil", amount=3},
{type="fluid", name="petroleum-gas", amount=4}
},
</syntaxhighlight>
<syntaxhighlight lang="lua">
results =
{
{type = "item", name = "iron-nuggets", amount = 9},
{type = "item", name = "gold-nuggets", amount = 1}
},
</syntaxhighlight>
<syntaxhighlight lang="lua">
results =
{
{type = "fluid", name = "steam", amount = 1, temperature = 165}
},
</syntaxhighlight>

{{Prototype property|energy_required|[[Types/double|double]]|0.5|optional=true}}
Optional. The amount of time it takes to make this recipe. Must be greater than 0.001.

This is the number of seconds it takes to craft at crafting speed 1.

{{Prototype property|emissions_multiplier|[[Types/double|double]]|1.0|optional=true}}

{{Prototype property|requester_paste_multiplier|[[Types/uint32|uint32]]|30|optional=true}}

{{Prototype property|overload_multiplier|[[Types/uint32|uint32]]|0|optional=true}}
Used to determine how many extra items are put into an assembling machine before it's considered "full enough". See [[Inserters#Insertion_limits]].

If set to 0, it instead uses the following formula: 1.166 / (energy_required / the assembler's crafting_speed), rounded up, and clamped between 2 and 100. The numbers used in this formula can be changed by the [[Prototype/UtilityConstants]] dynamic_recipe_overload_factor, minimum_recipe_overload_multiplier and maximum_recipe_overload_multiplier.

{{Prototype property|allow_inserter_overload|[[Types/bool|bool]]|true|optional=true}}
If the recipe is allowed to have the extra inserter overload bonus applied (4 * stack inserter stack size).

{{Prototype property|enabled|[[Types/bool|bool]]|true|optional=true}}
Optional. This can be false to disable the recipe at the start of the game, or "true" to leave it enabled.

If your recipe is unlocked by a technology, you should set this to "false".

{{Prototype property|hidden|[[Types/bool|bool]]|false|optional=true}}
Optional. Hides the recipe from crafting menus.

{{Prototype property|hide_from_stats|[[Types/bool|bool]]|false|optional=true}}
Optional. Hides the recipe from flow stats (item/fluid production statistics).

{{Prototype property|hide_from_player_crafting|[[Types/bool|bool]]|false|optional=true}}
Optional. Hides the recipe from the player's crafting screen. The recipe will still show up for selection in machines.

{{Prototype property|allow_decomposition|[[Types/bool|bool]]|true|optional=true}}
Optional. Whether this recipe is allowed to be broken down for the recipe tooltip "Total raw" calculations.

{{Prototype property|allow_as_intermediate|[[Types/bool|bool]]|true|optional=true}}
Optional. Whether the recipe can be used as an intermediate recipe in hand-crafting.

{{Prototype property|allow_intermediates|[[Types/bool|bool]]|true|optional=true}}
Optional. Whether the recipe is allowed to use intermediate recipes when hand-crafting.

{{Prototype property|always_show_made_in|[[Types/bool|bool]]|false|optional=true}}
Optional. Whether the "Made in: {Machine}" part of the tool-tip should always be present, not only when the recipe can not be hand-crafted.

{{Prototype property|show_amount_in_title|[[Types/bool|bool]]|true|optional=true}}
Optional. Whether the recipe name should have the product amount in front of it, e.g. "2 [[transport belt]]"

{{Prototype property|always_show_products|[[Types/bool|bool]]|false|optional=true}}
Optional. Whether the products are always shown in the recipe tool-tip.

{{Prototype property|unlock_results|[[Types/bool|bool]]|true|optional=true}}
Optional. Whether enabling this recipe unlocks its item products to show in selection lists (item filter, logistic request etc.).

{{Prototype property|main_product|[[Types/string|string]]|optional=true}}
Optional.

For recipes with more than one product: The recipe takes that product's localised_name, localised_description, icon, and subgroup.

For recipes with one product (<code>results</code> with one product or <code>result</code>): The recipe uses the localised_name, localised_description, icon, and subgroup of the product.

If 1) there are multiple products and this property is nil, 2) this property is set to an empty string (<code>""</code>), or 3) there are no products, the recipe will use the localised_name, localised_description, icon, and subgroup of the recipe. icon and subgroup become non-optional.

== Examples ==

=== "iron-plate" ===
<syntaxhighlight lang="lua">
{
type = "recipe",
name = "iron-plate",
category = "smelting",
energy_required = 3.5,
ingredients = {{"iron-ore", 1}},
result = "iron-plate"
}</syntaxhighlight>

=== "coal-liquefaction" ===

<syntaxhighlight lang="lua">{
type = "recipe",
name = "coal-liquefaction",
category = "oil-processing",
subgroup = "fluid-recipes",
order = "a[oil-processing]-c[coal-liquefaction]",
enabled = false,
energy_required = 5,
icon = "__base__/graphics/icons/fluid/coal-liquefaction.png",
icon_size = 32,
ingredients =
{
{type="item", name="coal", amount=10},
{type="fluid", name="heavy-oil", amount=25},
{type="fluid", name="steam", amount=50}
},
results=
{
{type="fluid", name="heavy-oil", amount=35},
{type="fluid", name="light-oil", amount=15},
{type="fluid", name="petroleum-gas", amount=20}
},
allow_decomposition = false
}</syntaxhighlight>

=== "iron-gear-wheel" — recipe with difficulty ===
<syntaxhighlight lang="lua"> {
type = "recipe",
name = "iron-gear-wheel",
normal =
{
ingredients = {{"iron-plate", 2}},
result = "iron-gear-wheel"
},
expensive =
{
ingredients = {{"iron-plate", 4}},
result = "iron-gear-wheel"
}
},</syntaxhighlight>

==== Modified so that it cannot be crafted in normal mode, unless unlocked via command/research ====
<syntaxhighlight lang="lua"> {
type = "recipe",
name = "iron-gear-wheel",
normal = false,
expensive =
{
ingredients = {{"iron-plate", 4}},
result = "iron-gear-wheel"
}
},</syntaxhighlight>

==== Modified so that the expensive recipe is always used, even in normal mode ====
<syntaxhighlight lang="lua"> {
type = "recipe",
name = "iron-gear-wheel",
normal = nil, --this line can be omitted
expensive =
{
ingredients = {{"iron-plate", 4}},
result = "iron-gear-wheel"
}
},</syntaxhighlight>

Prototype/Recipe

2023-04-06T08:55:23Z

Honktown: /* Recipe data */ re-describe main_product for clearer logic and more cases

{{Prototype parent|PrototypeBase}}
A recipe. It can be a crafting recipe, a smelting recipe, or a custom type of recipe (see [[Prototype/RecipeCategory]]).

{{Prototype TOC|recipe}}

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

{{Prototype property|category|[[Types/string|string]]|"crafting"|optional=true}}
Optional. Name of a [[Prototype/RecipeCategory]]. The category of the recipe is used to control which machines can craft the recipe. The built-in categories can be found [[Data.raw#recipe-category|here]].

The recipe category "crafting" cannot contain recipes with fluid ingredients or products.

{{Prototype property|subgroup|[[Types/string|string]]||optional=true}}
Optional. Name of a [[Prototype/ItemSubGroup]]. The subgroup of this recipe. If not specified, defaults to the subgroup of the product if there is only 1, or main_product if multiple products exist. If multiple products exist and no main_product is specified, the subgroup is required.

{{Prototype property|icons, icon, icon_size (IconSpecification)|[[Types/IconSpecification|IconSpecification]]|optional=true}}
An icon is mandatory for recipe with more than 1 product and no main_product. Otherwise defaults to the icon of main_product/1 product.

If given, it overwrites the icon of the main_product/1 product.

{{Prototype property|crafting_machine_tint|[[Types/table|table]] of [[Types/Color|Color]]|optional=true}}
Optional. Used by crafting machine <code>[[Prototype/CraftingMachine#working_visualisations|working_visualisations]]</code> to tint certain layers with the recipe color. [[Types/WorkingVisualisation#apply_recipe_tint|apply_recipe_tint]] on the working visualisation determines which of the 4 colors is used for that layer (if any).

Format:
<syntaxhighlight lang="lua">crafting_machine_tint = { primary = {r=0,g=0,b=0,a=0}, secondary = {r=0,g=0,b=0,a=0}, tertiary = {r=0,g=0,b=0,a=0}, quaternary = {r=0,g=0,b=0,a=0}}</syntaxhighlight>

Each key/value pair is optional and defaults to the above value.

== Recipe data ==
{{#subobject:normal
|Prototype property name=normal
|Prototype property type=[[Prototype/Recipe#Recipe_data|Recipe data]] or [[Types/bool|bool]]
|Prototype property optional=true
|Prototype property pagename={{FULLPAGENAME}}
}}{{#subobject:expensive
|Prototype property name=expensive
|Prototype property type=[[Prototype/Recipe#Recipe_data|Recipe data]] or [[Types/bool|bool]]
|Prototype property optional=true
|Prototype property pagename={{FULLPAGENAME}}
}}
If the recipe does not have a difficulty, this is located directly in the prototype. Otherwise, if the "'''normal'''" or "'''expensive'''" property exists, the recipe has difficulty. Then, the recipe data has to be specified for each difficulty instead of directly in the prototype. If at least one difficulty has recipe data defined, the other difficulty can be set to <code>false</code>. This will disable the recipe for the difficulty, same as setting it <code>enabled = false</code>. If it is enabled (by technologies etc), it will use the data from the other difficulty. Not setting a difficulty, e.g. <code>normal = nil</code>, is possible and gives that difficulty the exact same properties as the difficulty that is defined. Setting one or both difficulties to <code>true</code> is not valid and will produce an error. See below for examples of difficulty.

{{Prototype property|ingredients|[[Types/table|table]] of [[Types/IngredientPrototype|IngredientPrototype]]}}
A table containing ingredient names and counts. Can also contain information about fluid temperature and catalyst amounts. The catalyst amounts are automatically calculated from the recipe, or can be set manually in the [[Types/IngredientPrototype|IngredientPrototype]].[https://factorio.com/blog/post/fff-256] 
Maximum ingredient amount is 65535. 
<code>ingredients</code> can be set to an empty table to create a recipe that needs no ingredients. 
Duplicate ingredients, e.g. two entries for the "wood" item, are ''not'' allowed. 
In-game, the item ingredients are ordered by [[Prototype/ItemGroup#order_in_recipe|item group order_in_recipe]].
<syntaxhighlight lang="lua">
ingredients = {{"iron-stick", 2}, {"iron-plate", 3}}
</syntaxhighlight>
The same with full format:
<syntaxhighlight lang="lua">
ingredients = {{type = "item", name = "iron-stick", amount = 2}, {type = "item", name = "iron-plate", amount = 3}}
</syntaxhighlight>
For fluids, the full format always has to be used:
<syntaxhighlight lang="lua">
ingredients = {{type="fluid", name="water", amount=50}, {type="fluid", name="crude-oil", amount=100}}
</syntaxhighlight>

{{Prototype property|result|[[Types/string|string]]|optional=true}}
Can be replaced with the results parameter. The item created by this recipe. Must be the name of an item, such as "iron-gear-wheel".
Note that <code>results</code> takes priority over <code>result</code>. So if a recipe has both keys set, <code>result</code> will be ignored. 

{{Prototype property|result_count|[[Types/uint32|uint32]]|1|optional=true}}
Optional. The number of items created by this recipe.

{{Prototype property|results|[[Types/table|table]] of [[Types/ProductPrototype|ProductPrototype]]|optional=true}}
A table containing result names and counts. Can also contain information about fluid temperature and catalyst amounts. The catalyst amounts are automatically calculated from the recipe, or can be set manually in the [[Types/ProductPrototype|ProductPrototype]].[https://factorio.com/blog/post/fff-256] 
<code>results</code> can be set to an empty table to create a recipe that produces nothing. 
Duplicate results, e.g. two entries for the "iron-plate" item, are allowed.

<syntaxhighlight lang="lua">
results=
{
{type="fluid", name="heavy-oil", amount=3},
{type="fluid", name="light-oil", amount=3},
{type="fluid", name="petroleum-gas", amount=4}
},
</syntaxhighlight>
<syntaxhighlight lang="lua">
results =
{
{type = "item", name = "iron-nuggets", amount = 9},
{type = "item", name = "gold-nuggets", amount = 1}
},
</syntaxhighlight>
<syntaxhighlight lang="lua">
results =
{
{type = "fluid", name = "steam", amount = 1, temperature = 165}
},
</syntaxhighlight>

{{Prototype property|energy_required|[[Types/double|double]]|0.5|optional=true}}
Optional. The amount of time it takes to make this recipe. Must be greater than 0.001.

This is the number of seconds it takes to craft at crafting speed 1.

{{Prototype property|emissions_multiplier|[[Types/double|double]]|1.0|optional=true}}

{{Prototype property|requester_paste_multiplier|[[Types/uint32|uint32]]|30|optional=true}}

{{Prototype property|overload_multiplier|[[Types/uint32|uint32]]|0|optional=true}}
Used to determine how many extra items are put into an assembling machine before it's considered "full enough". See [[Inserters#Insertion_limits]].

If set to 0, it instead uses the following formula: 1.166 / (energy_required / the assembler's crafting_speed), rounded up, and clamped between 2 and 100. The numbers used in this formula can be changed by the [[Prototype/UtilityConstants]] dynamic_recipe_overload_factor, minimum_recipe_overload_multiplier and maximum_recipe_overload_multiplier.

{{Prototype property|allow_inserter_overload|[[Types/bool|bool]]|true|optional=true}}
If the recipe is allowed to have the extra inserter overload bonus applied (4 * stack inserter stack size).

{{Prototype property|enabled|[[Types/bool|bool]]|true|optional=true}}
Optional. This can be false to disable the recipe at the start of the game, or "true" to leave it enabled.

If your recipe is unlocked by a technology, you should set this to "false".

{{Prototype property|hidden|[[Types/bool|bool]]|false|optional=true}}
Optional. Hides the recipe from crafting menus.

{{Prototype property|hide_from_stats|[[Types/bool|bool]]|false|optional=true}}
Optional. Hides the recipe from flow stats (item/fluid production statistics).

{{Prototype property|hide_from_player_crafting|[[Types/bool|bool]]|false|optional=true}}
Optional. Hides the recipe from the player's crafting screen. The recipe will still show up for selection in machines.

{{Prototype property|allow_decomposition|[[Types/bool|bool]]|true|optional=true}}
Optional. Whether this recipe is allowed to be broken down for the recipe tooltip "Total raw" calculations.

{{Prototype property|allow_as_intermediate|[[Types/bool|bool]]|true|optional=true}}
Optional. Whether the recipe can be used as an intermediate recipe in hand-crafting.

{{Prototype property|allow_intermediates|[[Types/bool|bool]]|true|optional=true}}
Optional. Whether the recipe is allowed to use intermediate recipes when hand-crafting.

{{Prototype property|always_show_made_in|[[Types/bool|bool]]|false|optional=true}}
Optional. Whether the "Made in: {Machine}" part of the tool-tip should always be present, not only when the recipe can not be hand-crafted.

{{Prototype property|show_amount_in_title|[[Types/bool|bool]]|true|optional=true}}
Optional. Whether the recipe name should have the product amount in front of it, e.g. "2 [[transport belt]]"

{{Prototype property|always_show_products|[[Types/bool|bool]]|false|optional=true}}
Optional. Whether the products are always shown in the recipe tool-tip.

{{Prototype property|unlock_results|[[Types/bool|bool]]|true|optional=true}}
Optional. Whether enabling this recipe unlocks its item products to show in selection lists (item filter, logistic request etc.).

{{Prototype property|main_product|[[Types/string|string]]|optional=true}}
Optional.

For recipes with more than one product: The recipe takes that product's localised_name, localised_description, icon, and subgroup.

For recipes with one product (<code>results</code> with one product or <code>result</code>): The recipe uses the localised_name, localised_description, icon, and subgroup of the product.

If 1) there are multiple products and this property is nil, 2) this property is set to an empty string (<code>""</code>), or 3) there are no products, the recipe will use the localised_name, localised_description, icon, and subgroup of the recipe. icon and subgroup become non-optional.

== Examples ==

=== "iron-plate" ===
<syntaxhighlight lang="lua">
{
type = "recipe",
name = "iron-plate",
category = "smelting",
energy_required = 3.5,
ingredients = {{"iron-ore", 1}},
result = "iron-plate"
}</syntaxhighlight>

=== "coal-liquefaction" ===

<syntaxhighlight lang="lua">{
type = "recipe",
name = "coal-liquefaction",
category = "oil-processing",
subgroup = "fluid-recipes",
order = "a[oil-processing]-c[coal-liquefaction]",
enabled = false,
energy_required = 5,
icon = "__base__/graphics/icons/fluid/coal-liquefaction.png",
icon_size = 32,
ingredients =
{
{type="item", name="coal", amount=10},
{type="fluid", name="heavy-oil", amount=25},
{type="fluid", name="steam", amount=50}
},
results=
{
{type="fluid", name="heavy-oil", amount=35},
{type="fluid", name="light-oil", amount=15},
{type="fluid", name="petroleum-gas", amount=20}
},
allow_decomposition = false
}</syntaxhighlight>

=== "iron-gear-wheel" — recipe with difficulty ===
<syntaxhighlight lang="lua"> {
type = "recipe",
name = "iron-gear-wheel",
normal =
{
ingredients = {{"iron-plate", 2}},
result = "iron-gear-wheel"
},
expensive =
{
ingredients = {{"iron-plate", 4}},
result = "iron-gear-wheel"
}
},</syntaxhighlight>

==== Modified so that it cannot be crafted in normal mode, unless unlocked via command/research ====
<syntaxhighlight lang="lua"> {
type = "recipe",
name = "iron-gear-wheel",
normal = false,
expensive =
{
ingredients = {{"iron-plate", 4}},
result = "iron-gear-wheel"
}
},</syntaxhighlight>

==== Modified so that the expensive recipe is always used, even in normal mode ====
<syntaxhighlight lang="lua"> {
type = "recipe",
name = "iron-gear-wheel",
normal = nil, --this line can be omitted
expensive =
{
ingredients = {{"iron-plate", 4}},
result = "iron-gear-wheel"
}
},</syntaxhighlight>

Prototype/BlueprintBook

2023-03-25T01:19:43Z

Honktown: /* Mandatory values */ better dynamic description?

{{Prototype parent|Prototype/ItemWithInventory}}
A [[blueprint book]].

{{Prototype TOC|blueprint-book|no-properties=true}}

== Mandatory values ==
Blueprint books must have a stack size of 1.

{{Prototype property|inventory_size|[[Types/ItemStackIndex|ItemStackIndex]] or [[Types/string|string]]}}
The inventory size of the item. The only accepted string is "dynamic". If "dynamic", the size of the LuaInventory object is the last occupied blueprint / book slot.

Prototype/BlueprintBook

2023-03-25T01:17:58Z

Honktown: /* Mandatory values */ "dynamic" inventory size

{{Prototype parent|Prototype/ItemWithInventory}}
A [[blueprint book]].

{{Prototype TOC|blueprint-book|no-properties=true}}

== Mandatory values ==
Blueprint books must have a stack size of 1.

{{Prototype property|inventory_size|[[Types/ItemStackIndex|ItemStackIndex]] or [[Types/string|"dynamic"]]}}
The inventory size of the item. If "dynamic", the size of the LuaInventory object is the last occupied blueprint / book slot.

Prototype/CraftingMachine

2023-03-22T20:18:25Z

Honktown: /* Optional properties */ idle animation grammar, split sentence

{{Prototype parent|Prototype/EntityWithOwner}}
The abstract basis of the assembling machines and furnaces. Contains the properties that both of them have.

Note that a crafting machine cannot be rotated unless it has at least one of the following: a fluid box, a heat energy source, a fluid energy source, or a non-square collision box. Crafting machines with non-square collision boxes can only be rotated before placement, not after.

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

== Extensions ==

* [[Prototype/AssemblingMachine]] '''assembling-machine'''
** [[Prototype/RocketSilo]] '''rocket-silo'''
* [[Prototype/Furnace]] '''furnace'''

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

{{Prototype property|energy_usage|[[Types/Energy|Energy]]}}
Sets how much energy this machine uses while crafting. Energy usage has to be positive.

{{Prototype property|crafting_speed|[[Types/double|double]]}}
How fast this crafting machine can craft. 1 means that for example a 1 second long recipe take 1 second to craft. 0.5 means it takes 2 seconds, and 2 means it takes 0.5 seconds.

Crafting speed has to be positive.

{{Prototype property|crafting_categories|[[Types/table|table]] of [[Types/string|string]]s}}
A list of [[Prototype/RecipeCategory|recipe categories]] this crafting machine can use.

Example:
<pre>
crafting_categories = {"crafting", "smelting"}
</pre>

{{Prototype property|energy_source|[[Types/EnergySource|EnergySource]]}}
Defines how the crafting machine is powered.

When using an electric energy source and <code>drain</code> is not specified, it will be set to <code>energy_usage ÷ 30</code> automatically.

== Optional properties ==

{{Prototype property|fluid_boxes|[[Types/table|table]] of [[Types/FluidBox|FluidBox]]|optional=true}}
Can have off_when_no_fluid_recipe key that has a [[Types/bool|bool]] value. off_when_no_fluid_recipe defaults to false. off_when_no_fluid_recipe is ignored by [[Prototype/Furnace]]s and considered to always be false.

If a crafting machine has fluid boxes ''and'' off_when_no_fluid_recipe is true, the crafting machine can only be rotated when a recipe consuming or producing fluid is set, or it has one of the other properties listed at the top of the page.

<syntaxhighlight lang="lua">fluid_boxes =
{
{
production_type = "input",
pipe_picture = assembler2pipepictures(),
pipe_covers = pipecoverspictures(),
base_area = 10,
base_level = -1,
pipe_connections = {{ type="input", position = {0, -2} }},
secondary_draw_orders = { north = -1 }
},
{
production_type = "output",
pipe_picture = assembler2pipepictures(),
pipe_covers = pipecoverspictures(),
base_area = 10,
base_level = 1,
pipe_connections = {{ type="output", position = {0, 2} }},
secondary_draw_orders = { north = -1 }
},
off_when_no_fluid_recipe = true
},</syntaxhighlight>

{{Prototype property|allowed_effects|[[Types/EffectTypeLimitation|EffectTypeLimitation]]|No effects are allowed|optional=true}}
Sets the module effects that are allowed to be used on this machine.

Note: If the time to complete a recipe is shorter than one tick, only one craft can be completed per tick, but productivity bonus is applied to the non-limited ''completable'' work. For a simple example, if a recipe were to take half a tick, only one recipe would be completed, but twice the productivity bonus would occur. The surplus production from productivity is '''not''' limited to one craft per tick.

{{Prototype property|scale_entity_info_icon|[[Types/bool|bool]]|false|optional=true}}
Whether the "alt-mode icon" should be scaled to the size of the machine.

{{Prototype property|show_recipe_icon|[[Types/bool|bool]]|true|optional=true}}
Whether the "alt-mode icon" should be drawn at all.

{{Prototype property|return_ingredients_on_change|[[Types/bool|bool]]|true|optional=true}}
Controls whether the ingredients of an in-progress recipe are destroyed when mining the machine/changing the recipe. If set to true, the ingredients do not get destroyed. This affects only the ingredients of the recipe that is currently in progress, so those that visually have already been consumed while their resulting product has not yet been produced.

{{Prototype property|animation|[[Types/Animation4Way|Animation4Way]]|optional=true}}
The animation played when crafting. When the crafting machine is idle, the animation will be paused.

When a crafting machine cannot be rotated, only the north rotation of the animation will be used.

The <code>animation_speed</code> of the animation is divided by 2 by the game. For example, the default animation speed of 1 means one animation frame per 2 ticks (30 fps) instead of the usual 60 fps.

{{Prototype property|idle_animation|[[Types/Animation4Way|Animation4Way]]|optional=true}}
Idle animation must have the same frame count as animation. It is used for drawing the machine in the idle state. The animation is frozen on a single frame when the machine is idle. 
This is an animation and not just sprite to make it possible for idle state and working state to match their visuals when the machine switches from one state to another.

When a crafting machine cannot be rotated, only the north rotation of the idle animation will be used.

The <code>animation_speed</code> of the animation is divided by 2 by the game. For example, the default animation speed of 1 means one animation frame per 2 ticks (30 fps) instead of the usual 60 fps.

{{Prototype property|always_draw_idle_animation|[[Types/bool|bool]]|false|optional=true}}
Only loaded if <code>idle_animation</code> is present.

{{Prototype property|default_recipe_tint|[[Types/table|table]] of [[Types/Color|Color]]|optional=true}}
Format:
<syntaxhighlight lang="lua">default_recipe_tint = { primary = {r=1,g=1,b=1,a=1}, secondary = {r=1,g=1,b=1,a=1}, tertiary = {r=1,g=1,b=1,a=1}, quaternary = {r=1,g=1,b=1,a=1}}</syntaxhighlight>
Each key/value pair is optional and defaults to the above value.

{{Prototype property|shift_animation_waypoints|[[Types/table|table]] of [[Types/table|table]] (array) of [[Types/vector|vector]]|optional=true}}
Table with the following optional key/value pairs:
* north - [[Types/table|array]] of [[Types/vector|vector]]
* east - [[Types/table|array]] of [[Types/vector|vector]]
* south - [[Types/table|array]] of [[Types/vector|vector]]
* west - [[Types/table|array]] of [[Types/vector|vector]]

Only loaded if one of <code>shift_animation_waypoint_stop_duration</code> or <code>shift_animation_transition_duration</code> is not 0.

{{Prototype property|shift_animation_waypoint_stop_duration|[[Types/uint16|uint16]]|0|optional=true}}
Only loaded if <code>shift_animation_waypoints</code> is present.

{{Prototype property|shift_animation_transition_duration |[[Types/uint16|uint16]]|0|optional=true}}
Only loaded if <code>shift_animation_waypoints</code> is present.

{{Prototype property|status_colors|[[Types/table|table]] of [[Types/Color|Color]]|optional=true}}
Table with the following optional key/value pairs:
* idle - [[Types/Color|Color]] - Default: White
* no_minable_resources - [[Types/Color|Color]] - Default: <code>idle</code>
* full_output - [[Types/Color|Color]] - Default: <code>idle</code>
* insufficient_input - [[Types/Color|Color]] - Default: <code>idle</code>
* disabled - [[Types/Color|Color]] - Default: <code>idle</code>
* no_power - [[Types/Color|Color]] - Default: No color
* working - [[Types/Color|Color]] - Default: White
* low_power - [[Types/Color|Color]] - Default: <code>working</code>

Used by [[Types/WorkingVisualisation#apply_tint]].

{{Prototype property|entity_info_icon_shift|[[Types/vector|vector]]|<nowiki>{0, -0.3}</nowiki> for [[Prototype/AssemblingMachine]] and <nowiki>{0, -0.1}</nowiki> for [[Prototype/Furnace]]|optional=true}}
Shift of the "alt-mode icon" relative to the machine's center.

{{Prototype property|draw_entity_info_icon_background|[[Types/bool|bool]]|true|optional=true}}
Whether the "alt-mode icon" should have a black background.

{{Prototype property|match_animation_speed_to_activity|[[Types/bool|bool]]|true|optional=true}}
Whether the speed of the animation and working visualization should be based on the machine's speed (boosted or slowed by modules).

{{Prototype property|show_recipe_icon_on_map|[[Types/bool|bool]]|true|optional=true}}
Whether the recipe icon should be shown on the map.

{{Prototype property|base_productivity|[[Types/float|float]]|0|optional=true}}
Productivity bonus that this machine always has.

{{Prototype property|module_specification|[[Types/ModuleSpecification|ModuleSpecification]]|optional=true}}
The number of module slots in this machine, and their icon positions.

<syntaxhighlight lang="lua">module_specification = {
module_info_icon_shift = {
0,
0.8
},
module_slots = 2
},</syntaxhighlight>

{{Prototype property|working_visualisations|[[Types/table|table]] of [[Types/WorkingVisualisation|WorkingVisualisation]]|optional=true}}
Used to display different animations when the machine is running, for example tinted based on the current recipe.

The <code>animation_speed</code> of the animations is divided by 2 by the game. For example, the default animation speed of 1 means one animation frame per 2 ticks (30 fps) instead of the usual 60 fps.

Types/ItemProductPrototype

2023-03-11T01:59:06Z

Honktown: /* probability */ the case of amount and no min or max

__NOTOC__An item product definition, for example for a [[Prototype/Recipe]]. Its loading is triggered by the <code>type</code> of a [[Types/ProductPrototype]] being "item". It can be specified as a table with named or numbered keys, but not a mix of both.

== Mandatory properties ==

=== name or 1 ===
'''Type''': [[Types/string]]

The name of a [[Prototype/Item]].

== Optional properties ==

=== amount or 2 ===
'''Type''': [[Types/uint16]]

Mandatory when using numbered keys (an array). 
If <code>amount</code> is present, <code>amount_min</code> and <code>amount_max</code> are not loaded.

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

'''Default''': 1

Value between 0 and 1, 0 for 0% chance and 1 for 100% chance.

The effect of probability is no product, or, a linear distribution on [min, max]. For a recipe with probability p, amount_min min, and amount_max max, the Expected Value of this '''product''' can be expressed as <code>p * (0.5 * (max + min))</code>. This is what will be shown in a recipe tooltip. The effect of <code>catalyst_amount</code> on the product is not shown.

When amount_min and amount_max are not provided, <code>amount</code> applies as min and max. The Expected Value simplifies to <code>p*amount</code>, providing 0 product, or, <code>amount</code> product, on recipe completion.

=== amount_min ===
'''Type''': [[Types/uint16]]

Mandatory if <code>amount</code> is not specified and named keys are being used.

=== amount_max ===
'''Type''': [[Types/uint16]]

Mandatory if <code>amount</code> is not specified and named keys are being used.

If set to a number that is less than <code>amount_min</code>, the game will use <code>amount_min</code> internally.

=== catalyst_amount ===
'''Type''': [[Types/uint16]]

'''Default''': 0

Amount that should not be affected by productivity modules (not yielded from bonus production) and should not be included in the item production statistics.

If this ItemProductPrototype is used in a recipe, the catalyst amount is calculated automatically based on the [[Prototype/Recipe#ingredients|ingredients]] and [[Prototype/Recipe#results|results]].[https://factorio.com/blog/post/fff-256]

== See also ==
* [[Types/ProductPrototype]]
* [[Types/FluidProductPrototype]]

Tutorial:Mod settings

2023-03-06T20:41:34Z

Honktown: /* color-setting */ a setting exists in data, removed reference to control

{{Languages}}
This tutorial aims to explain how to create and use mod settings. Basic knowledge of modding is assumed, so you should have at least understood [[Tutorial:Modding tutorial/Gangsir|Gangsir's modding tutorial]].

== Overview ==
Each mod can specify settings that users can change. The values of these settings can be accessed from inside the data stage or the control stage depending on their [[#The_setting_type_property|setting_type]] and allow to conditionally create or modify prototypes and to add configuration options to control scripts. They allow modders to easily create a graphical interface for their configuration options, instead of using on text files that have to be edited manually by users.

== Location ==

Mod settings are defined in the [https://lua-api.factorio.com/latest/Data-Lifecycle.html settings stage]. This stage is loaded before the data stage. There are three files in which settings can be defined:
* settings.lua
* settings-updates.lua
* settings-final-fixes.lua

First the settings.lua file is called for each mod, in the order of their dependencies and then in the [[:Wikipedia:natural sort order|natural sort order]]. After settings.lua has been called for all mods, the settings-updates.lua file is called for each mod (in the same order) and finally the settings-final-fixes.lua file is called for each mod (in the same order). These 3 different phases of the settings stage allow to change settings of other mods without needing to rely on dependencies to load last. The settings are all defined in the same stage and their user defined values are not available, therefore mods cannot conditionally create settings depending on the values of other mod settings. Since the settings stage gets loaded first, there is also no prototype data or [http://lua-api.factorio.com/latest/LuaRemote.html remote interface] available.

The "mod-settings.dat" file stored in the [[Application_directory#User_Data_directory|mods folder]] for the game contains the local players settings between game sessions similar to the player-data.json file.

== Creation ==

Mod settings are defined and modified by using the data table during the settings stage. This works [[Tutorial:Modding_tutorial/Gangsir#Prototype_creation|the same way as other prototypes]]. An example would be:
<syntaxhighlight lang="lua">
data:extend({
{
type = "bool-setting",
name = "my-mod-test-setting",
setting_type = "runtime-global",
default_value = true
}
})
</syntaxhighlight>

As you can see, the setting has multiple properties. Each setting supports the following standard prototype properties:
* name - [[Types/string|string]] - Mandatory.
* type - [[Types/string|string]] - Mandatory.
* localised_name - [[Types/LocalisedString|LocalisedString]] - Optional.
* localised_description - [[Types/LocalisedString|LocalisedString]] - Optional.
* [[Types/Order|order]] - [[Types/string|string]] - Optional.

In addition to the standard properties, mod settings also contain:

* hidden - [[Types/bool|bool]] - Optional.
* setting_type - [[Types/string|string]] - Mandatory.

=== The name property ===

The name of the settings prototype should be unique to avoid mod conflicts since the mod settings are global across all mods. Because of that it is recommened to prefix mod settings with your mod name, "my-mod" in this example.

=== The type property ===

There are four types of mod settings:

* bool-setting - a true/false checkbox
* int-setting - a signed 64 bit integer textfield (or selection dropdown)
* double-setting - a double precision floating point textfield (or selection dropdown)
* string-setting - a string textfield (or selection dropdown)
* color-setting - a color picker (sliders), with whole number textfields. Includes alpha.

Depending on the type, the prototype also allows or requires additional properties, these are listed below.

==== bool-setting ====
* default_value - [[Types/bool|bool]] - Mandatory.
** Defines the default value of the setting, in this case whether the checkbox is checked or not.
* forced_value - [[Types/bool|bool]] - Optional.
** Only loaded if <code>hidden = true</code>. This forces the setting to be of this value. This can be useful for mod compatiblity.[https://forums.factorio.com/viewtopic.php?p=531322#p531322]


==== int-setting ====
* default_value - [[Types/int64|int64]] - Mandatory.
** Defines the default value of the setting.
* minimum_value - [[Types/int64|int64]] - Optional.
** Defines the lowest possible number.
* maximum_value - [[Types/int64|int64]] - Optional.
** Defines the highest possible number.
* allowed_values - [[Types/table|array]] of [[Types/int64|int64]] - Optional.
** Makes it possible to force the player to choose between the defined numbers, creates a dropdown instead of a texfield.
** If only one allowed value is given, the settings is forced to be of that value.

==== double-setting ====
* default_value - [[Types/double|double]] - Mandatory.
** Defines the default value of the setting.
* minimum_value - [[Types/double|double]] - Optional.
** Defines the lowest possible number.
* maximum_value - [[Types/double|double]] - Optional.
** Defines the highest possible number.
* allowed_values - [[Types/table|array]] of [[Types/double|double]] - Optional.
** Makes it possible to force the player to choose between the defined numbers, creates a dropdown instead of a textfield.
** If only one allowed value is given, the settings is forced to be of that value.

==== string-setting ====
* default_value - [[Types/string|string]] - Mandatory.
** Defines the default value of the setting.
* allow_blank - [[Types/bool|bool]] - Optional. - Default: false
** Defines whether it's possible for the user to set the textfield to empty and apply the setting.
* auto_trim - [[Types/bool|bool]] - Optional. - Default: false
** Whether values that are input by the user should have whitespace removed from both ends of the string.
* allowed_values - [[Types/table|array]] of [[Types/string|string]] - Optional.
** Makes it possible to force the player to choose between the defined strings, creates a dropdown instead of a textfield. The strings in the dropdown can be localized (translated) and can have a tooltip, see below.
** If only one allowed value is given, the settings is forced to be of that value.

==== color-setting ====
* default_value = [[Types/Color|color]] - Mandatory.
** Default color to set. When read, the color has 'r', 'g', 'b', 'a' keys and values [0, 1]

=== The order property ===

The order property can be used to change how the mod settings are ordered in the settings gui. Mod settings are sorted
* first by mod
* then by the setting "order" string
* then finally by the setting name.

For more info on how to use the order string, see [[Types/Order]].

=== The hidden property ===

The hidden property can be used to hide mod settings from GUIs, so that they cannot be seen or changed by players. However, other mods can still access hidden settings.[https://forums.factorio.com/83316]

=== The setting_type property ===
[[File:Mod_settings_gui.png|right|300px|thumb|The mod settings gui. Can be reached from the main menu → Settings → Mod settings.]]
There are the overall kinds of settings:

* '''startup''': This kind of setting is available in the prototype stage, and can not be changed runtime. They have to be set to the same values for all players on a server.
* '''runtime-global''': This kind of setting is global to an entire save game and can be changed runtime. On servers, only admins can change these settings.
* '''runtime-per-user''': This kind of setting is only available runtime in the control.lua stage and each player has their own instance of this setting. When a player joins a server their local setting of "keep mod settings per save" determines if the local settings they have set are synced to the loaded save or if the save's settings are used.

This "setting_type" also determines in which tab the setting is showed in the mod settings menu.

=== Locale ===
The locale for mod settings works like any other locale in the game. The names of the groups for the setting name and description (tooltip) are "mod-setting-name" and "mod-setting-description". The dropdown items of a string setting can be localized in the "string-mod-setting" group, but the game falls back to just showing the name of the dropdown item if no localization is found. An example for mod setting localization that would be set within "locale/en/locale.cfg", is:
<pre>
[mod-setting-name]
my-mod-test-setting=Localized test setting name

[mod-setting-description]
my-mod-test-setting=Localized test setting description

[string-mod-setting]
#<setting-name>-<dropdown-item-name>=<translated dropdown item>
my-mod-string-test-setting-item-1=Item 1 localized string

[string-mod-setting-description]
#<setting-name>-<dropdown-item-name>=<tooltip of dropdown item>
my-mod-string-test-setting-item-1=Item 1 localized tooltip

</pre>

== Usage ==
=== Reading settings ===
When accessing any mod setting, you will have to specifically access the ''value'' of the setting. The data type of the value depends on the type of the setting. For string settings that use a selection of allowed values, the value of the setting is one of the original string values defined in the prototype, the localization is ignored. See also: [http://lua-api.factorio.com/latest/Concepts.html#ModSetting ModSetting concept].

In the prototype stage you can access settings of the setting_type "startup" by indexing <code>settings.startup</code> with the name of the setting. Example:
<syntaxhighlight lang="lua">
--in settings.lua:
data:extend({
{
type = "int-setting",
name = "my-mod-stone-wall-stack-size",
setting_type = "startup",
minimum_value = 1,
default_value = 100
}
})

--in data.lua:
data.raw.item["stone-wall"].stack_size = settings.startup["my-mod-stone-wall-stack-size"].value
</syntaxhighlight>

<div class="plainlinks">
In the control stage, the settings of the setting_type "runtime-global" can be accessed using <code>settings.global["setting-name"]</code> (see [https://lua-api.factorio.com/latest/LuaSettings.html LuaSettings]). Settings of the setting_type "runtime-per-user" are accessed using <code>settings.get_player_settings([https://lua-api.factorio.com/latest/Concepts.html#PlayerIdentification <PlayerIdentification>])["setting-name"]</code> or <code>game.players[[https://lua-api.factorio.com/latest/Concepts.html#PlayerIdentification <PlayerIdentification>]].mod_settings["setting-name"]</code>.
</div>
Example:
<syntaxhighlight lang="lua">
--in settings.lua:
data:extend({
{
type = "string-setting",
name = "my-mod-always-difficult",
setting_type = "runtime-global",
default_value = "yes",
allowed_values = {"yes", "no"}
},
{
type = "bool-setting",
name = "my-mod-kill-player-on-entity-built",
setting_type = "runtime-per-user",
default_value = false
}
})

--in control.lua:
script.on_init(function()
if settings.global["my-mod-always-difficult"].value == "yes" then
game.difficulty_settings.recipe_difficulty = 1
game.difficulty_settings.technology_difficulty = 1
game.difficulty_settings.technology_price_multiplier = 4
end
end)

script.on_event(defines.events.on_built_entity, function(event)
local setting_value = settings.get_player_settings(event.player_index)["my-mod-kill-player-on-entity-built"].value
if setting_value then
game.get_player(event.player_index).die()
end
end)
</syntaxhighlight>

=== Writing to your own settings ===
It is possible for mods to write to their own runtime (global or per player) mod settings. This is done by writing a new [https://lua-api.factorio.com/latest/Concepts.html#ModSetting ModSetting] table to the setting.

Example:
<syntaxhighlight lang="lua">
--in settings.lua:
data:extend({
{
type = "string-setting",
name = "my-mod-always-difficult",
setting_type = "runtime-global",
default_value = "yes",
allowed_values = {"yes", "no"}
}
})

--in control.lua:
script.on_event(defines.events.on_rocket_launched, function()
settings.global["my-mod-always-difficult"] = {value = "yes"}
end)
</syntaxhighlight>

=== Changing another mod's settings ===
After creating a setting in the settings stage, it is stored in data.raw until the end of the stage, so it can be altered from another mod.

Example:
<syntaxhighlight lang="lua">
--in settings-updates.lua:
data.raw["string-setting"]["my-mod-always-difficult"].order = "abc"
</syntaxhighlight>

If the intent is to force the setting to be of a certain value that cannot be modified by players, the properties [[#The_hidden_property|hidden]], allowed_values and forced_value can be used. Modifying existing settings of other mods can be useful for mod packs or other mod compatibility goals.[https://forums.factorio.com/viewtopic.php?p=531322#p531322]

Example:
<syntaxhighlight lang="lua">
--in settings-updates.lua:
data.raw["string-setting"]["my-mod-always-difficult"].hidden = true
data.raw["string-setting"]["my-mod-always-difficult"].allowed_values = {"no"}
data.raw["string-setting"]["my-mod-always-difficult"].default_value = "no"
</syntaxhighlight>

=== Tips ===

* Do not conditionally 'require(...)' things depending on mod settings: This breaks the CRC checks and people will get errors trying to use your mod in multiplayer. 'require(...)' everything and then conditionally add the values to data.raw using the settings.
* You should cache the settings table inside the event you use it in. Accessing it is relatively expensive (about as expensive as accessing game.*prototypes[...]), so when accessing it mutliple times within the same event, you should set a local variable to it (within the event) to improve performance.
** If you want to cache startup/and runtime settings outside of events, you will have to makes sure that the local variable of settings of the setting_type "runtime-global" are updated in the <code>on_runtime_mod_setting_changed</code> event.
* If you want to detect whether a certain mod is installed in the settings stage, you can use <code>if mods["another-mods-name"] then</code>, just like in the data stage.

== See also ==

* [https://forums.factorio.com/viewtopic.php?p=207275 Forum post documenting mod settings]
* [https://forums.factorio.com/viewtopic.php?p=305644#p305644 per_user is not a valid property and has no effects!]
* [http://lua-api.factorio.com/latest/LuaSettings.html Lua api documentation on the settings table]

Types/HeatConnection

2023-03-04T08:11:22Z

Honktown: /* direction */ explanation

Defines the connections for a heat energy source in [[Types/EnergySource]].

== Properties ==

=== position ===
'''Type''': [[Types/Position]]

The location of the heat pipe connection, relative to the center of the entity in the north-facing direction.

=== direction ===
'''Type''': [[Types/Direction]]

The "outward" direction of this heat connection. For a connection to succeed, the other heat connection must face the opposite direction (a south-facing connection needs a north-facing connection to succeed). A connection rotates with the entity.

Types/HeatConnection

2023-03-04T08:05:51Z

Honktown: /* position */ description

Prototype/TransportBeltConnectable

2023-03-04T00:21:14Z

Honktown: /* Mandatory properties */ simple speed, rephrasing

{{Prototype parent|Prototype/EntityWithOwner}}
Abstract class that anything that is a belt or can connect to belts uses.

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

== Extensions ==

* [[Prototype/LinkedBelt]] '''linked-belt'''
* [[Prototype/Loader1x1]] '''loader-1x1'''
* [[Prototype/Loader1x2]] '''loader'''
* [[Prototype/Splitter]] '''splitter'''
* [[Prototype/TransportBelt]] '''transport-belt'''
* [[Prototype/UndergroundBelt]] '''underground-belt'''

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

{{Prototype property|speed|[[Types/double|double]]}}
The speed of the belt (since 0.17): <code>speed × 480 = x Items/second</code>

The raw value is expressed as the number of tiles traveled by each item on the belt per tick, relative to the belt's maximum density - e.g. <code>x items/second ÷ (4 items/lane × 2 lanes/belt × 60 ticks/second) = <speed> belts/tick</code> where a "belt" is the size of one tile. See [[Transport_belts/Physics]] for more details.

Must be a positive non-infinite number. The number is a fixed point number with 8 bits reserved for decimal precision, meaning the smallest value step is 1/2^8 = 0.00390625. In the simple case of a non-curved belt, the rate is multiples of 1.875 items / s, even though the entity tooltip may show a different rate.

== Optional properties ==

{{Prototype property|animation_speed_coefficient|[[Types/double|double]]|1|optional=true}}

{{Prototype property|belt_animation_set|[[Types/table|table]]|optional=true}}
Either this, or all of the properties below this one have to be present.

Table with the following properties:

* animation_set - [[Types/RotatedAnimation|RotatedAnimation]] - Mandatory.
* east_index - [[Types/uint8|uint8]] - Optional. - Default: 1
* west_index - [[Types/uint8|uint8]] - Optional. - Default: 2
* north_index - [[Types/uint8|uint8]] - Optional. - Default: 3
* south_index - [[Types/uint8|uint8]] - Optional. - Default: 4
* starting_south_index - [[Types/uint8|uint8]] - Optional. - Default: 13
* ending_south_index - [[Types/uint8|uint8]] - Optional. - Default: 14
* starting_west_index - [[Types/uint8|uint8]] - Optional. - Default: 15
* ending_west_index - [[Types/uint8|uint8]] - Optional. - Default: 16
* starting_north_index - [[Types/uint8|uint8]] - Optional. - Default: 17
* ending_north_index - [[Types/uint8|uint8]] - Optional. - Default: 18
* starting_east_index - [[Types/uint8|uint8]] - Optional. - Default: 19
* ending_east_index - [[Types/uint8|uint8]] - Optional. - Default: 20
* ending_patch - [[Types/Sprite4Way|Sprite4Way]] - Optional.
* ends_with_stopper - [[Types/bool|bool]] - Optional. - Default: false

{{Prototype property|belt_horizontal|[[Types/Animation|Animation]]|optional=true}}
Mandatory if <code>belt_animation_set</code> is not present.

{{Prototype property|belt_vertical|[[Types/Animation|Animation]]|optional=true}}
Mandatory if <code>belt_animation_set</code> is not present.

{{Prototype property|ending_top|[[Types/Animation|Animation]]|optional=true}}
Mandatory if <code>belt_animation_set</code> is not present.

{{Prototype property|ending_bottom|[[Types/Animation|Animation]]|optional=true}}
Mandatory if <code>belt_animation_set</code> is not present.

{{Prototype property|ending_side|[[Types/Animation|Animation]]|optional=true}}
Mandatory if <code>belt_animation_set</code> is not present.

{{Prototype property|starting_top|[[Types/Animation|Animation]]|optional=true}}
Mandatory if <code>belt_animation_set</code> is not present.

{{Prototype property|starting_bottom|[[Types/Animation|Animation]]|optional=true}}
Mandatory if <code>belt_animation_set</code> is not present.

{{Prototype property|starting_side|[[Types/Animation|Animation]]|optional=true}}
Mandatory if <code>belt_animation_set</code> is not present.

{{Prototype property|ending_patch|[[Types/Sprite4Way|Sprite4Way]]|optional=true}}
Always optional. Only read if <code>belt_animation_set</code> is not present.

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

== Mandatory values ==
Transport belt connectables have additional requirements for the properties inherited from [[Prototype/Entity]]:
* Transport belt connectable entities must collide with [[Types/CollisionMask#Layers|"transport-belt-layer"]].
* Transport belt connectable entities must have [[Types/CollisionMask#Collision_options|collision mask]] that collides with itself.
* Transport belt connectable entities cannot have collision mask that collides only with tiles (must collide with entities in some way).
* Transport belt connectable entities must have collision box of an appropriate minimal size, they should occupy more than half of every tile the entity covers.
* Transport belt connectable entities cannot have the [[Types/EntityPrototypeFlags#.22placeable-off-grid.22|"placeable-off-grid"]] flag specified.

Tutorial:Mod settings

2023-03-03T19:40:51Z

Honktown: /* color-setting */ resulting table in control

{{Languages}}
This tutorial aims to explain how to create and use mod settings. Basic knowledge of modding is assumed, so you should have at least understood [[Tutorial:Modding tutorial/Gangsir|Gangsir's modding tutorial]].

== Overview ==
Each mod can specify settings that users can change. The values of these settings can be accessed from inside the data stage or the control stage depending on their [[#The_setting_type_property|setting_type]] and allow to conditionally create or modify prototypes and to add configuration options to control scripts. They allow modders to easily create a graphical interface for their configuration options, instead of using on text files that have to be edited manually by users.

== Location ==

Mod settings are defined in the [https://lua-api.factorio.com/latest/Data-Lifecycle.html settings stage]. This stage is loaded before the data stage. There are three files in which settings can be defined:
* settings.lua
* settings-updates.lua
* settings-final-fixes.lua

First the settings.lua file is called for each mod, in the order of their dependencies and then in the [[:Wikipedia:natural sort order|natural sort order]]. After settings.lua has been called for all mods, the settings-updates.lua file is called for each mod (in the same order) and finally the settings-final-fixes.lua file is called for each mod (in the same order). These 3 different phases of the settings stage allow to change settings of other mods without needing to rely on dependencies to load last. The settings are all defined in the same stage and their user defined values are not available, therefore mods cannot conditionally create settings depending on the values of other mod settings. Since the settings stage gets loaded first, there is also no prototype data or [http://lua-api.factorio.com/latest/LuaRemote.html remote interface] available.

The "mod-settings.dat" file stored in the [[Application_directory#User_Data_directory|mods folder]] for the game contains the local players settings between game sessions similar to the player-data.json file.

== Creation ==

Mod settings are defined and modified by using the data table during the settings stage. This works [[Tutorial:Modding_tutorial/Gangsir#Prototype_creation|the same way as other prototypes]]. An example would be:
<syntaxhighlight lang="lua">
data:extend({
{
type = "bool-setting",
name = "my-mod-test-setting",
setting_type = "runtime-global",
default_value = true
}
})
</syntaxhighlight>

As you can see, the setting has multiple properties. Each setting supports the following standard prototype properties:
* name - [[Types/string|string]] - Mandatory.
* type - [[Types/string|string]] - Mandatory.
* localised_name - [[Types/LocalisedString|LocalisedString]] - Optional.
* localised_description - [[Types/LocalisedString|LocalisedString]] - Optional.
* [[Types/Order|order]] - [[Types/string|string]] - Optional.

In addition to the standard properties, mod settings also contain:

* hidden - [[Types/bool|bool]] - Optional.
* setting_type - [[Types/string|string]] - Mandatory.

=== The name property ===

The name of the settings prototype should be unique to avoid mod conflicts since the mod settings are global across all mods. Because of that it is recommened to prefix mod settings with your mod name, "my-mod" in this example.

=== The type property ===

There are four types of mod settings:

* bool-setting - a true/false checkbox
* int-setting - a signed 64 bit integer textfield (or selection dropdown)
* double-setting - a double precision floating point textfield (or selection dropdown)
* string-setting - a string textfield (or selection dropdown)
* color-setting - a color picker (sliders), with whole number textfields. Includes alpha.

Depending on the type, the prototype also allows or requires additional properties, these are listed below.

==== bool-setting ====
* default_value - [[Types/bool|bool]] - Mandatory.
** Defines the default value of the setting, in this case whether the checkbox is checked or not.
* forced_value - [[Types/bool|bool]] - Optional.
** Only loaded if <code>hidden = true</code>. This forces the setting to be of this value. This can be useful for mod compatiblity.[https://forums.factorio.com/viewtopic.php?p=531322#p531322]


==== int-setting ====
* default_value - [[Types/int64|int64]] - Mandatory.
** Defines the default value of the setting.
* minimum_value - [[Types/int64|int64]] - Optional.
** Defines the lowest possible number.
* maximum_value - [[Types/int64|int64]] - Optional.
** Defines the highest possible number.
* allowed_values - [[Types/table|array]] of [[Types/int64|int64]] - Optional.
** Makes it possible to force the player to choose between the defined numbers, creates a dropdown instead of a texfield.
** If only one allowed value is given, the settings is forced to be of that value.

==== double-setting ====
* default_value - [[Types/double|double]] - Mandatory.
** Defines the default value of the setting.
* minimum_value - [[Types/double|double]] - Optional.
** Defines the lowest possible number.
* maximum_value - [[Types/double|double]] - Optional.
** Defines the highest possible number.
* allowed_values - [[Types/table|array]] of [[Types/double|double]] - Optional.
** Makes it possible to force the player to choose between the defined numbers, creates a dropdown instead of a textfield.
** If only one allowed value is given, the settings is forced to be of that value.

==== string-setting ====
* default_value - [[Types/string|string]] - Mandatory.
** Defines the default value of the setting.
* allow_blank - [[Types/bool|bool]] - Optional. - Default: false
** Defines whether it's possible for the user to set the textfield to empty and apply the setting.
* auto_trim - [[Types/bool|bool]] - Optional. - Default: false
** Whether values that are input by the user should have whitespace removed from both ends of the string.
* allowed_values - [[Types/table|array]] of [[Types/string|string]] - Optional.
** Makes it possible to force the player to choose between the defined strings, creates a dropdown instead of a textfield. The strings in the dropdown can be localized (translated) and can have a tooltip, see below.
** If only one allowed value is given, the settings is forced to be of that value.

==== color-setting ====
* default_value = [[Types/Color|color]] - Mandatory.
** Default color to set. When read during control, the color has 'r', 'g', 'b', 'a' keys and values [0, 1]

=== The order property ===

The order property can be used to change how the mod settings are ordered in the settings gui. Mod settings are sorted
* first by mod
* then by the setting "order" string
* then finally by the setting name.

For more info on how to use the order string, see [[Types/Order]].

=== The hidden property ===

The hidden property can be used to hide mod settings from GUIs, so that they cannot be seen or changed by players. However, other mods can still access hidden settings.[https://forums.factorio.com/83316]

=== The setting_type property ===
[[File:Mod_settings_gui.png|right|300px|thumb|The mod settings gui. Can be reached from the main menu → Settings → Mod settings.]]
There are the overall kinds of settings:

* '''startup''': This kind of setting is available in the prototype stage, and can not be changed runtime. They have to be set to the same values for all players on a server.
* '''runtime-global''': This kind of setting is global to an entire save game and can be changed runtime. On servers, only admins can change these settings.
* '''runtime-per-user''': This kind of setting is only available runtime in the control.lua stage and each player has their own instance of this setting. When a player joins a server their local setting of "keep mod settings per save" determines if the local settings they have set are synced to the loaded save or if the save's settings are used.

This "setting_type" also determines in which tab the setting is showed in the mod settings menu.

=== Locale ===
The locale for mod settings works like any other locale in the game. The names of the groups for the setting name and description (tooltip) are "mod-setting-name" and "mod-setting-description". The dropdown items of a string setting can be localized in the "string-mod-setting" group, but the game falls back to just showing the name of the dropdown item if no localization is found. An example for mod setting localization that would be set within "locale/en/locale.cfg", is:
<pre>
[mod-setting-name]
my-mod-test-setting=Localized test setting name

[mod-setting-description]
my-mod-test-setting=Localized test setting description

[string-mod-setting]
#<setting-name>-<dropdown-item-name>=<translated dropdown item>
my-mod-string-test-setting-item-1=Item 1 localized string

[string-mod-setting-description]
#<setting-name>-<dropdown-item-name>=<tooltip of dropdown item>
my-mod-string-test-setting-item-1=Item 1 localized tooltip

</pre>

== Usage ==
=== Reading settings ===
When accessing any mod setting, you will have to specifically access the ''value'' of the setting. The data type of the value depends on the type of the setting. For string settings that use a selection of allowed values, the value of the setting is one of the original string values defined in the prototype, the localization is ignored. See also: [http://lua-api.factorio.com/latest/Concepts.html#ModSetting ModSetting concept].

In the prototype stage you can access settings of the setting_type "startup" by indexing <code>settings.startup</code> with the name of the setting. Example:
<syntaxhighlight lang="lua">
--in settings.lua:
data:extend({
{
type = "int-setting",
name = "my-mod-stone-wall-stack-size",
setting_type = "startup",
minimum_value = 1,
default_value = 100
}
})

--in data.lua:
data.raw.item["stone-wall"].stack_size = settings.startup["my-mod-stone-wall-stack-size"].value
</syntaxhighlight>

<div class="plainlinks">
In the control stage, the settings of the setting_type "runtime-global" can be accessed using <code>settings.global["setting-name"]</code> (see [https://lua-api.factorio.com/latest/LuaSettings.html LuaSettings]). Settings of the setting_type "runtime-per-user" are accessed using <code>settings.get_player_settings([https://lua-api.factorio.com/latest/Concepts.html#PlayerIdentification <PlayerIdentification>])["setting-name"]</code> or <code>game.players[[https://lua-api.factorio.com/latest/Concepts.html#PlayerIdentification <PlayerIdentification>]].mod_settings["setting-name"]</code>.
</div>
Example:
<syntaxhighlight lang="lua">
--in settings.lua:
data:extend({
{
type = "string-setting",
name = "my-mod-always-difficult",
setting_type = "runtime-global",
default_value = "yes",
allowed_values = {"yes", "no"}
},
{
type = "bool-setting",
name = "my-mod-kill-player-on-entity-built",
setting_type = "runtime-per-user",
default_value = false
}
})

--in control.lua:
script.on_init(function()
if settings.global["my-mod-always-difficult"].value == "yes" then
game.difficulty_settings.recipe_difficulty = 1
game.difficulty_settings.technology_difficulty = 1
game.difficulty_settings.technology_price_multiplier = 4
end
end)

script.on_event(defines.events.on_built_entity, function(event)
local setting_value = settings.get_player_settings(event.player_index)["my-mod-kill-player-on-entity-built"].value
if setting_value then
game.get_player(event.player_index).die()
end
end)
</syntaxhighlight>

=== Writing to your own settings ===
It is possible for mods to write to their own runtime (global or per player) mod settings. This is done by writing a new [https://lua-api.factorio.com/latest/Concepts.html#ModSetting ModSetting] table to the setting.

Example:
<syntaxhighlight lang="lua">
--in settings.lua:
data:extend({
{
type = "string-setting",
name = "my-mod-always-difficult",
setting_type = "runtime-global",
default_value = "yes",
allowed_values = {"yes", "no"}
}
})

--in control.lua:
script.on_event(defines.events.on_rocket_launched, function()
settings.global["my-mod-always-difficult"] = {value = "yes"}
end)
</syntaxhighlight>

=== Changing another mod's settings ===
After creating a setting in the settings stage, it is stored in data.raw until the end of the stage, so it can be altered from another mod.

Example:
<syntaxhighlight lang="lua">
--in settings-updates.lua:
data.raw["string-setting"]["my-mod-always-difficult"].order = "abc"
</syntaxhighlight>

If the intent is to force the setting to be of a certain value that cannot be modified by players, the properties [[#The_hidden_property|hidden]], allowed_values and forced_value can be used. Modifying existing settings of other mods can be useful for mod packs or other mod compatibility goals.[https://forums.factorio.com/viewtopic.php?p=531322#p531322]

Example:
<syntaxhighlight lang="lua">
--in settings-updates.lua:
data.raw["string-setting"]["my-mod-always-difficult"].hidden = true
data.raw["string-setting"]["my-mod-always-difficult"].allowed_values = {"no"}
data.raw["string-setting"]["my-mod-always-difficult"].default_value = "no"
</syntaxhighlight>

=== Tips ===

* Do not conditionally 'require(...)' things depending on mod settings: This breaks the CRC checks and people will get errors trying to use your mod in multiplayer. 'require(...)' everything and then conditionally add the values to data.raw using the settings.
* You should cache the settings table inside the event you use it in. Accessing it is relatively expensive (about as expensive as accessing game.*prototypes[...]), so when accessing it mutliple times within the same event, you should set a local variable to it (within the event) to improve performance.
** If you want to cache startup/and runtime settings outside of events, you will have to makes sure that the local variable of settings of the setting_type "runtime-global" are updated in the <code>on_runtime_mod_setting_changed</code> event.
* If you want to detect whether a certain mod is installed in the settings stage, you can use <code>if mods["another-mods-name"] then</code>, just like in the data stage.

== See also ==

* [https://forums.factorio.com/viewtopic.php?p=207275 Forum post documenting mod settings]
* [https://forums.factorio.com/viewtopic.php?p=305644#p305644 per_user is not a valid property and has no effects!]
* [http://lua-api.factorio.com/latest/LuaSettings.html Lua api documentation on the settings table]

Tutorial:Mod settings

2023-03-03T19:31:48Z

Honktown: /* The type property */ color setting description at top

{{Languages}}
This tutorial aims to explain how to create and use mod settings. Basic knowledge of modding is assumed, so you should have at least understood [[Tutorial:Modding tutorial/Gangsir|Gangsir's modding tutorial]].

== Overview ==
Each mod can specify settings that users can change. The values of these settings can be accessed from inside the data stage or the control stage depending on their [[#The_setting_type_property|setting_type]] and allow to conditionally create or modify prototypes and to add configuration options to control scripts. They allow modders to easily create a graphical interface for their configuration options, instead of using on text files that have to be edited manually by users.

== Location ==

Mod settings are defined in the [https://lua-api.factorio.com/latest/Data-Lifecycle.html settings stage]. This stage is loaded before the data stage. There are three files in which settings can be defined:
* settings.lua
* settings-updates.lua
* settings-final-fixes.lua

First the settings.lua file is called for each mod, in the order of their dependencies and then in the [[:Wikipedia:natural sort order|natural sort order]]. After settings.lua has been called for all mods, the settings-updates.lua file is called for each mod (in the same order) and finally the settings-final-fixes.lua file is called for each mod (in the same order). These 3 different phases of the settings stage allow to change settings of other mods without needing to rely on dependencies to load last. The settings are all defined in the same stage and their user defined values are not available, therefore mods cannot conditionally create settings depending on the values of other mod settings. Since the settings stage gets loaded first, there is also no prototype data or [http://lua-api.factorio.com/latest/LuaRemote.html remote interface] available.

The "mod-settings.dat" file stored in the [[Application_directory#User_Data_directory|mods folder]] for the game contains the local players settings between game sessions similar to the player-data.json file.

== Creation ==

Mod settings are defined and modified by using the data table during the settings stage. This works [[Tutorial:Modding_tutorial/Gangsir#Prototype_creation|the same way as other prototypes]]. An example would be:
<syntaxhighlight lang="lua">
data:extend({
{
type = "bool-setting",
name = "my-mod-test-setting",
setting_type = "runtime-global",
default_value = true
}
})
</syntaxhighlight>

As you can see, the setting has multiple properties. Each setting supports the following standard prototype properties:
* name - [[Types/string|string]] - Mandatory.
* type - [[Types/string|string]] - Mandatory.
* localised_name - [[Types/LocalisedString|LocalisedString]] - Optional.
* localised_description - [[Types/LocalisedString|LocalisedString]] - Optional.
* [[Types/Order|order]] - [[Types/string|string]] - Optional.

In addition to the standard properties, mod settings also contain:

* hidden - [[Types/bool|bool]] - Optional.
* setting_type - [[Types/string|string]] - Mandatory.

=== The name property ===

The name of the settings prototype should be unique to avoid mod conflicts since the mod settings are global across all mods. Because of that it is recommened to prefix mod settings with your mod name, "my-mod" in this example.

=== The type property ===

There are four types of mod settings:

* bool-setting - a true/false checkbox
* int-setting - a signed 64 bit integer textfield (or selection dropdown)
* double-setting - a double precision floating point textfield (or selection dropdown)
* string-setting - a string textfield (or selection dropdown)
* color-setting - a color picker (sliders), with whole number textfields. Includes alpha.

Depending on the type, the prototype also allows or requires additional properties, these are listed below.

==== bool-setting ====
* default_value - [[Types/bool|bool]] - Mandatory.
** Defines the default value of the setting, in this case whether the checkbox is checked or not.
* forced_value - [[Types/bool|bool]] - Optional.
** Only loaded if <code>hidden = true</code>. This forces the setting to be of this value. This can be useful for mod compatiblity.[https://forums.factorio.com/viewtopic.php?p=531322#p531322]


==== int-setting ====
* default_value - [[Types/int64|int64]] - Mandatory.
** Defines the default value of the setting.
* minimum_value - [[Types/int64|int64]] - Optional.
** Defines the lowest possible number.
* maximum_value - [[Types/int64|int64]] - Optional.
** Defines the highest possible number.
* allowed_values - [[Types/table|array]] of [[Types/int64|int64]] - Optional.
** Makes it possible to force the player to choose between the defined numbers, creates a dropdown instead of a texfield.
** If only one allowed value is given, the settings is forced to be of that value.

==== double-setting ====
* default_value - [[Types/double|double]] - Mandatory.
** Defines the default value of the setting.
* minimum_value - [[Types/double|double]] - Optional.
** Defines the lowest possible number.
* maximum_value - [[Types/double|double]] - Optional.
** Defines the highest possible number.
* allowed_values - [[Types/table|array]] of [[Types/double|double]] - Optional.
** Makes it possible to force the player to choose between the defined numbers, creates a dropdown instead of a textfield.
** If only one allowed value is given, the settings is forced to be of that value.

==== string-setting ====
* default_value - [[Types/string|string]] - Mandatory.
** Defines the default value of the setting.
* allow_blank - [[Types/bool|bool]] - Optional. - Default: false
** Defines whether it's possible for the user to set the textfield to empty and apply the setting.
* auto_trim - [[Types/bool|bool]] - Optional. - Default: false
** Whether values that are input by the user should have whitespace removed from both ends of the string.
* allowed_values - [[Types/table|array]] of [[Types/string|string]] - Optional.
** Makes it possible to force the player to choose between the defined strings, creates a dropdown instead of a textfield. The strings in the dropdown can be localized (translated) and can have a tooltip, see below.
** If only one allowed value is given, the settings is forced to be of that value.

==== color-setting ====
* default_value = [[Types/Color|color]] - Mandatory.
** Default color to set.

=== The order property ===

The order property can be used to change how the mod settings are ordered in the settings gui. Mod settings are sorted
* first by mod
* then by the setting "order" string
* then finally by the setting name.

For more info on how to use the order string, see [[Types/Order]].

=== The hidden property ===

The hidden property can be used to hide mod settings from GUIs, so that they cannot be seen or changed by players. However, other mods can still access hidden settings.[https://forums.factorio.com/83316]

=== The setting_type property ===
[[File:Mod_settings_gui.png|right|300px|thumb|The mod settings gui. Can be reached from the main menu → Settings → Mod settings.]]
There are the overall kinds of settings:

* '''startup''': This kind of setting is available in the prototype stage, and can not be changed runtime. They have to be set to the same values for all players on a server.
* '''runtime-global''': This kind of setting is global to an entire save game and can be changed runtime. On servers, only admins can change these settings.
* '''runtime-per-user''': This kind of setting is only available runtime in the control.lua stage and each player has their own instance of this setting. When a player joins a server their local setting of "keep mod settings per save" determines if the local settings they have set are synced to the loaded save or if the save's settings are used.

This "setting_type" also determines in which tab the setting is showed in the mod settings menu.

=== Locale ===
The locale for mod settings works like any other locale in the game. The names of the groups for the setting name and description (tooltip) are "mod-setting-name" and "mod-setting-description". The dropdown items of a string setting can be localized in the "string-mod-setting" group, but the game falls back to just showing the name of the dropdown item if no localization is found. An example for mod setting localization that would be set within "locale/en/locale.cfg", is:
<pre>
[mod-setting-name]
my-mod-test-setting=Localized test setting name

[mod-setting-description]
my-mod-test-setting=Localized test setting description

[string-mod-setting]
#<setting-name>-<dropdown-item-name>=<translated dropdown item>
my-mod-string-test-setting-item-1=Item 1 localized string

[string-mod-setting-description]
#<setting-name>-<dropdown-item-name>=<tooltip of dropdown item>
my-mod-string-test-setting-item-1=Item 1 localized tooltip

</pre>

== Usage ==
=== Reading settings ===
When accessing any mod setting, you will have to specifically access the ''value'' of the setting. The data type of the value depends on the type of the setting. For string settings that use a selection of allowed values, the value of the setting is one of the original string values defined in the prototype, the localization is ignored. See also: [http://lua-api.factorio.com/latest/Concepts.html#ModSetting ModSetting concept].

In the prototype stage you can access settings of the setting_type "startup" by indexing <code>settings.startup</code> with the name of the setting. Example:
<syntaxhighlight lang="lua">
--in settings.lua:
data:extend({
{
type = "int-setting",
name = "my-mod-stone-wall-stack-size",
setting_type = "startup",
minimum_value = 1,
default_value = 100
}
})

--in data.lua:
data.raw.item["stone-wall"].stack_size = settings.startup["my-mod-stone-wall-stack-size"].value
</syntaxhighlight>

<div class="plainlinks">
In the control stage, the settings of the setting_type "runtime-global" can be accessed using <code>settings.global["setting-name"]</code> (see [https://lua-api.factorio.com/latest/LuaSettings.html LuaSettings]). Settings of the setting_type "runtime-per-user" are accessed using <code>settings.get_player_settings([https://lua-api.factorio.com/latest/Concepts.html#PlayerIdentification <PlayerIdentification>])["setting-name"]</code> or <code>game.players[[https://lua-api.factorio.com/latest/Concepts.html#PlayerIdentification <PlayerIdentification>]].mod_settings["setting-name"]</code>.
</div>
Example:
<syntaxhighlight lang="lua">
--in settings.lua:
data:extend({
{
type = "string-setting",
name = "my-mod-always-difficult",
setting_type = "runtime-global",
default_value = "yes",
allowed_values = {"yes", "no"}
},
{
type = "bool-setting",
name = "my-mod-kill-player-on-entity-built",
setting_type = "runtime-per-user",
default_value = false
}
})

--in control.lua:
script.on_init(function()
if settings.global["my-mod-always-difficult"].value == "yes" then
game.difficulty_settings.recipe_difficulty = 1
game.difficulty_settings.technology_difficulty = 1
game.difficulty_settings.technology_price_multiplier = 4
end
end)

script.on_event(defines.events.on_built_entity, function(event)
local setting_value = settings.get_player_settings(event.player_index)["my-mod-kill-player-on-entity-built"].value
if setting_value then
game.get_player(event.player_index).die()
end
end)
</syntaxhighlight>

=== Writing to your own settings ===
It is possible for mods to write to their own runtime (global or per player) mod settings. This is done by writing a new [https://lua-api.factorio.com/latest/Concepts.html#ModSetting ModSetting] table to the setting.

Example:
<syntaxhighlight lang="lua">
--in settings.lua:
data:extend({
{
type = "string-setting",
name = "my-mod-always-difficult",
setting_type = "runtime-global",
default_value = "yes",
allowed_values = {"yes", "no"}
}
})

--in control.lua:
script.on_event(defines.events.on_rocket_launched, function()
settings.global["my-mod-always-difficult"] = {value = "yes"}
end)
</syntaxhighlight>

=== Changing another mod's settings ===
After creating a setting in the settings stage, it is stored in data.raw until the end of the stage, so it can be altered from another mod.

Example:
<syntaxhighlight lang="lua">
--in settings-updates.lua:
data.raw["string-setting"]["my-mod-always-difficult"].order = "abc"
</syntaxhighlight>

If the intent is to force the setting to be of a certain value that cannot be modified by players, the properties [[#The_hidden_property|hidden]], allowed_values and forced_value can be used. Modifying existing settings of other mods can be useful for mod packs or other mod compatibility goals.[https://forums.factorio.com/viewtopic.php?p=531322#p531322]

Example:
<syntaxhighlight lang="lua">
--in settings-updates.lua:
data.raw["string-setting"]["my-mod-always-difficult"].hidden = true
data.raw["string-setting"]["my-mod-always-difficult"].allowed_values = {"no"}
data.raw["string-setting"]["my-mod-always-difficult"].default_value = "no"
</syntaxhighlight>

=== Tips ===

* Do not conditionally 'require(...)' things depending on mod settings: This breaks the CRC checks and people will get errors trying to use your mod in multiplayer. 'require(...)' everything and then conditionally add the values to data.raw using the settings.
* You should cache the settings table inside the event you use it in. Accessing it is relatively expensive (about as expensive as accessing game.*prototypes[...]), so when accessing it mutliple times within the same event, you should set a local variable to it (within the event) to improve performance.
** If you want to cache startup/and runtime settings outside of events, you will have to makes sure that the local variable of settings of the setting_type "runtime-global" are updated in the <code>on_runtime_mod_setting_changed</code> event.
* If you want to detect whether a certain mod is installed in the settings stage, you can use <code>if mods["another-mods-name"] then</code>, just like in the data stage.

== See also ==

* [https://forums.factorio.com/viewtopic.php?p=207275 Forum post documenting mod settings]
* [https://forums.factorio.com/viewtopic.php?p=305644#p305644 per_user is not a valid property and has no effects!]
* [http://lua-api.factorio.com/latest/LuaSettings.html Lua api documentation on the settings table]

Tutorial:Mod settings

2023-03-03T19:26:05Z

Honktown: /* string-setting */ -> new color setting!

{{Languages}}
This tutorial aims to explain how to create and use mod settings. Basic knowledge of modding is assumed, so you should have at least understood [[Tutorial:Modding tutorial/Gangsir|Gangsir's modding tutorial]].

== Overview ==
Each mod can specify settings that users can change. The values of these settings can be accessed from inside the data stage or the control stage depending on their [[#The_setting_type_property|setting_type]] and allow to conditionally create or modify prototypes and to add configuration options to control scripts. They allow modders to easily create a graphical interface for their configuration options, instead of using on text files that have to be edited manually by users.

== Location ==

Mod settings are defined in the [https://lua-api.factorio.com/latest/Data-Lifecycle.html settings stage]. This stage is loaded before the data stage. There are three files in which settings can be defined:
* settings.lua
* settings-updates.lua
* settings-final-fixes.lua

First the settings.lua file is called for each mod, in the order of their dependencies and then in the [[:Wikipedia:natural sort order|natural sort order]]. After settings.lua has been called for all mods, the settings-updates.lua file is called for each mod (in the same order) and finally the settings-final-fixes.lua file is called for each mod (in the same order). These 3 different phases of the settings stage allow to change settings of other mods without needing to rely on dependencies to load last. The settings are all defined in the same stage and their user defined values are not available, therefore mods cannot conditionally create settings depending on the values of other mod settings. Since the settings stage gets loaded first, there is also no prototype data or [http://lua-api.factorio.com/latest/LuaRemote.html remote interface] available.

The "mod-settings.dat" file stored in the [[Application_directory#User_Data_directory|mods folder]] for the game contains the local players settings between game sessions similar to the player-data.json file.

== Creation ==

Mod settings are defined and modified by using the data table during the settings stage. This works [[Tutorial:Modding_tutorial/Gangsir#Prototype_creation|the same way as other prototypes]]. An example would be:
<syntaxhighlight lang="lua">
data:extend({
{
type = "bool-setting",
name = "my-mod-test-setting",
setting_type = "runtime-global",
default_value = true
}
})
</syntaxhighlight>

As you can see, the setting has multiple properties. Each setting supports the following standard prototype properties:
* name - [[Types/string|string]] - Mandatory.
* type - [[Types/string|string]] - Mandatory.
* localised_name - [[Types/LocalisedString|LocalisedString]] - Optional.
* localised_description - [[Types/LocalisedString|LocalisedString]] - Optional.
* [[Types/Order|order]] - [[Types/string|string]] - Optional.

In addition to the standard properties, mod settings also contain:

* hidden - [[Types/bool|bool]] - Optional.
* setting_type - [[Types/string|string]] - Mandatory.

=== The name property ===

The name of the settings prototype should be unique to avoid mod conflicts since the mod settings are global across all mods. Because of that it is recommened to prefix mod settings with your mod name, "my-mod" in this example.

=== The type property ===

There are four types of mod settings:

* bool-setting - a true/false checkbox
* int-setting - a signed 64 bit integer textfield (or selection dropdown)
* double-setting - a double precision floating point textfield (or selection dropdown)
* string-setting - a string textfield (or selection dropdown)

Depending on the type, the prototype also allows or requires additional properties, these are listed below.

==== bool-setting ====
* default_value - [[Types/bool|bool]] - Mandatory.
** Defines the default value of the setting, in this case whether the checkbox is checked or not.
* forced_value - [[Types/bool|bool]] - Optional.
** Only loaded if <code>hidden = true</code>. This forces the setting to be of this value. This can be useful for mod compatiblity.[https://forums.factorio.com/viewtopic.php?p=531322#p531322]


==== int-setting ====
* default_value - [[Types/int64|int64]] - Mandatory.
** Defines the default value of the setting.
* minimum_value - [[Types/int64|int64]] - Optional.
** Defines the lowest possible number.
* maximum_value - [[Types/int64|int64]] - Optional.
** Defines the highest possible number.
* allowed_values - [[Types/table|array]] of [[Types/int64|int64]] - Optional.
** Makes it possible to force the player to choose between the defined numbers, creates a dropdown instead of a texfield.
** If only one allowed value is given, the settings is forced to be of that value.

==== double-setting ====
* default_value - [[Types/double|double]] - Mandatory.
** Defines the default value of the setting.
* minimum_value - [[Types/double|double]] - Optional.
** Defines the lowest possible number.
* maximum_value - [[Types/double|double]] - Optional.
** Defines the highest possible number.
* allowed_values - [[Types/table|array]] of [[Types/double|double]] - Optional.
** Makes it possible to force the player to choose between the defined numbers, creates a dropdown instead of a textfield.
** If only one allowed value is given, the settings is forced to be of that value.

==== string-setting ====
* default_value - [[Types/string|string]] - Mandatory.
** Defines the default value of the setting.
* allow_blank - [[Types/bool|bool]] - Optional. - Default: false
** Defines whether it's possible for the user to set the textfield to empty and apply the setting.
* auto_trim - [[Types/bool|bool]] - Optional. - Default: false
** Whether values that are input by the user should have whitespace removed from both ends of the string.
* allowed_values - [[Types/table|array]] of [[Types/string|string]] - Optional.
** Makes it possible to force the player to choose between the defined strings, creates a dropdown instead of a textfield. The strings in the dropdown can be localized (translated) and can have a tooltip, see below.
** If only one allowed value is given, the settings is forced to be of that value.

==== color-setting ====
* default_value = [[Types/Color|color]] - Mandatory.
** Default color to set.

=== The order property ===

The order property can be used to change how the mod settings are ordered in the settings gui. Mod settings are sorted
* first by mod
* then by the setting "order" string
* then finally by the setting name.

For more info on how to use the order string, see [[Types/Order]].

=== The hidden property ===

The hidden property can be used to hide mod settings from GUIs, so that they cannot be seen or changed by players. However, other mods can still access hidden settings.[https://forums.factorio.com/83316]

=== The setting_type property ===
[[File:Mod_settings_gui.png|right|300px|thumb|The mod settings gui. Can be reached from the main menu → Settings → Mod settings.]]
There are the overall kinds of settings:

* '''startup''': This kind of setting is available in the prototype stage, and can not be changed runtime. They have to be set to the same values for all players on a server.
* '''runtime-global''': This kind of setting is global to an entire save game and can be changed runtime. On servers, only admins can change these settings.
* '''runtime-per-user''': This kind of setting is only available runtime in the control.lua stage and each player has their own instance of this setting. When a player joins a server their local setting of "keep mod settings per save" determines if the local settings they have set are synced to the loaded save or if the save's settings are used.

This "setting_type" also determines in which tab the setting is showed in the mod settings menu.

=== Locale ===
The locale for mod settings works like any other locale in the game. The names of the groups for the setting name and description (tooltip) are "mod-setting-name" and "mod-setting-description". The dropdown items of a string setting can be localized in the "string-mod-setting" group, but the game falls back to just showing the name of the dropdown item if no localization is found. An example for mod setting localization that would be set within "locale/en/locale.cfg", is:
<pre>
[mod-setting-name]
my-mod-test-setting=Localized test setting name

[mod-setting-description]
my-mod-test-setting=Localized test setting description

[string-mod-setting]
#<setting-name>-<dropdown-item-name>=<translated dropdown item>
my-mod-string-test-setting-item-1=Item 1 localized string

[string-mod-setting-description]
#<setting-name>-<dropdown-item-name>=<tooltip of dropdown item>
my-mod-string-test-setting-item-1=Item 1 localized tooltip

</pre>

== Usage ==
=== Reading settings ===
When accessing any mod setting, you will have to specifically access the ''value'' of the setting. The data type of the value depends on the type of the setting. For string settings that use a selection of allowed values, the value of the setting is one of the original string values defined in the prototype, the localization is ignored. See also: [http://lua-api.factorio.com/latest/Concepts.html#ModSetting ModSetting concept].

In the prototype stage you can access settings of the setting_type "startup" by indexing <code>settings.startup</code> with the name of the setting. Example:
<syntaxhighlight lang="lua">
--in settings.lua:
data:extend({
{
type = "int-setting",
name = "my-mod-stone-wall-stack-size",
setting_type = "startup",
minimum_value = 1,
default_value = 100
}
})

--in data.lua:
data.raw.item["stone-wall"].stack_size = settings.startup["my-mod-stone-wall-stack-size"].value
</syntaxhighlight>

<div class="plainlinks">
In the control stage, the settings of the setting_type "runtime-global" can be accessed using <code>settings.global["setting-name"]</code> (see [https://lua-api.factorio.com/latest/LuaSettings.html LuaSettings]). Settings of the setting_type "runtime-per-user" are accessed using <code>settings.get_player_settings([https://lua-api.factorio.com/latest/Concepts.html#PlayerIdentification <PlayerIdentification>])["setting-name"]</code> or <code>game.players[[https://lua-api.factorio.com/latest/Concepts.html#PlayerIdentification <PlayerIdentification>]].mod_settings["setting-name"]</code>.
</div>
Example:
<syntaxhighlight lang="lua">
--in settings.lua:
data:extend({
{
type = "string-setting",
name = "my-mod-always-difficult",
setting_type = "runtime-global",
default_value = "yes",
allowed_values = {"yes", "no"}
},
{
type = "bool-setting",
name = "my-mod-kill-player-on-entity-built",
setting_type = "runtime-per-user",
default_value = false
}
})

--in control.lua:
script.on_init(function()
if settings.global["my-mod-always-difficult"].value == "yes" then
game.difficulty_settings.recipe_difficulty = 1
game.difficulty_settings.technology_difficulty = 1
game.difficulty_settings.technology_price_multiplier = 4
end
end)

script.on_event(defines.events.on_built_entity, function(event)
local setting_value = settings.get_player_settings(event.player_index)["my-mod-kill-player-on-entity-built"].value
if setting_value then
game.get_player(event.player_index).die()
end
end)
</syntaxhighlight>

=== Writing to your own settings ===
It is possible for mods to write to their own runtime (global or per player) mod settings. This is done by writing a new [https://lua-api.factorio.com/latest/Concepts.html#ModSetting ModSetting] table to the setting.

Example:
<syntaxhighlight lang="lua">
--in settings.lua:
data:extend({
{
type = "string-setting",
name = "my-mod-always-difficult",
setting_type = "runtime-global",
default_value = "yes",
allowed_values = {"yes", "no"}
}
})

--in control.lua:
script.on_event(defines.events.on_rocket_launched, function()
settings.global["my-mod-always-difficult"] = {value = "yes"}
end)
</syntaxhighlight>

=== Changing another mod's settings ===
After creating a setting in the settings stage, it is stored in data.raw until the end of the stage, so it can be altered from another mod.

Example:
<syntaxhighlight lang="lua">
--in settings-updates.lua:
data.raw["string-setting"]["my-mod-always-difficult"].order = "abc"
</syntaxhighlight>

If the intent is to force the setting to be of a certain value that cannot be modified by players, the properties [[#The_hidden_property|hidden]], allowed_values and forced_value can be used. Modifying existing settings of other mods can be useful for mod packs or other mod compatibility goals.[https://forums.factorio.com/viewtopic.php?p=531322#p531322]

Example:
<syntaxhighlight lang="lua">
--in settings-updates.lua:
data.raw["string-setting"]["my-mod-always-difficult"].hidden = true
data.raw["string-setting"]["my-mod-always-difficult"].allowed_values = {"no"}
data.raw["string-setting"]["my-mod-always-difficult"].default_value = "no"
</syntaxhighlight>

=== Tips ===

* Do not conditionally 'require(...)' things depending on mod settings: This breaks the CRC checks and people will get errors trying to use your mod in multiplayer. 'require(...)' everything and then conditionally add the values to data.raw using the settings.
* You should cache the settings table inside the event you use it in. Accessing it is relatively expensive (about as expensive as accessing game.*prototypes[...]), so when accessing it mutliple times within the same event, you should set a local variable to it (within the event) to improve performance.
** If you want to cache startup/and runtime settings outside of events, you will have to makes sure that the local variable of settings of the setting_type "runtime-global" are updated in the <code>on_runtime_mod_setting_changed</code> event.
* If you want to detect whether a certain mod is installed in the settings stage, you can use <code>if mods["another-mods-name"] then</code>, just like in the data stage.

== See also ==

* [https://forums.factorio.com/viewtopic.php?p=207275 Forum post documenting mod settings]
* [https://forums.factorio.com/viewtopic.php?p=305644#p305644 per_user is not a valid property and has no effects!]
* [http://lua-api.factorio.com/latest/LuaSettings.html Lua api documentation on the settings table]

Prototype/TransportBeltConnectable

2023-03-02T00:55:08Z

Honktown: /* Mandatory properties */ added in-game speed which is a little more obvious

{{Prototype parent|Prototype/EntityWithOwner}}
Abstract class that anything that is a belt or can connect to belts uses.

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

== Extensions ==

* [[Prototype/LinkedBelt]] '''linked-belt'''
* [[Prototype/Loader1x1]] '''loader-1x1'''
* [[Prototype/Loader1x2]] '''loader'''
* [[Prototype/Splitter]] '''splitter'''
* [[Prototype/TransportBelt]] '''transport-belt'''
* [[Prototype/UndergroundBelt]] '''underground-belt'''

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

{{Prototype property|speed|[[Types/double|double]]}}
The speed of the belt (since 0.17): <code>speed × 480 = x Items/second</code>

The raw value is expressed as the number of tiles traveled by each item on the belt per tick, relative to the belt's maximum density - e.g. <code>x items/second ÷ (4 items/lane × 2 lanes/belt × 60 ticks/second) = <speed> belts/tick</code> where a "belt" is the size of one tile. See [[Transport_belts/Physics]] for more details.

Must be a positive non-infinite number. The number is a fixed point number with 8 bits reserved for decimal precision, meaning the smallest value step is 1/2^8 = 0.00390625. In terms of speed, all speeds are multiples of 1.875 items / s, even though the entity tooltip may show a different rate.

== Optional properties ==

{{Prototype property|animation_speed_coefficient|[[Types/double|double]]|1|optional=true}}

{{Prototype property|belt_animation_set|[[Types/table|table]]|optional=true}}
Either this, or all of the properties below this one have to be present.

Table with the following properties:

* animation_set - [[Types/RotatedAnimation|RotatedAnimation]] - Mandatory.
* east_index - [[Types/uint8|uint8]] - Optional. - Default: 1
* west_index - [[Types/uint8|uint8]] - Optional. - Default: 2
* north_index - [[Types/uint8|uint8]] - Optional. - Default: 3
* south_index - [[Types/uint8|uint8]] - Optional. - Default: 4
* starting_south_index - [[Types/uint8|uint8]] - Optional. - Default: 13
* ending_south_index - [[Types/uint8|uint8]] - Optional. - Default: 14
* starting_west_index - [[Types/uint8|uint8]] - Optional. - Default: 15
* ending_west_index - [[Types/uint8|uint8]] - Optional. - Default: 16
* starting_north_index - [[Types/uint8|uint8]] - Optional. - Default: 17
* ending_north_index - [[Types/uint8|uint8]] - Optional. - Default: 18
* starting_east_index - [[Types/uint8|uint8]] - Optional. - Default: 19
* ending_east_index - [[Types/uint8|uint8]] - Optional. - Default: 20
* ending_patch - [[Types/Sprite4Way|Sprite4Way]] - Optional.
* ends_with_stopper - [[Types/bool|bool]] - Optional. - Default: false

{{Prototype property|belt_horizontal|[[Types/Animation|Animation]]|optional=true}}
Mandatory if <code>belt_animation_set</code> is not present.

{{Prototype property|belt_vertical|[[Types/Animation|Animation]]|optional=true}}
Mandatory if <code>belt_animation_set</code> is not present.

{{Prototype property|ending_top|[[Types/Animation|Animation]]|optional=true}}
Mandatory if <code>belt_animation_set</code> is not present.

{{Prototype property|ending_bottom|[[Types/Animation|Animation]]|optional=true}}
Mandatory if <code>belt_animation_set</code> is not present.

{{Prototype property|ending_side|[[Types/Animation|Animation]]|optional=true}}
Mandatory if <code>belt_animation_set</code> is not present.

{{Prototype property|starting_top|[[Types/Animation|Animation]]|optional=true}}
Mandatory if <code>belt_animation_set</code> is not present.

{{Prototype property|starting_bottom|[[Types/Animation|Animation]]|optional=true}}
Mandatory if <code>belt_animation_set</code> is not present.

{{Prototype property|starting_side|[[Types/Animation|Animation]]|optional=true}}
Mandatory if <code>belt_animation_set</code> is not present.

{{Prototype property|ending_patch|[[Types/Sprite4Way|Sprite4Way]]|optional=true}}
Always optional. Only read if <code>belt_animation_set</code> is not present.

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

== Mandatory values ==
Transport belt connectables have additional requirements for the properties inherited from [[Prototype/Entity]]:
* Transport belt connectable entities must collide with [[Types/CollisionMask#Layers|"transport-belt-layer"]].
* Transport belt connectable entities must have [[Types/CollisionMask#Collision_options|collision mask]] that collides with itself.
* Transport belt connectable entities cannot have collision mask that collides only with tiles (must collide with entities in some way).
* Transport belt connectable entities must have collision box of an appropriate minimal size, they should occupy more than half of every tile the entity covers.
* Transport belt connectable entities cannot have the [[Types/EntityPrototypeFlags#.22placeable-off-grid.22|"placeable-off-grid"]] flag specified.

Types/SpiderLegSpecification

2023-02-26T23:33:11Z

Honktown: /* leg_hit_the_ground_trigger */ position isn't in the script event, not sure about other triggers

Used by [[Types/SpiderEnginePrototype]] for [[Prototype/SpiderVehicle]].

== Mandatory properties ==
=== leg ===
'''Type''': [[Types/string|string]]

Name of a [[Prototype/SpiderLeg]].

=== mount_position ===
'''Type''': [[Types/vector|vector]]

=== ground_position ===
'''Type''': [[Types/vector|vector]]

=== blocking_legs ===
'''Type''': [[Types/table|array]] of [[Types/uint32|uint32]]

The 1-based indices of the legs that should block this leg's movement.

== Optional properties ==
=== leg_hit_the_ground_trigger ===
'''Type''': [[Types/TriggerEffect|TriggerEffect]]

For triggers, the source and target is the leg entity. Certain effects may not raise as desired, e.g. <code>"push-back"</code> does nothing, and <code>"script"</code> has leg as the source and target of the event.

Types/SpiderLegSpecification

2023-02-26T23:31:46Z

Honktown: /* leg_hit_the_ground_trigger */ little bit of details for how triggers act

Used by [[Types/SpiderEnginePrototype]] for [[Prototype/SpiderVehicle]].

== Mandatory properties ==
=== leg ===
'''Type''': [[Types/string|string]]

Name of a [[Prototype/SpiderLeg]].

=== mount_position ===
'''Type''': [[Types/vector|vector]]

=== ground_position ===
'''Type''': [[Types/vector|vector]]

=== blocking_legs ===
'''Type''': [[Types/table|array]] of [[Types/uint32|uint32]]

The 1-based indices of the legs that should block this leg's movement.

== Optional properties ==
=== leg_hit_the_ground_trigger ===
'''Type''': [[Types/TriggerEffect|TriggerEffect]]

For triggers, the source and target is the leg entity and "foot" position. Certain effects may not raise as desired, e.g. <code>"push-back"</code> does nothing, and <code>"script"</code> has leg as the source and target of the event.

Tutorial:Localisation

2023-01-07T13:38:38Z

Honktown: /* File format */ category's need not be built-ins.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Localising alternate input names ===

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

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

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

== Accessing the localised result in code ==
While usually unneeded, it is possible to read the resulting localised text in code, for example to search in localised names. See [https://lua-api.factorio.com/latest/LuaPlayer.html#LuaPlayer.request_translation LuaPlayer::request_translation] and [https://lua-api.factorio.com/latest/events.html#on_string_translated on_string_translated event].

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

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

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

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

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

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

== Scenario Name and Description ==
Scenarios have special keys, before a [category]. <code>scenario-name</code> and <code>description</code> allow for localising the name and description while selecting from a 'Start new game' scenario selector. Example from freeplay/locale/en/freeplay.cfg (msg-intro is not included because it is not special):

:scenario-name=Freeplay
:description=Your task is to launch a rocket into space. Start from nothing, work your way up with automation, and don't forget to protect yourself from the natives.\n[font=default-bold]This is the intended way of playing Factorio.[/font]

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

Types/LocalisedString

2023-01-07T05:43:56Z

Honktown: Added second paragraph, an explanation of what the localised string means in the more general context.

Localised strings are a way to support translation of in-game text. It is an array where the first element is the ''key'' and the remaining elements are parameters that will be substituted for placeholders in the template designated by the key.

When presented to a player, what appears to ''each'' player is determined by their Language (as chosen by game setting). As Language is set per-player, and Factorio must reach the same results for every player, a localised string offers a player-independent '''code''' representation. The Factorio API Docs provide the means to expose a translation, during gameplay, to everyone. Stated a different way, any place a translation is visible is not available for code to access "as it appears to be", because it would result in different outcomes for different players. The localised string provides an abstract representation, preventing inconsistencies.

The ''key'' identifies the string template. For example, "gui-alert-tooltip.attack" (for the template "__1__ objects are being damaged"; see the file data/core/locale/en.cfg). In the data stage, this key cannot be longer than 200 characters.

The template can contain placeholders such as __1__ or __2__. These will be replaced by the respective parameter in the LocalisedString. The parameters themselves can be other localised strings, which will be processed recursively in the same fashion. Localised strings cannot be recursed deeper than 20 levels and cannot have more than 20 parameters.

As a special case, when the key is just the empty string, all the parameters will be concatenated (after processing, if any are localised strings). If there is only one parameter, it will be used as is.

Furthermore, when an API function expects a localised string, it will also accept a regular string (i.e. not a table) which will not be translated, or a number or boolean which will be converted to its textual representation.

== Examples ==
In the English translation, this will print "No ammo"; in the Czech translation, it will print "Bez munice":
<syntaxhighlight lang="lua">game.player.print({"description.no-ammo"})</syntaxhighlight>
The description.no-ammo template contains no placeholders, so no further parameters are necessary.

In the English translation, this will print "Durability: 5/9"; in the Japanese one, it will print "耐久度: 5/9":
<syntaxhighlight lang="lua">game.player.print({"description.durability", 5, 9})</syntaxhighlight>

This will print "hello" in all translations:
<syntaxhighlight lang="lua">game.player.print({"", "hello"})</syntaxhighlight>

This will print "Iron plate: 60" in the English translation and "Eisenplatte: 60" in the German translation.
<syntaxhighlight lang="lua">game.print({"", {"item-name.iron-plate"}, ": ", 60})</syntaxhighlight>

== See also ==
* [https://lua-api.factorio.com/latest/Concepts.html#LocalisedString Control stage doc]
* [[Tutorial:Localisation]]

Tutorial:Localisation

2023-01-07T05:02:22Z

Honktown: /* List of built-in parameters */ detail / examples

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Localising alternate input names ===

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

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

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

== Accessing the localised result in code ==
While usually unneeded, it is possible to read the resulting localised text in code, for example to search in localised names. See [https://lua-api.factorio.com/latest/LuaPlayer.html#LuaPlayer.request_translation LuaPlayer::request_translation] and [https://lua-api.factorio.com/latest/events.html#on_string_translated on_string_translated event].

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

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

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

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

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

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

== Scenario Name and Description ==
Scenarios have special keys, before a [category]. <code>scenario-name</code> and <code>description</code> allow for localising the name and description while selecting from a 'Start new game' scenario selector. Example from freeplay/locale/en/freeplay.cfg (msg-intro is not included because it is not special):

:scenario-name=Freeplay
:description=Your task is to launch a rocket into space. Start from nothing, work your way up with automation, and don't forget to protect yourself from the natives.\n[font=default-bold]This is the intended way of playing Factorio.[/font]

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

Types/FluidBox

2022-12-26T12:04:57Z

Honktown: /* base_level */ small word change to reduce ambiguity (height of self vs where it's positioned)

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

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

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

== Mandatory properties ==

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

Max number of members is 255.

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

== Optional properties ==

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

'''Default''': 1

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

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

'''Default''': 0

Base level is the elevation of the invisible fluid box.
0 is ground level.

-1 puts the '''top''' of the fluid box at the '''bottom''' of a pipe connection, so, fluid "falls" in to it, and can't get out.

1 puts the '''bottom''' of the fluid box at the '''top''' of a pipe connection, so fluid "falls" out of it, but fluids already outside cannot get into it.

In other words:

1 = output only (and will attempt to empty as fast as possible).

-1 = input only (and will attempt to fill as fast as possible).

0 means fluids can freely flow in and out (and like a pipe, will balance to the level of the pipe next to it).

Having a -1 or 1 improperly set on an output or input, respectively, will cause issues like output fluid not leaving the building, or input fluid not entering, regardless of fluid levels in the pipe or fluid box.

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

'''Default''': 1

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

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

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

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

'''Default''': "object"

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

'''Default''': false

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

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

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

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

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

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

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

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

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

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

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

'''Default''': "None"

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

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

'''Default''': 1

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

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

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

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

== Example ==

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

Types/EnergySource

2022-12-08T17:53:40Z

Honktown: /* input_flow_limit */ small clarification

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

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

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

'''Default''': 0

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

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

'''Default''': true

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

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

'''Default''': true

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

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

Optional. How much energy the entity holds.

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

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

'''Default''': max double

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

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

'''Default''': max double

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

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

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

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

Mandatory.

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

'''Default''': 0

Optional.

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

Optional. Array of 1 or more smoke sources.

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

Optional.

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

'''Default''': 1

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

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

'''Default''': "chemical"

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

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

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

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

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

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

Mandatory. max_temperature must be >= default_temperature.

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

'''Default''': 15

Optional.

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

Mandatory.

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

Mandatory.

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

'''Default''': 1

Optional.

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

'''Default''': 15

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

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

'''Default''': 1

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

Optional.

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

Optional.

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

Optional.

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

Optional.

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

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

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

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

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

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

Optional. Array of 1 or more smoke sources.

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

Optional.

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

'''Default''': 1

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

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

'''Default''': false

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

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

'''Default''': false

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

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

'''Default''': true

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

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

'''Default''': 0

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

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

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

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

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

Types/EnergySource

2022-12-08T17:53:19Z

Honktown: /* output_flow_limit */ weird typo

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

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

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

'''Default''': 0

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

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

'''Default''': true

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

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

'''Default''': true

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

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

Optional. How much energy the entity holds.

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

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

'''Default''': max double

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

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

'''Default''': max double

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

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

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

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

Mandatory.

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

'''Default''': 0

Optional.

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

Optional. Array of 1 or more smoke sources.

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

Optional.

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

'''Default''': 1

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

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

'''Default''': "chemical"

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

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

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

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

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

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

Mandatory. max_temperature must be >= default_temperature.

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

'''Default''': 15

Optional.

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

Mandatory.

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

Mandatory.

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

'''Default''': 1

Optional.

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

'''Default''': 15

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

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

'''Default''': 1

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

Optional.

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

Optional.

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

Optional.

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

Optional.

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

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

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

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

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

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

Optional. Array of 1 or more smoke sources.

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

Optional.

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

'''Default''': 1

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

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

'''Default''': false

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

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

'''Default''': false

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

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

'''Default''': true

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

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

'''Default''': 0

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

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

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

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

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

Tutorial:Localisation

2022-12-06T01:32:48Z

Honktown: Scenario Name and Description

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==== List of built-in parameters ====
<code>name</code> is the name of a control or prototype, depending on context. <code>n</code> can be 1 or 2, it's used in parameters that control [[#Localising_alternate_input_names|alternate input names]].
* <code>__CONTROL__name__</code>
* <code>__CONTROL_MODIFIER__name__</code>
* <code>__CONTROL_STYLE_BEGIN__</code>
* <code>__CONTROL_STYLE_END__</code>
* <code>__CONTROL_LEFT_CLICK__</code> is replaced with <code>control-keys.mouse-button-1</code> or <code>control-keys.controller-b</code>[https://crowdin.com/project/factorio/discussions/214]
* <code>__CONTROL_RIGHT_CLICK__</code> is replaced with <code>control-keys.mouse-button-2</code> or <code>control-keys.controller-x</code>
* <code>__CONTROL_KEY_SHIFT__</code> is replaced with <code>control-keys.shift</code> or <code>control-keys.controller-leftshoulder</code>
* <code>__CONTROL_KEY_CTRL__</code> is replaced with <code>control-keys.control</code> or <code>control-keys.controller-rightshoulder</code>
* <code>__ALT_CONTROL_LEFT_CLICK__n__</code> is replaced with <code>control-keys.mouse-button-1-alt-n</code> or <code>control-keys.controller-button-alt-n</code> (with parameter <code>control-keys.controller-b</code>)
* <code>__ALT_CONTROL_RIGHT_CLICK__n__</code> is replaced with <code>control-keys.mouse-button-2-alt-n</code> or <code>control-keys.controller-button-alt-n</code> (with parameter <code>control-keys.controller-x</code>)
* <code>__REMARK_COLOR_BEGIN__</code>
* <code>__REMARK_COLOR_END__</code>
* <code>__ALT_CONTROL__n__name__</code>
* <code>__CONTROL_MOVE__</code>
* <code>__ENTITY__name__</code>
* <code>__ITEM__name__</code>
* <code>__TILE__name__</code>
* <code>__FLUID__name__</code>

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

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

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

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

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

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

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

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

=== Localising alternate input names ===

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

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

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

== Accessing the localised result in code ==
While usually unneeded, it is possible to read the resulting localised text in code, for example to search in localised names. See [https://lua-api.factorio.com/latest/LuaPlayer.html#LuaPlayer.request_translation LuaPlayer::request_translation] and [https://lua-api.factorio.com/latest/events.html#on_string_translated on_string_translated event].

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

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

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

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

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

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

== Scenario Name and Description ==
Scenarios have special keys, before a [category]. <code>scenario-name</code> and <code>description</code> allow for localising the name and description while selecting from a 'Start new game' scenario selector. Example from freeplay/locale/en/freeplay.cfg (msg-intro is not included because it is not special):

:scenario-name=Freeplay
:description=Your task is to launch a rocket into space. Start from nothing, work your way up with automation, and don't forget to protect yourself from the natives.\n[font=default-bold]This is the intended way of playing Factorio.[/font]

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

Tutorial:Mod structure

2022-11-12T08:31:25Z

Honktown: /* dependencies */ indent -1 to Dependency section

{{Languages}}Mods are expected to have a certain structure in order to be loaded by the game. This page aims to explain that file structure and what each file is used for.

== Mod folder and file structure ==

The mod must either be in a folder, or in a folder inside a zip file. The mod folder (no zip file) must either be named in the pattern of <code>{mod-name}_{version-number}</code> or just <code>{mod-name}</code>, for example <code>test-mod-thing</code>. The mod zip must be named in the pattern of <code>{mod-name}_{version-number}</code>, for example <code>test-mod-thing_0.0.1</code>. When using a zip file for the mod, the folder inside the zip file does not have any naming restrictions; only the zip file itself must be named with the <code>{mod-name}_{version-number}</code> pattern. The mod name and its version number are defined in the [[#info.json|info.json]] file.

=== Files ===
Inside the mod folder, the game automatically reads the following files during load:
* info.json — The only mandatory file. The [[#info.json|info.json]] identifies the mod, defines its version and other general properties.
* changelog.txt — Version history of the mod, to be shown in the mod browser. The changelog file must follow the strict [[Tutorial:Mod changelog format|formatting requirements]].
* thumbnail.png — Thumbnail to be shown on the mod portal and in the mod browser in-game. Ideally a 144x144px image file.
* settings.lua — This and the next two files are used to set up mod [[Tutorial:Mod settings|configuration options]].
* settings-updates.lua
* settings-final-fixes.lua
* data.lua — This and the next two files are used to define [[Prototype definitions|prototypes]].
* data-updates.lua — The load order of the three data*.lua files is explained on [https://lua-api.factorio.com/latest/Data-Lifecycle.html Data-Lifecycle].
* data-final-fixes.lua
* control.lua — This file is used for runtime scripting. Runtime scripting is documented on [https://lua-api.factorio.com/latest/index.html lua-api.factorio.com].

=== Subfolders ===
Furthermore, the following folders inside the mod folder are recognized by the game:
* locale — Can contain up to one subfolder per language, identified with the language code, for example <code>en</code> for English. The subfolder then has to contain at least one *.cfg file which defines the [[Tutorial:Localisation|translations]] for that language.
* scenarios — Custom [[scenario system|scenarios]] can be placed in subfolders of this folder.
* campaigns — Custom campaigns can be placed in subfolders of this folder.
* tutorials — Custom [[Prototype/Tutorial|tutorials]] can be placed in subfolders of this folder.
* migrations — [https://lua-api.factorio.com/latest/Migrations.html Migration files] are placed in this folder. They are a way to handle prototype changes and mod data structure changes between mod versions or game versions.

=== Example ===
Here is an example directory structure for a mod titled <code>my-armor-mod</code> with a version number of <code>0.3.6</code>:

<pre>
my-armor-mod_0.3.6.zip
|- aFolderName/
|- control.lua
|- data.lua
|- info.json
|- thumbnail.png
</pre>

== info.json ==

The info.json file identifies the mod and defines its version. If the game encounters a problem when parsing the file, the error message can be found in the [[log file]]. A minimal info.json file can look like this:
{
"name": "test-mod-thing",
"version": "0.0.1",
"title": "My best test mod",
"author": "A very great tester",
"factorio_version": "1.1",
"dependencies": ["? optional-mod"]
}

The info.json file supports the following fields:

=== name ===
: '''Type''': [[Types/string|string]]

: Mandatory field. The internal name of mod. The game accepts anything as a mod name, however the mod portal restricts mod names to only consist of alphanumeric characters, dashes and underscores. Note that the mod folder or mod zip file name has to contain the mod name, where the restrictions of the file system apply.

: The game accepts mod names with a maximum length of 100 characters. The mod portal only accepts mods with names that are longer than 3 characters and shorter than 50 characters.

=== version ===
: '''Type''': [[Types/string|string]]

: Mandatory field. Defines the version of the mod in the format <code>"number.number.number"</code> for <code>"Major.Middle.Minor"</code>, for example <code>"0.6.4"</code>. Each number can range from 0 to 65535.

=== title ===
: '''Type''': [[Types/string|string]]

: Mandatory field. The display name of the mod, so it is not recommended to use someUgly_pRoGrAmMeR-name here. Can be overwritten with a locale entry in the <code>mod-name</code> category, using the internal mod name as the key.

: The game will reject a title field that is longer than 100 characters. However, this can be worked around by using the locale entry. The mod portal does not restrict mod title length.

=== author ===
: '''Type''': [[Types/string|string]]

: Mandatory field. The author of the mod. This field does not have restrictions, it can also be a list of authors etc. The mod portal ignores this field, it will simply display the uploader's name as the author.

=== contact ===
: '''Type''': [[Types/string|string]]

: Optional field. How the mod author can be contacted, for example an email address.

=== homepage ===
: '''Type''': [[Types/string|string]]

: Optional field. Where the mod can be found on the internet. Note that the in-game mod browser shows the mod portal link additionally to this field. Please don't put "None" here, it makes the field on the mod portal website look ugly. Just leave the field empty if the mod doesn't have a website/forum thread/discord.

=== description ===
: '''Type''': [[Types/string|string]]

: Optional field. A short description of what your mod does. This is all that people get to see in-game. Can be overwritten with a locale entry in the <code>mod-description</code> category, using the internal mod name as the key.

=== factorio_version ===
: '''Type''': [[Types/string|string]]

: '''Default''': "0.12"

: Optional field. The Factorio version <code>Major.Middle</code> that this mod supports. This can only be one Factorio version, not multiple. ''However'', it includes all <code>.Minor</code> versions. While the field is optional, usually mods are developed for versions higher than the default 0.12, so the field has to be added anyway.

: Adding a Minor part, e.g. "0.18.'''27'''" will make the mod portal reject the mod and the game act weirdly. That means this shouldn't be done; use only the Major and Middle components <code>"Major.Middle"</code>, for example <code>"1.0"</code>.

: Mods with the factorio_version "0.18" can also be loaded in 1.0 and the mod portal will return them when queried for factorio_version 1.0 mods.

=== dependencies ===
: '''Type''': array of [[#Dependency]]

: '''Default''': ["base"]

: Optional field. Mods that this mod depends on or is incompatible with. If this mod depends on another, the other mod will load first, see [https://lua-api.factorio.com/latest/Data-Lifecycle.html Data-Lifecycle]. An empty array allows get around the default and have no dependencies at all.

: Example:
: <pre>"dependencies": ["mod-a", "? mod-c > 0.4.3", "! mod-g"]</pre>

: <h4>Dependency</h4>
: Each dependency is a string that consists of up to three parts: <code>"<prefix> internal-mod-name <equality-operator version>"</code>, for example <code>"? some-mod-everyone-loves >= 4.2.0"</code>.

:The equality operator (<code><, <=, =, >= or ></code>) combined with the version allows to define dependencies that require certain mod versions, but it is not required. Incompatibility does not support versions; if incompatibility is used, version is ignored.

:The possible prefixes are:
::<code>!</code> for incompatibility
::<code>?</code> for an optional dependency
::<code>(?)</code> for a hidden optional dependency
::<code>~</code> for a dependency that does not affect load order, or no prefix for a hard requirement for the other mod.

Tutorial:Mod structure

2022-11-12T08:26:24Z

Honktown: /* factorio_version */ Major Middle Minor naming for factorio_version, and some editing

{{Languages}}Mods are expected to have a certain structure in order to be loaded by the game. This page aims to explain that file structure and what each file is used for.

== Mod folder and file structure ==

The mod must either be in a folder, or in a folder inside a zip file. The mod folder (no zip file) must either be named in the pattern of <code>{mod-name}_{version-number}</code> or just <code>{mod-name}</code>, for example <code>test-mod-thing</code>. The mod zip must be named in the pattern of <code>{mod-name}_{version-number}</code>, for example <code>test-mod-thing_0.0.1</code>. When using a zip file for the mod, the folder inside the zip file does not have any naming restrictions; only the zip file itself must be named with the <code>{mod-name}_{version-number}</code> pattern. The mod name and its version number are defined in the [[#info.json|info.json]] file.

=== Files ===
Inside the mod folder, the game automatically reads the following files during load:
* info.json — The only mandatory file. The [[#info.json|info.json]] identifies the mod, defines its version and other general properties.
* changelog.txt — Version history of the mod, to be shown in the mod browser. The changelog file must follow the strict [[Tutorial:Mod changelog format|formatting requirements]].
* thumbnail.png — Thumbnail to be shown on the mod portal and in the mod browser in-game. Ideally a 144x144px image file.
* settings.lua — This and the next two files are used to set up mod [[Tutorial:Mod settings|configuration options]].
* settings-updates.lua
* settings-final-fixes.lua
* data.lua — This and the next two files are used to define [[Prototype definitions|prototypes]].
* data-updates.lua — The load order of the three data*.lua files is explained on [https://lua-api.factorio.com/latest/Data-Lifecycle.html Data-Lifecycle].
* data-final-fixes.lua
* control.lua — This file is used for runtime scripting. Runtime scripting is documented on [https://lua-api.factorio.com/latest/index.html lua-api.factorio.com].

=== Subfolders ===
Furthermore, the following folders inside the mod folder are recognized by the game:
* locale — Can contain up to one subfolder per language, identified with the language code, for example <code>en</code> for English. The subfolder then has to contain at least one *.cfg file which defines the [[Tutorial:Localisation|translations]] for that language.
* scenarios — Custom [[scenario system|scenarios]] can be placed in subfolders of this folder.
* campaigns — Custom campaigns can be placed in subfolders of this folder.
* tutorials — Custom [[Prototype/Tutorial|tutorials]] can be placed in subfolders of this folder.
* migrations — [https://lua-api.factorio.com/latest/Migrations.html Migration files] are placed in this folder. They are a way to handle prototype changes and mod data structure changes between mod versions or game versions.

=== Example ===
Here is an example directory structure for a mod titled <code>my-armor-mod</code> with a version number of <code>0.3.6</code>:

<pre>
my-armor-mod_0.3.6.zip
|- aFolderName/
|- control.lua
|- data.lua
|- info.json
|- thumbnail.png
</pre>

== info.json ==

The info.json file identifies the mod and defines its version. If the game encounters a problem when parsing the file, the error message can be found in the [[log file]]. A minimal info.json file can look like this:
{
"name": "test-mod-thing",
"version": "0.0.1",
"title": "My best test mod",
"author": "A very great tester",
"factorio_version": "1.1",
"dependencies": ["? optional-mod"]
}

The info.json file supports the following fields:

=== name ===
: '''Type''': [[Types/string|string]]

: Mandatory field. The internal name of mod. The game accepts anything as a mod name, however the mod portal restricts mod names to only consist of alphanumeric characters, dashes and underscores. Note that the mod folder or mod zip file name has to contain the mod name, where the restrictions of the file system apply.

: The game accepts mod names with a maximum length of 100 characters. The mod portal only accepts mods with names that are longer than 3 characters and shorter than 50 characters.

=== version ===
: '''Type''': [[Types/string|string]]

: Mandatory field. Defines the version of the mod in the format <code>"number.number.number"</code> for <code>"Major.Middle.Minor"</code>, for example <code>"0.6.4"</code>. Each number can range from 0 to 65535.

=== title ===
: '''Type''': [[Types/string|string]]

: Mandatory field. The display name of the mod, so it is not recommended to use someUgly_pRoGrAmMeR-name here. Can be overwritten with a locale entry in the <code>mod-name</code> category, using the internal mod name as the key.

: The game will reject a title field that is longer than 100 characters. However, this can be worked around by using the locale entry. The mod portal does not restrict mod title length.

=== author ===
: '''Type''': [[Types/string|string]]

: Mandatory field. The author of the mod. This field does not have restrictions, it can also be a list of authors etc. The mod portal ignores this field, it will simply display the uploader's name as the author.

=== contact ===
: '''Type''': [[Types/string|string]]

: Optional field. How the mod author can be contacted, for example an email address.

=== homepage ===
: '''Type''': [[Types/string|string]]

: Optional field. Where the mod can be found on the internet. Note that the in-game mod browser shows the mod portal link additionally to this field. Please don't put "None" here, it makes the field on the mod portal website look ugly. Just leave the field empty if the mod doesn't have a website/forum thread/discord.

=== description ===
: '''Type''': [[Types/string|string]]

: Optional field. A short description of what your mod does. This is all that people get to see in-game. Can be overwritten with a locale entry in the <code>mod-description</code> category, using the internal mod name as the key.

=== factorio_version ===
: '''Type''': [[Types/string|string]]

: '''Default''': "0.12"

: Optional field. The Factorio version <code>Major.Middle</code> that this mod supports. This can only be one Factorio version, not multiple. ''However'', it includes all <code>.Minor</code> versions. While the field is optional, usually mods are developed for versions higher than the default 0.12, so the field has to be added anyway.

: Adding a Minor part, e.g. "0.18.'''27'''" will make the mod portal reject the mod and the game act weirdly. That means this shouldn't be done; use only the Major and Middle components <code>"Major.Middle"</code>, for example <code>"1.0"</code>.

: Mods with the factorio_version "0.18" can also be loaded in 1.0 and the mod portal will return them when queried for factorio_version 1.0 mods.

=== dependencies ===
: '''Type''': array of [[#Dependency]]

: '''Default''': ["base"]

: Optional field. Mods that this mod depends on or is incompatible with. If this mod depends on another, the other mod will load first, see [https://lua-api.factorio.com/latest/Data-Lifecycle.html Data-Lifecycle]. An empty array allows get around the default and have no dependencies at all.

: Example:
: <pre>"dependencies": ["mod-a", "? mod-c > 0.4.3", "! mod-g"]</pre>

:: <h4>Dependency</h4>
:: Each dependency is a string that consists of up to three parts: <code>"<prefix> internal-mod-name <equality-operator version>"</code>, for example <code>"? some-mod-everyone-loves >= 4.2.0"</code>.

::The equality operator (<code><, <=, =, >= or ></code>) combined with the version allows to define dependencies that require certain mod versions, but it is not required. Incompatibility does not support versions; if incompatibility is used, version is ignored.

::The possible prefixes are:
:::<code>!</code> for incompatibility
:::<code>?</code> for an optional dependency
:::<code>(?)</code> for a hidden optional dependency
:::<code>~</code> for a dependency that does not affect load order, or no prefix for a hard requirement for the other mod.

Prototype/Recipe

2022-11-09T09:54:35Z

Honktown: /* Recipe data */ text mistake

{{Prototype parent|PrototypeBase}}
A recipe. It can be a crafting recipe, a smelting recipe, or a custom type of recipe (see [[Prototype/RecipeCategory]]).

{{Prototype TOC|recipe}}

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

{{Prototype property|category|[[Types/string|string]]|"crafting"|optional=true}}
Optional. The category of this recipe. The built-in categories can be found [[Data.raw#recipe-category|here]]. See also [[Prototype/RecipeCategory]].

The recipe category "crafting" cannot contain recipes with fluid ingredients or products.

{{Prototype property|subgroup|[[Types/string|string]]||optional=true}}
Optional. The subgroup of this recipe. If not specified, defaults to the subgroup of the product if there is only 1, or main_product if multiple products exist. If multiple products exist and no main_product is specified, the subgroup is required.

{{Prototype property|icons, icon, icon_size (IconSpecification)|[[Types/IconSpecification|IconSpecification]]|optional=true}}
An icon is mandatory for recipe with more than 1 product and no main_product. Otherwise defaults to the icon of main_product/1 product.

If given, it overwrites the icon of the main_product/1 product.

{{Prototype property|crafting_machine_tint|[[Types/table|table]] of [[Types/Color|Color]]|optional=true}}
Optional. Used by crafting machine <code>[[Prototype/CraftingMachine#working_visualisations|working_visualisations]]</code> to tint certain layers with the recipe color. [[Types/WorkingVisualisation#apply_recipe_tint|apply_recipe_tint]] on the working visualisation determines which of the 4 colors is used for that layer (if any).

Format:
<syntaxhighlight lang="lua">crafting_machine_tint = { primary = {r=0,g=0,b=0,a=0}, secondary = {r=0,g=0,b=0,a=0}, tertiary = {r=0,g=0,b=0,a=0}, quaternary = {r=0,g=0,b=0,a=0}}</syntaxhighlight>

Each key/value pair is optional and defaults to the above value.

== Recipe data ==
{{#subobject:normal
|Prototype property name=normal
|Prototype property type=[[Prototype/Recipe#Recipe_data|Recipe data]] or [[Types/bool|bool]]
|Prototype property optional=true
|Prototype property pagename={{FULLPAGENAME}}
}}{{#subobject:expensive
|Prototype property name=expensive
|Prototype property type=[[Prototype/Recipe#Recipe_data|Recipe data]] or [[Types/bool|bool]]
|Prototype property optional=true
|Prototype property pagename={{FULLPAGENAME}}
}}
If the recipe does not have a difficulty, this is located directly in the prototype. Otherwise, if the "'''normal'''" or "'''expensive'''" property exists, the recipe has difficulty. Then, the recipe data has to be specified for each difficulty instead of directly in the prototype. If at least one difficulty has recipe data defined, the other difficulty can be set to <code>false</code>. This will disable the recipe for the difficulty, same as setting it <code>enabled = false</code>. If it is enabled (by technologies etc), it will use the data from the other difficulty. Not setting a difficulty, e.g. <code>normal = nil</code>, is possible and gives that difficulty the exact same properties as the difficulty that is defined. Setting one or both difficulties to <code>true</code> is not valid and will produce an error. See below for examples of difficulty.

{{Prototype property|ingredients|[[Types/table|table]] of [[Types/IngredientPrototype|IngredientPrototype]]}}
A table containing ingredient names and counts. Can also contain information about fluid temperature and catalyst amounts. The catalyst amounts are automatically calculated from the recipe, or can be set manually in the [[Types/IngredientPrototype|IngredientPrototype]].[https://factorio.com/blog/post/fff-256] 
Maximum ingredient amount is 65535. 
<code>ingredients</code> can be set to an empty table to create a recipe that needs no ingredients. 
Duplicate ingredients, e.g. two entries for the "wood" item, are ''not'' allowed. 
In-game, the item ingredients are ordered by [[Prototype/ItemGroup#order_in_recipe|item group order_in_recipe]].
<syntaxhighlight lang="lua">
ingredients = {{"iron-stick", 2}, {"iron-plate", 3}}
</syntaxhighlight>
The same with full format:
<syntaxhighlight lang="lua">
ingredients = {{type = "item", name = "iron-stick", amount = 2}, {type = "item", name = "iron-plate", amount = 3}}
</syntaxhighlight>
For fluids, the full format always has to be used:
<syntaxhighlight lang="lua">
ingredients = {{type="fluid", name="water", amount=50}, {type="fluid", name="crude-oil", amount=100}}
</syntaxhighlight>

{{Prototype property|result|[[Types/string|string]]|optional=true}}
Can be replaced with the results parameter. The item created by this recipe. Must be the name of an item, such as "iron-gear-wheel".
Note that <code>results</code> takes priority over <code>result</code>. So if a recipe has both keys set, <code>result</code> will be ignored. 

{{Prototype property|result_count|[[Types/uint32|uint32]]|1|optional=true}}
Optional. The number of items created by this recipe.

{{Prototype property|results|[[Types/table|table]] of [[Types/ProductPrototype|ProductPrototype]]|optional=true}}
A table containing result names and counts. Can also contain information about fluid temperature and catalyst amounts. The catalyst amounts are automatically calculated from the recipe, or can be set manually in the [[Types/ProductPrototype|ProductPrototype]].[https://factorio.com/blog/post/fff-256] 
<code>results</code> can be set to an empty table to create a recipe that produces nothing. 
Duplicate results, e.g. two entries for the "iron-plate" item, are allowed.

<syntaxhighlight lang="lua">
results=
{
{type="fluid", name="heavy-oil", amount=3},
{type="fluid", name="light-oil", amount=3},
{type="fluid", name="petroleum-gas", amount=4}
},
</syntaxhighlight>
<syntaxhighlight lang="lua">
results =
{
{type = "item", name = "iron-nuggets", amount = 9},
{type = "item", name = "gold-nuggets", amount = 1}
},
</syntaxhighlight>
<syntaxhighlight lang="lua">
results =
{
{type = "fluid", name = "steam", amount = 1, temperature = 165}
},
</syntaxhighlight>

{{Prototype property|energy_required|[[Types/double|double]]|0.5|optional=true}}
Optional. The amount of time it takes to make this recipe. Must be greater than 0.001.

This is the number of seconds it takes to craft at crafting speed 1.

{{Prototype property|emissions_multiplier|[[Types/double|double]]|1.0|optional=true}}

{{Prototype property|requester_paste_multiplier|[[Types/uint32|uint32]]|30|optional=true}}

{{Prototype property|overload_multiplier|[[Types/uint32|uint32]]|0|optional=true}}
Used to determine how many extra items are put into an assembling machine before it's considered "full enough". See [[Inserters#Insertion_limits]].

If set to 0, it instead uses the following formula: 1.166 / (energy_required / the assembler's crafting_speed), rounded up, and clamped between 2 and 100. The numbers used in this formula can be changed by the [[Prototype/UtilityConstants]] dynamic_recipe_overload_factor, minimum_recipe_overload_multiplier and maximum_recipe_overload_multiplier.

{{Prototype property|allow_inserter_overload|[[Types/bool|bool]]|true|optional=true}}
If the recipe is allowed to have the extra inserter overload bonus applied (4 * stack inserter stack size).

{{Prototype property|enabled|[[Types/bool|bool]]|true|optional=true}}
Optional. This can be false to disable the recipe at the start of the game, or "true" to leave it enabled.

If your recipe is unlocked by a technology, you should set this to "false".

{{Prototype property|hidden|[[Types/bool|bool]]|false|optional=true}}
Optional. Hides the recipe from crafting menus.

{{Prototype property|hide_from_stats|[[Types/bool|bool]]|false|optional=true}}
Optional. Hides the recipe from flow stats (item/fluid production statistics).

{{Prototype property|hide_from_player_crafting|[[Types/bool|bool]]|false|optional=true}}
Optional. Hides the recipe from the player's crafting screen. The recipe will still show up for selection in machines.

{{Prototype property|allow_decomposition|[[Types/bool|bool]]|true|optional=true}}
Optional. Whether this recipe is allowed to be broken down for the recipe tooltip "Total raw" calculations.

{{Prototype property|allow_as_intermediate|[[Types/bool|bool]]|true|optional=true}}
Optional. Whether the recipe can be used as an intermediate recipe in hand-crafting.

{{Prototype property|allow_intermediates|[[Types/bool|bool]]|true|optional=true}}
Optional. Whether the recipe is allowed to use intermediate recipes when hand-crafting.

{{Prototype property|always_show_made_in|[[Types/bool|bool]]|false|optional=true}}
Optional. Whether the "Made in: {Machine}" part of the tool-tip should always be present, not only when the recipe can not be hand-crafted.

{{Prototype property|show_amount_in_title|[[Types/bool|bool]]|true|optional=true}}
Optional. Whether the recipe name should have the product amount in front of it, e.g. "2 [[transport belt]]"

{{Prototype property|always_show_products|[[Types/bool|bool]]|false|optional=true}}
Optional. Whether the products are always shown in the recipe tool-tip.

{{Prototype property|unlock_results|[[Types/bool|bool]]|true|optional=true}}
Optional. Whether enabling this recipe unlocks its item products to show in selection lists (item filter, logistic request etc.).

{{Prototype property|main_product|[[Types/string|string]]|optional=true}}
Optional.

For recipes with more than one product: This defines of which result the icon, subgroup and name is used. If it is not set and the recipe has more than 1 result the recipe will use the recipe-name and recipe-description locale and its own subgroup and icon.

For recipes with 1 result: The recipe uses the icon, subgroup and name of the result by default. If this property is set to an empty string, the recipe will use the properties of the recipe instead of the result.

== Examples ==

=== "iron-plate" ===
<syntaxhighlight lang="lua">
{
type = "recipe",
name = "iron-plate",
category = "smelting",
energy_required = 3.5,
ingredients = {{"iron-ore", 1}},
result = "iron-plate"
}</syntaxhighlight>

=== "coal-liquefaction" ===

<syntaxhighlight lang="lua">{
type = "recipe",
name = "coal-liquefaction",
category = "oil-processing",
subgroup = "fluid-recipes",
order = "a[oil-processing]-c[coal-liquefaction]",
enabled = false,
energy_required = 5,
icon = "__base__/graphics/icons/fluid/coal-liquefaction.png",
icon_size = 32,
ingredients =
{
{type="item", name="coal", amount=10},
{type="fluid", name="heavy-oil", amount=25},
{type="fluid", name="steam", amount=50}
},
results=
{
{type="fluid", name="heavy-oil", amount=35},
{type="fluid", name="light-oil", amount=15},
{type="fluid", name="petroleum-gas", amount=20}
},
allow_decomposition = false
}</syntaxhighlight>

=== "iron-gear-wheel" — recipe with difficulty ===
<syntaxhighlight lang="lua"> {
type = "recipe",
name = "iron-gear-wheel",
normal =
{
ingredients = {{"iron-plate", 2}},
result = "iron-gear-wheel"
},
expensive =
{
ingredients = {{"iron-plate", 4}},
result = "iron-gear-wheel"
}
},</syntaxhighlight>

==== Modified so that it cannot be crafted in normal mode, unless unlocked via command/research ====
<syntaxhighlight lang="lua"> {
type = "recipe",
name = "iron-gear-wheel",
normal = false,
expensive =
{
ingredients = {{"iron-plate", 4}},
result = "iron-gear-wheel"
}
},</syntaxhighlight>

==== Modified so that the expensive recipe is always used, even in normal mode ====
<syntaxhighlight lang="lua"> {
type = "recipe",
name = "iron-gear-wheel",
normal = nil, --this line can be omitted
expensive =
{
ingredients = {{"iron-plate", 4}},
result = "iron-gear-wheel"
}
},</syntaxhighlight>

Tutorial:Localisation

2022-11-06T18:42:11Z

Honktown: /* Default Behavior(s) for finding an Unspecified Localised String */ bad locale category [setting-description] -> [mod-setting-description]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==== List of built-in parameters ====
<code>name</code> is the name of a control or prototype, depending on context. <code>n</code> can be 1 or 2, it's used in parameters that control [[#Localising_alternate_input_names|alternate input names]].
* <code>__CONTROL__name__</code>
* <code>__CONTROL_MODIFIER__name__</code>
* <code>__CONTROL_STYLE_BEGIN__</code>
* <code>__CONTROL_STYLE_END__</code>
* <code>__CONTROL_LEFT_CLICK__</code> is replaced with <code>control-keys.mouse-button-1</code> or <code>control-keys.controller-b</code>[https://crowdin.com/project/factorio/discussions/214]
* <code>__CONTROL_RIGHT_CLICK__</code> is replaced with <code>control-keys.mouse-button-2</code> or <code>control-keys.controller-x</code>
* <code>__CONTROL_KEY_SHIFT__</code> is replaced with <code>control-keys.mouse-button-2</code> or <code>control-keys.controller-x</code>
* <code>__CONTROL_KEY_CTRL__</code> is replaced with <code>control-keys.mouse-button-2</code> or <code>control-keys.controller-x</code>
* <code>__ALT_CONTROL_LEFT_CLICK__n__</code> is replaced with <code>control-keys.mouse-button-1-alt-n</code> or <code>control-keys.controller-button-alt-n</code> (with parameter <code>control-keys.controller-b</code>)
* <code>__ALT_CONTROL_RIGHT_CLICK__n__</code> is replaced with <code>control-keys.mouse-button-2-alt-n</code> or <code>control-keys.controller-button-alt-n</code> (with parameter <code>control-keys.controller-x</code>)
* <code>__REMARK_COLOR_BEGIN__</code>
* <code>__REMARK_COLOR_END__</code>
* <code>__ALT_CONTROL__n__name__</code>
* <code>__CONTROL_MOVE__</code>
* <code>__ENTITY__name__</code>
* <code>__ITEM__name__</code>
* <code>__TILE__name__</code>
* <code>__FLUID__name__</code>

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

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

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

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

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

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

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

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

=== Localising alternate input names ===

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

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

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

== Accessing the localised result in code ==
While usually unneeded, it is possible to read the resulting localised text in code, for example to search in localised names. See [https://lua-api.factorio.com/latest/LuaPlayer.html#LuaPlayer.request_translation LuaPlayer::request_translation] and [https://lua-api.factorio.com/latest/events.html#on_string_translated on_string_translated event].

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

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

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

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

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

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

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

Tutorial:Mod structure

2022-11-03T04:47:43Z

Honktown: /* dependencies */ re-format text for readability. Minor rephrasing of incompatibility and versions.

{{Languages}}Mods are expected to have a certain structure in order to be loaded by the game. This page aims to explain that file structure and what each file is used for.

== Mod folder and file structure ==

The mod must either be in a folder, or in a folder inside a zip file. The mod folder (no zip file) must either be named in the pattern of <code>{mod-name}_{version-number}</code> or just <code>{mod-name}</code>, for example <code>test-mod-thing</code>. The mod zip must be named in the pattern of <code>{mod-name}_{version-number}</code>, for example <code>test-mod-thing_0.0.1</code>. When using a zip file for the mod, the folder inside the zip file does not have any naming restrictions; only the zip file itself must be named with the <code>{mod-name}_{version-number}</code> pattern. The mod name and its version number are defined in the [[#info.json|info.json]] file.

=== Files ===
Inside the mod folder, the game automatically reads the following files during load:
* info.json — The only mandatory file. The [[#info.json|info.json]] identifies the mod, defines its version and other general properties.
* changelog.txt — Version history of the mod, to be shown in the mod browser. The changelog file must follow the strict [https://forums.factorio.com/viewtopic.php?t=67140 formatting requirements].
* thumbnail.png — Thumbnail to be shown on the mod portal and in the mod browser in-game. Ideally a 144x144px image file.
* settings.lua — This and the next two files are used to set up mod [[Tutorial:Mod settings|configuration options]].
* settings-updates.lua
* settings-final-fixes.lua
* data.lua — This and the next two files are used to define [[Prototype definitions|prototypes]].
* data-updates.lua — The load order of the three data*.lua files is explained on [https://lua-api.factorio.com/latest/Data-Lifecycle.html Data-Lifecycle].
* data-final-fixes.lua
* control.lua — This file is used for runtime scripting. Runtime scripting is documented on [https://lua-api.factorio.com/latest/index.html lua-api.factorio.com].

=== Subfolders ===
Furthermore, the following folders inside the mod folder are recognized by the game:
* locale — Can contain up to one subfolder per language, identified with the language code, for example <code>en</code> for English. The subfolder then has to contain at least one *.cfg file which defines the [[Tutorial:Localisation|translations]] for that language.
* scenarios — Custom [[scenario system|scenarios]] can be placed in subfolders of this folder.
* campaigns — Custom campaigns can be placed in subfolders of this folder.
* tutorials — Custom [[Prototype/Tutorial|tutorials]] can be placed in subfolders of this folder.
* migrations — [https://lua-api.factorio.com/latest/Migrations.html Migration files] are placed in this folder. They are a way to handle prototype changes and mod data structure changes between mod versions or game versions.

=== Example ===
Here is an example directory structure for a mod titled <code>my-armor-mod</code> with a version number of <code>0.3.6</code>:

<pre>
my-armor-mod_0.3.6.zip
|- aFolderName/
|- control.lua
|- data.lua
|- info.json
|- thumbnail.png
</pre>

== info.json ==

The info.json file identifies the mod and defines its version. If the game encounters a problem when parsing the file, the error message can be found in the [[log file]]. A minimal info.json file can look like this:
{
"name": "test-mod-thing",
"version": "0.0.1",
"title": "My best test mod",
"author": "A very great tester",
"factorio_version": "1.1",
"dependencies": ["? optional-mod"]
}

The info.json file supports the following fields:

=== name ===
: '''Type''': [[Types/string|string]]

: Mandatory field. The internal name of mod. The game accepts anything as a mod name, however the mod portal restricts mod names to only consist of alphanumeric characters, dashes and underscores. Note that the mod folder or mod zip file name has to contain the mod name, where the restrictions of the file system apply.

: The game accepts mod names with a maximum length of 100 characters. The mod portal only accepts mods with names that are longer than 3 characters and shorter than 50 characters.

=== version ===
: '''Type''': [[Types/string|string]]

: Mandatory field. Defines the version of the mod in the format <code>"number.number.number"</code> for <code>"main.major.minor"</code>, for example <code>"0.6.4"</code>. Each number can range from 0 to 65535.

=== title ===
: '''Type''': [[Types/string|string]]

: Mandatory field. The display name of the mod, so it is not recommended to use someUgly_pRoGrAmMeR-name here. Can be overwritten with a locale entry in the <code>mod-name</code> category, using the internal mod name as the key.

: The game will reject a title field that is longer than 100 characters. However, this can be worked around by using the locale entry. The mod portal does not restrict mod title length.

=== author ===
: '''Type''': [[Types/string|string]]

: Mandatory field. The author of the mod. This field does not have restrictions, it can also be a list of authors etc. The mod portal ignores this field, it will simply display the uploader's name as the author.

=== contact ===
: '''Type''': [[Types/string|string]]

: Optional field. How the mod author can be contacted, for example an email address.

=== homepage ===
: '''Type''': [[Types/string|string]]

: Optional field. Where the mod can be found on the internet. Note that the in-game mod browser shows the mod portal link additionally to this field. Please don't put "None" here, it makes the field on the mod portal website look ugly. Just leave the field empty if the mod doesn't have a website/forum thread/discord.

=== description ===
: '''Type''': [[Types/string|string]]

: Optional field. A short description of what your mod does. This is all that people get to see in-game. Can be overwritten with a locale entry in the <code>mod-description</code> category, using the internal mod name as the key.

=== factorio_version ===
: '''Type''': [[Types/string|string]]

: '''Default''': "0.12"

: Optional field. The major Factorio version that this mod supports. This can only be one version, not multiple. While the field is optional, usually mods are developed for major versions higher than the default 0.12, so the field has to be added anyway.
: Adding a minor version, e.g. "0.18.'''27'''" will make the mod portal reject the mod and the game act weirdly. That means this shouldn't be done; use only main and major version <code>"main.major"</code>, for example <code>"1.0"</code>.
: Mods with the factorio_version "0.18" can also be loaded in 1.0 and the mod portal will return them when queried for factorio_version 1.0 mods.

=== dependencies ===
: '''Type''': array of [[#Dependency]]

: '''Default''': ["base"]

: Optional field. Mods that this mod depends on or is incompatible with. If this mod depends on another, the other mod will load first, see [https://lua-api.factorio.com/latest/Data-Lifecycle.html Data-Lifecycle]. An empty array allows get around the default and have no dependencies at all.

: Example:
: <pre>"dependencies": ["mod-a", "? mod-c > 0.4.3", "! mod-g"]</pre>

:: <h4>Dependency</h4>
:: Each dependency is a string that consists of up to three parts: <code>"<prefix> internal-mod-name <equality-operator version>"</code>, for example <code>"? some-mod-everyone-loves >= 4.2.0"</code>.

::The equality operator (<code><, <=, =, >= or ></code>) combined with the version allows to define dependencies that require certain mod versions, but it is not required. Incompatibility does not support versions; if incompatibility is used, version is ignored.

::The possible prefixes are:
:::<code>!</code> for incompatibility
:::<code>?</code> for an optional dependency
:::<code>(?)</code> for a hidden optional dependency
:::<code>~</code> for a dependency that does not affect load order, or no prefix for a hard requirement for the other mod.

Types/EnergySource

2022-11-03T02:11:23Z

Honktown: /* output_flow_limit */ clarification

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

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

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

'''Default''': 0

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

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

'''Default''': true

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

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

'''Default''': true

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

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

Optional. How much energy the entity holds.

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

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

'''Default''': max double

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

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

'''Default''': max double

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

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

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

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

Mandatory.

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

'''Default''': 0

Optional.

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

Optional. Array of 1 or more smoke sources.

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

Optional.

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

'''Default''': 1

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

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

'''Default''': "chemical"

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

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

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

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

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

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

Mandatory. max_temperature must be >= default_temperature.

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

'''Default''': 15

Optional.

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

Mandatory.

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

Mandatory.

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

'''Default''': 1

Optional.

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

'''Default''': 15

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

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

'''Default''': 1

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

Optional.

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

Optional.

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

Optional.

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

Optional.

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

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

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

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

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

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

Optional. Array of 1 or more smoke sources.

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

Optional.

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

'''Default''': 1

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

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

'''Default''': false

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

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

'''Default''': false

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

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

'''Default''': true

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

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

'''Default''': 0

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

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

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

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

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

Types/EnergySource

2022-11-02T23:54:33Z

Honktown: /* input_flow_limit */ clarification

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

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

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

'''Default''': 0

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

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

'''Default''': true

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

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

'''Default''': true

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

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

Optional. How much energy the entity holds.

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

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

'''Default''': max double

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

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

'''Default''': max double

Optional. How fast the energy can flow out of the entity. 0 means 0.

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

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

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

Mandatory.

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

'''Default''': 0

Optional.

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

Optional. Array of 1 or more smoke sources.

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

Optional.

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

'''Default''': 1

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

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

'''Default''': "chemical"

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

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

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

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

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

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

Mandatory. max_temperature must be >= default_temperature.

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

'''Default''': 15

Optional.

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

Mandatory.

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

Mandatory.

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

'''Default''': 1

Optional.

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

'''Default''': 15

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

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

'''Default''': 1

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

Optional.

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

Optional.

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

Optional.

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

Optional.

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

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

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

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

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

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

Optional. Array of 1 or more smoke sources.

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

Optional.

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

'''Default''': 1

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

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

'''Default''': false

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

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

'''Default''': false

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

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

'''Default''': true

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

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

'''Default''': 0

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

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

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

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

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

Types/EnergySource

2022-11-02T23:50:03Z

Honktown: /* drain */ clarification of drain

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

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

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

'''Default''': 0

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

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

'''Default''': true

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

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

'''Default''': true

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

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

Optional. How much energy the entity holds.

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

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

'''Default''': max double

Optional. How fast the energy can flow into the entity. 0 means 0.
=== output_flow_limit ===
'''Type''': [[Types/Energy]]

'''Default''': max double

Optional. How fast the energy can flow out of the entity. 0 means 0.

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

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

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

Mandatory.

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

'''Default''': 0

Optional.

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

Optional. Array of 1 or more smoke sources.

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

Optional.

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

'''Default''': 1

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

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

'''Default''': "chemical"

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

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

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

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

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

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

Mandatory. max_temperature must be >= default_temperature.

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

'''Default''': 15

Optional.

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

Mandatory.

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

Mandatory.

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

'''Default''': 1

Optional.

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

'''Default''': 15

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

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

'''Default''': 1

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

Optional.

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

Optional.

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

Optional.

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

Optional.

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

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

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

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

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

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

Optional. Array of 1 or more smoke sources.

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

Optional.

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

'''Default''': 1

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

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

'''Default''': false

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

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

'''Default''': false

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

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

'''Default''': true

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

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

'''Default''': 0

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

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

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

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

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

Talk:Types/ProjectileTriggerDelivery

2022-10-31T07:43:36Z

Honktown: start of discussion, added range_deviation topic

=range_deviation questions=
After it was discovered range_deviation is *not* in tiles, here is an example of a "fragmentation grenade" action:
<syntaxhighlight lang="lua"> {
type = "area",
repeat_count = 1200,
radius = 30,
trigger_from_target = true,
target_entities = false,
action_delivery =
{
type = "projectile",
projectile = "shotgun-pellet",
starting_speed = 1,
starting_speed_deviation = 0.3,
min_range = 50,
max_range = 100,
range_deviation = .5
}
}
</syntaxhighlight>

In game, the farthest a projectile travels is ~125 from the origin of the capsule (ok, so range_deviation / 2, add 1, * max range). However, for the least distance traveled of the projectiles, I find ~17.5. I do not understand and think the values could use some clarifying from a developer. [[User:Honktown|Honktown]] ([[User talk:Honktown|talk]]) 07:43, 31 October 2022 (UTC)

Types/ProjectileTriggerDelivery

2022-10-31T07:35:38Z

Honktown: /* range_deviation */ range_deviation is weird. 1/2 multiplier against max. cont. on discussion pages

Extends [[Types/TriggerDelivery]].

== Mandatory properties ==

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

Name of a [[Prototype/Projectile]].

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

Starting speed in tiles per tick.

== Optional properties ==
Inherits "source_effects" and "target_effects" properties from [[Types/TriggerDelivery]].

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

'''Default''': 0

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

'''Default''': 0

Maximum deviation of the projectile from source orientation, in +/- ( x radians / 2). Example: 3.14 radians -> +/- (180° / 2), meaning up to 90° deviation in either direction of rotation.

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

'''Default''': 0

Multiplied against 1/2 max range. A deviation of .5 will appear as a maximum of .25 (25%) deviation of an initial range goal. Post-deviation range may exceed max_range or be less than min_range.

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

'''Default''': 1000

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

'''Default''': 0

Prototype/Recipe

2022-10-25T15:31:50Z

Honktown: /* Recipe data */ difficulty = true is an error

{{Prototype parent|PrototypeBase}}
A recipe. It can be a crafting recipe, a smelting recipe, or a custom type of recipe (see [[Prototype/RecipeCategory]]).

{{Prototype TOC|recipe}}

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

{{Prototype property|category|[[Types/string|string]]|"crafting"|optional=true}}
Optional. The category of this recipe. The built-in categories can be found [[Data.raw#recipe-category|here]]. See also [[Prototype/RecipeCategory]].

The recipe category "crafting" cannot contain recipes with fluid ingredients or products.

{{Prototype property|subgroup|[[Types/string|string]]||optional=true}}
Optional. The subgroup of this recipe. If not specified, defaults to the subgroup of the product if there is only 1, or main_product if multiple products exist. If multiple products exist and no main_product is specified, the subgroup is required.

{{Prototype property|icons, icon, icon_size (IconSpecification)|[[Types/IconSpecification|IconSpecification]]|optional=true}}
An icon is mandatory for recipe with more than 1 product and no main_product. Otherwise defaults to the icon of main_product/1 product.

If given, it overwrites the icon of the main_product/1 product.

{{Prototype property|crafting_machine_tint|[[Types/table|table]] of [[Types/Color|Color]]|optional=true}}
Optional. Used by crafting machine <code>[[Prototype/CraftingMachine#working_visualisations|working_visualisations]]</code> to tint certain layers with the recipe color. [[Types/WorkingVisualisation#apply_recipe_tint|apply_recipe_tint]] on the working visualisation determines which of the 4 colors is used for that layer (if any).

Format:
<syntaxhighlight lang="lua">crafting_machine_tint = { primary = {r=0,g=0,b=0,a=0}, secondary = {r=0,g=0,b=0,a=0}, tertiary = {r=0,g=0,b=0,a=0}, quaternary = {r=0,g=0,b=0,a=0}}</syntaxhighlight>

Each key/value pair is optional and defaults to the above value.

== Recipe data ==
{{#subobject:normal
|Prototype property name=normal
|Prototype property type=[[Prototype/Recipe#Recipe_data|Recipe data]] or [[Types/bool|bool]]
|Prototype property optional=true
|Prototype property pagename={{FULLPAGENAME}}
}}{{#subobject:expensive
|Prototype property name=expensive
|Prototype property type=[[Prototype/Recipe#Recipe_data|Recipe data]] or [[Types/bool|bool]]
|Prototype property optional=true
|Prototype property pagename={{FULLPAGENAME}}
}}
If the recipe does not have a difficulty, this is located directly in the prototype. Otherwise, if the "'''normal'''" or "'''expensive'''" property exists, the recipe has difficulty. Then, the recipe data has to be specified for each difficulty instead of directly in the prototype. If at least one difficulty has recipe data defined, the other difficulty can be set to <code>false</code>. This will disable the recipe for the difficulty, same as setting it <code>enabled = false</code>. If it is enabled (by technologies etc), it will use the data from the other difficulty. Not setting a difficulty, e.g. <code>normal = nil</code>, is possible and gives that difficulty the exact same properties as the difficulty that is defined. Setting one or both difficulties to <code>true</code> is not valid and will produce an error. See below for examples of difficulty.

{{Prototype property|ingredients|[[Types/table|table]] of [[Types/IngredientPrototype|IngredientPrototype]]}}
A table containing ingredient names and counts. Can also contain information about fluid temperature and catalyst amounts. The catalyst amounts are automatically calculated from the recipe, or can be set manually in the [[Types/IngredientPrototype|IngredientPrototype]].[https://factorio.com/blog/post/fff-256] 
Maximum ingredient amount is 65535. 
<code>ingredients</code> can be set to an empty table to create a recipe that needs no ingredients. 
Duplicate ingredients, e.g. two entries for the "wood" item, are ''not'' allowed. 
In-game, the item ingredients are ordered by [[Prototype/ItemGroup#order_in_recipe|item group order_in_recipe]].
<syntaxhighlight lang="lua">
ingredients = {{"iron-stick", 2}, {"iron-plate", 3}}
</syntaxhighlight>
The same with full format:
<syntaxhighlight lang="lua">
ingredients = {{type = "item", name = "iron-stick", amount = 2}, {type = "item", name = "iron-plate", amount = 3}}
</syntaxhighlight>
For fluids, the full format always has to be used:
<syntaxhighlight lang="lua">
ingredients = {{type="fluid", name="water", amount=50}, {type="fluid", name="crude-oil", amount=100}}
</syntaxhighlight>

{{Prototype property|result|[[Types/string|string]]|optional=true}}
Can be replaced with the results parameter. The item created by this recipe. Must be the name of an item, such as "iron-gear-wheel".
Note that <code>results</code> takes priority over <code>result</code>. So if a recipe has both keys set, <code>result</code> will be ignored. 

{{Prototype property|result_count|[[Types/uint32|uint32]]|1|optional=true}}
Optional. The number of items created by this recipe.

{{Prototype property|results|[[Types/table|table]] of [[Types/ProductPrototype|ProductPrototype]]|optional=true}}
A table containing result names and counts. Can also contain information about fluid temperature and catalyst amounts. The catalyst amounts are automatically calculated from the recipe, or can be set manually in the [[Types/ProductPrototype|ProductPrototype]].[https://factorio.com/blog/post/fff-256] 
<code>results</code> can be set to an empty table to create a recipe that produces nothing. 
Duplicate results, e.g. two entries for the "iron-plate" item, are allowed.

<syntaxhighlight lang="lua">
results=
{
{type="fluid", name="heavy-oil", amount=3},
{type="fluid", name="light-oil", amount=3},
{type="fluid", name="petroleum-gas", amount=4}
},
</syntaxhighlight>
<syntaxhighlight lang="lua">
results =
{
{type = "item", name = "iron-nuggets", amount = 9},
{type = "item", name = "gold-nuggets", amount = 1}
},
</syntaxhighlight>
<syntaxhighlight lang="lua">
results =
{
{type = "fluid", name = "steam", amount = 1, temperature = 165}
},
</syntaxhighlight>

{{Prototype property|energy_required|[[Types/double|double]]|0.5|optional=true}}
Optional. The amount of time it takes to make this recipe. Must be greater than 0.001.

This is the number of seconds it takes to craft at crafting speed 1.

{{Prototype property|emissions_multiplier|[[Types/double|double]]|1.0|optional=true}}

{{Prototype property|requester_paste_multiplier|[[Types/uint32|uint32]]|30|optional=true}}

{{Prototype property|overload_multiplier|[[Types/uint32|uint32]]|0|optional=true}}
Used to determine how many extra items are put into an assembling machine before it's considered "full enough". See [[Inserters#Insertion_limits]].

If set to 0, it instead uses the following formula: 1.166 / (energy_required / the assembler's crafting_speed), rounded up, and clamped between 2 and 100. The numbers used in this formula can be changed by the [[Prototype/UtilityConstants]] dynamic_recipe_overload_factor, minimum_recipe_overload_multiplier and maximum_recipe_overload_multiplier.

{{Prototype property|allow_inserter_overload|[[Types/bool|bool]]|true|optional=true}}
If the recipe is allowed to have the extra inserter overload bonus applied (4 * stack inserter stack size).

{{Prototype property|enabled|[[Types/bool|bool]]|true|optional=true}}
Optional. This can be false to disable the recipe at the start of the game, or "true" to leave it enabled.

If your recipe is unlocked by a technology, you should set this to "false".

{{Prototype property|hidden|[[Types/bool|bool]]|false|optional=true}}
Optional. Hides the recipe from crafting menus.

{{Prototype property|hide_from_stats|[[Types/bool|bool]]|false|optional=true}}
Optional. Hides the recipe from flow stats (item/fluid production statistics).

{{Prototype property|hide_from_player_crafting|[[Types/bool|bool]]|false|optional=true}}
Optional. Hides the recipe from the player's crafting screen. The recipe will still show up for selection in machines.

{{Prototype property|allow_decomposition|[[Types/bool|bool]]|true|optional=true}}
Optional. Whether this recipe is allowed to be broken down for the recipe tooltip "Total raw" calculations.

{{Prototype property|allow_as_intermediate|[[Types/bool|bool]]|true|optional=true}}
Optional. Whether the recipe can be used as an intermediate recipe in hand-crafting.

{{Prototype property|allow_intermediates|[[Types/bool|bool]]|true|optional=true}}
Optional. Whether the recipe is allowed to use intermediate recipes when hand-crafting.

{{Prototype property|always_show_made_in|[[Types/bool|bool]]|false|optional=true}}
Optional. Whether the "Made in: {Machine}" part of the tool-tip should always be present, not only when the recipe can not be hand-crafted.

{{Prototype property|show_amount_in_title|[[Types/bool|bool]]|true|optional=true}}
Optional. Whether the recipe name should have the product amount in front of it, e.g. "2 [[transport belt]]"

{{Prototype property|always_show_products|[[Types/bool|bool]]|false|optional=true}}
Optional. Whether the products are always shown in the recipe tool-tip.

{{Prototype property|unlock_results|[[Types/bool|bool]]|true|optional=true}}
Optional. Whether enabling this recipe unlocks its item products to show in selection lists (item filter, logistic request etc.).

{{Prototype property|main_product|[[Types/string|string]]|optional=true}}
Optional.

For recipes with more than one product: This defines of which result the icon, subgroup and name is used. If it is not set and the recipe has more than 1 result the recipe will use the recipe-name and recipe-description locale and its own subgroup and icon.

For recipes with 1 result: The recipe uses the icon, subgroup and name of the result by default. If set this property is set to an empty string, the recipe will use the properties of the recipe instead of the result.

== Examples ==

=== "iron-plate" ===
<syntaxhighlight lang="lua">
{
type = "recipe",
name = "iron-plate",
category = "smelting",
energy_required = 3.5,
ingredients = {{"iron-ore", 1}},
result = "iron-plate"
}</syntaxhighlight>

=== "coal-liquefaction" ===

<syntaxhighlight lang="lua">{
type = "recipe",
name = "coal-liquefaction",
category = "oil-processing",
subgroup = "fluid-recipes",
order = "a[oil-processing]-c[coal-liquefaction]",
enabled = false,
energy_required = 5,
icon = "__base__/graphics/icons/fluid/coal-liquefaction.png",
icon_size = 32,
ingredients =
{
{type="item", name="coal", amount=10},
{type="fluid", name="heavy-oil", amount=25},
{type="fluid", name="steam", amount=50}
},
results=
{
{type="fluid", name="heavy-oil", amount=35},
{type="fluid", name="light-oil", amount=15},
{type="fluid", name="petroleum-gas", amount=20}
},
allow_decomposition = false
}</syntaxhighlight>

=== "iron-gear-wheel" — recipe with difficulty ===
<syntaxhighlight lang="lua"> {
type = "recipe",
name = "iron-gear-wheel",
normal =
{
ingredients = {{"iron-plate", 2}},
result = "iron-gear-wheel"
},
expensive =
{
ingredients = {{"iron-plate", 4}},
result = "iron-gear-wheel"
}
},</syntaxhighlight>

==== Modified so that it cannot be crafted in normal mode, unless unlocked via command/research ====
<syntaxhighlight lang="lua"> {
type = "recipe",
name = "iron-gear-wheel",
normal = false,
expensive =
{
ingredients = {{"iron-plate", 4}},
result = "iron-gear-wheel"
}
},</syntaxhighlight>

==== Modified so that the expensive recipe is always used, even in normal mode ====
<syntaxhighlight lang="lua"> {
type = "recipe",
name = "iron-gear-wheel",
normal = nil, --this line can be omitted
expensive =
{
ingredients = {{"iron-plate", 4}},
result = "iron-gear-wheel"
}
},</syntaxhighlight>

Types/ItemProductPrototype

2022-10-23T21:05:49Z

Honktown: /* probability */ effect and outcome of using probability (as it appears in game)

__NOTOC__An item product definition, for example for a [[Prototype/Recipe]]. Its loading is triggered by the <code>type</code> of a [[Types/ProductPrototype]] being "item". It can be specified as a table with named or numbered keys, but not a mix of both.

== Mandatory properties ==

=== name or 1 ===
'''Type''': [[Types/string]]

The name of a [[Prototype/Item]].

== Optional properties ==

=== amount or 2 ===
'''Type''': [[Types/uint16]]

Mandatory when using numbered keys (an array). 
If <code>amount</code> is present, <code>amount_min</code> and <code>amount_max</code> are not loaded.

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

'''Default''': 1

Value between 0 and 1, 0 for 0% chance and 1 for 100% chance.

The effect of probability is no product, or, a linear distribution on [min, max]. For a recipe with probability p, amount_min min, and amount_max max, the Expected Value of this '''product''' can be expressed as <code>p * (0.5 * (max + min))</code>. This is what will be shown in a recipe tooltip. The effect of <code>catalyst_amount</code> on the product is not shown.

=== amount_min ===
'''Type''': [[Types/uint16]]

Mandatory if <code>amount</code> is not specified and named keys are being used.

=== amount_max ===
'''Type''': [[Types/uint16]]

Mandatory if <code>amount</code> is not specified and named keys are being used.

If set to a number that is less than <code>amount_min</code>, the game will use <code>amount_min</code> internally.

=== catalyst_amount ===
'''Type''': [[Types/uint16]]

'''Default''': 0

Amount that should not be affected by productivity modules (not yielded from bonus production) and should not be included in the item production statistics.

If this ItemProductPrototype is used in a recipe, the catalyst amount is calculated automatically based on the [[Prototype/Recipe#ingredients|ingredients]] and [[Prototype/Recipe#results|results]].[https://factorio.com/blog/post/fff-256]

== See also ==
* [[Types/ProductPrototype]]
* [[Types/FluidProductPrototype]]

Prototype/Container

2022-10-15T02:29:21Z

Honktown: /* Optional properties */ clarified behavior of enable_inventory_bar

{{Prototype parent|Prototype/EntityWithOwner}}
A generic container, such as a chest. Can not be rotated.

{{Prototype TOC|container}}

== Extensions ==
* [[Prototype/LogisticContainer]] '''logistic-container'''
** [[Prototype/InfinityContainer]] '''infinity-container'''

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

{{Prototype property|inventory_size|[[Types/uint16|uint16]]}}
The number of slots in this container.

{{Prototype property|picture|[[Types/Sprite|Sprite]]}}
The picture displayed for this entity.

== Optional properties ==

{{Prototype property|inventory_type|[[Types/string|string]]|"with_bar"|optional=true}}
One of "with_bar" and "with_filters_and_bar". Whether the inventory of this container can be filtered (like cargo wagons) or not.

{{Prototype property|enable_inventory_bar|[[Types/bool|bool]]|true|optional=true}}
If the inventory limiter (red X) is visible. This does not change the inventory itself ([https://lua-api.factorio.com/latest/LuaInventory.html#LuaInventory.supports_bar LuaInventory.supports_bar()] will not change and the bar can still be modified by script).

{{Prototype property|scale_info_icons|[[Types/bool|bool]]|false|optional=true}}
If the icons of items shown in alt-mode should be scaled to the containers size.

{{Prototype property|circuit_wire_connection_point|[[Types/WireConnectionPoint|WireConnectionPoint]]|optional=true}}
Defines how wires visually connect to this container.

{{Prototype property|circuit_wire_max_distance|[[Types/double|double]]|0|optional=true}}
The maximum circuit wire distance for this container.

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

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

{{Prototype property|circuit_connector_sprites|[[Types/CircuitConnectorSprites|CircuitConnectorSprites]]|optional=true}}
The pictures displayed for circuit connections to this container.

Types/IconData

2022-10-04T08:43:07Z

Honktown: /* icon_mipmaps */ tiniest inconsistency. changing comma to x between resolution example

== Basics ==
Data of one icon "layer" for the <code>icons</code> property of the [[Types/IconSpecification]].

== Mandatory properties ==
=== icon ===
'''Type''': [[Types/FileName]]

The path to the icon.

=== icon_size ===
'''Type''': [[Types/SpriteSizeType]]

Mandatory if <code>icon_size</code> is not specified outside of <code>icons</code>. The size of the square icon, in pixels, e.g. 32 for a 32px by 32px icon.

== Optional properties ==
=== tint ===
'''Type''': [[Types/Color]]

'''Default''': <nowiki>{r=1, g=1, b=1, a=1} (white)</nowiki>

Tint of the icon.

=== shift ===
'''Type''': [[Types/vector]]

'''Default''': {0, 0}

Used to offset the icon "layer" from the overall icon. 
The shift is applied from the center (so negative shifts are left and up, respectively). Shift uses the unit "pixels after scaling", see [[#Notes]].

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

'''Default for items/recipes''': (32/icon_size)

'''Default for technologies''': (256/icon_size)

When set, specifies the scale of the icon on the GUI scale. 
Scale 2 means that the icon will be 2 times bigger on screen (and more pixelated).

=== icon_mipmaps ===
'''Type''': [[Types/uint8]]

Icons of reduced size will be used at decreased scale. 0 or 1 mipmaps is a single image. The file must contain 1/2 size images with a geometric-ratio, for each mipmap level. Each next level is aligned to the upper-left corner. Example sequence: 128x128@(0,0), 64x64@(128,0), 32x32@(196,0) is 3 mipmaps.

'''Default''': 0

== Notes ==

* Only the first icon layer will display a shadow.
* The final combination of icons will always be resized in GUI based on the first icon layer's size, but won't be resized when displayed on machines in alt-mode.
: (example: recipe first icon layer is size 128, scale 1, the icon group will be displayed at resolution /4 to fit the 32px GUI boxes, but will be displayed 4 times as large on buildings)
* Shift values are based on final size (icon_size * scale) of the first icon.

== Examples ==

<syntaxhighlight lang="lua">{
icon = "__base__/graphics/icons/fluid/heavy-oil.png",
icon_size = 64,
scale = 0.5,
shift = {4, -8}
}</syntaxhighlight>

Multiplayer

2022-09-25T23:38:05Z

Honktown: /* How to list a server-hosted game on the matching server */ server description increased to 5000 characters some time ago, noting

{{Languages}}
[[File:players_colored_preview.png|190px|right]]In addition to being a single-player game, Factorio also supports multiplayer, allowing many [[player]]s to cooperate and assist each other, or work against each other in pvp. This page documents how to set up a multiplayer game, how to join one, and the Multiplayer Admin features for managing other users and the server. By default, multiplayer games run the CO-OP [[Game modes and options|freeplay scenario]] where all players work together to launch a rocket with a satellite into space. Other scenarios, including PvP maps, are available for download from the [https://forums.factorio.com/viewforum.php?f=36&sid=93d1fbe9336d31d6bac60847b6c97985 Maps and Scenarios forum].

== Setting Up a Multiplayer Game ==

[[File:multiplayer_game_night.png|thumb|250px|A multiplayer game.]]Multiplayer games can be joined, hosted while playing, or hosted by a dedicated server. Multiplayer games can be advertised to other players on the same LAN or worldwide.

Use the ''Multiplayer'' button in the ''Play'' menu to start playing a multiplayer game, choose ''New'' or ''Load'' or ''Scenarios'' to host and play, or ''Browse'' or ''Play on LAN'' to connect to an already-running game. The host can also choose not to advertise the game at all, in which case you'll need the server's (public or otherwise reachable) IP address; you can then ''Connect'' directly to that to join the game.

Notes and tips:

* All game instances need the installation of ''exactly the same'' game-versions and mods.
* Factorio servers use port '''34197'''. The port can be changed in the [[Application directory|config]] file.
* Factorio uses '''UDP only'''. The game builds its own "reliable delivery" layer built on UDP to deal with packet loss and reordering issues.
** Make sure you configure your router's port forwarding correctly for port '''34197'''.
** Make sure your router does not [https://doc.pfsense.org/index.php/Static_Port randomize the source port] on packets outbound from '''34197'''. Some routers do this and require [https://forum.pfsense.org/index.php?PHPSESSID=3k4h9n5o2tksgqv910fknf7qt7&topic=142188.msg798594#msg798594 additional configuration] to prevent it.
** Make sure there is no firewall or anti-virus blocking the UDP-packets.
* The hard limit for the number of players is [https://forums.factorio.com/viewtopic.php?f=53&t=6481&p=50661#p50586 65,535]. However, practical limit for this is much lower, popular streamers have managed to get well over a hundred players.

=== Dedicated/Headless server ===

As of Factorio version 0.12.0 onwards, a dedicated (or headless) server can be started using the --start-server command line option. You can run factorio --help to get a list of all command-line arguments that Factorio accepts.

In the headless mode:
* Graphics are not initialized (faster start up, less memory usage, works on completely headless servers)
* Game starts immediately and loads a save given as a parameter to the command
* The server has no character in game
* Game is paused while there are no players connected (though this can be overridden using the no-auto-pause option in the server-settings.json)
* Saves the game on exit (and autosaves normally)

''0.13 onwards expects --start-server to be followed by a path to a save file.''

You will need to create your save file before you start the server, as the dedicated server REQUIRES a save file to be provided. This can easily be done using the --create command-line argument. For example:

<pre>
./bin/x64/factorio --create ./saves/my-save.zip # This creates a new save, as if by clicking the New Game button in the GUI
</pre>

<pre>
./bin/x64/factorio --start-server ./saves/my-save.zip # This starts a server that will host the file created on the previous line
</pre>

There are several JSON configuration files that factorio can make use of to change the server and map settings:
* '''map-gen-settings''' to set parameters used by the map generator such as width and height, ore patch frequency and size, etc. (Added in 0.13)
* '''map-settings''' to control pollution spread, biter expansion and evolution, and more (Added in 0.15)
* '''server-settings''' which consolidated several command-line options into a single file (Added in 0.14.12)
Example files for each of these parameters are included in the data subdirectory.

The --map-gen-settings and --map-settings options must be used with the --create option when you create a new map. For example:
<pre>./bin/x64/factorio --create saves/my-save.zip --map-gen-settings my-map-gen-settings.json --map-settings my-map-settings.json</pre>

Starting the factorio server requires you to specify the location of the server-settings.json file. By default this is in the factorio data folder. For example to start factorio using the most recent saved map, you would run:

<pre>./bin/x64/factorio --start-server-load-latest --server-settings ./data/server-settings.json</pre>

On windows, it may be useful to start the server with a .bat file. The bat file should have the following content:

<pre>start /wait .\bin\x64\factorio.exe --start-server-load-latest --server-settings .\data\server-settings.json</pre>

''See [[Command_line_parameters]] for more command line parameters.''

=== Setting up a Linux Factorio server ===

'''Note:''' Factorio now requires <tt>glibc</tt> version 2.18, but CentOS/RHEL 7 only ship with version 2.17 so this guide will no longer work without [https://forums.factorio.com/viewtopic.php?t=54654#p324493 manually compiling <tt>glibc</tt> 2.18].

This step-by-step guide has been verified on fresh CentOS 7 and RHEL 7 installs but should be applicable with little to no changes on most distributions.

The guide assumes you will install the headless server under '''/opt/factorio''', adjust paths according to your own setup. We will also suggest that you run the Factorio server as a separate user to harden security of your setup.

Note that there are two distinct packages for Linux that can be used to run a headless server. First is the usual Linux download, that contains the full game. The other is the special [https://www.factorio.com/download headless package]. The headless package does not contain any files irrelevant for a pure server, such as graphics and sounds. It is also not linked against libraries that may not be present on a server machine, such as Xlib, libGL or libasound. This option should be selected if running in a 3rd party hosted server.

This guide does not handle firewall/port forwarding since this can be done in various ways on Linux (make sure to read up how this is done as a Linux admin on your particular distribution)

==== Basic installation ====

* Download the selected package -- either full game or the headless package -- and upload the Linux tar.gz or tar.xz package to your server /tmp
* Extract the package in /tmp to /opt/factorio
<pre>
$cd /opt/

$sudo tar -xzf /tmp/factorio.tar.gz # Use the correct file name. It includes the factorio version number
$sudo tar -xJf /tmp/factorio.tar.xz # if you downloaded a .tar.xz file (ver 0.15.x)</pre>

* Add a new user to your system and assign ownership of the factorio dir to it (please, do not run as the root user, sudo may be needed)
<pre>
$useradd factorio
$chown -R factorio:factorio /opt/factorio</pre>

* Try the binary
<pre>
$su factorio
$/opt/factorio/bin/x64/factorio --start-server savename</pre>

As long as it fails saying it cannot find/open the savename.zip you are set! Just upload a save from your own computer and put it in the /opt/factorio/saves directory, or use the --create ./saves/newgame.zip argument.

=== How to list a server-hosted game on the matching server ===

In order to publish the game to the matching server, Factorio needs to be given some more information than just the save file location. These information are provided in a ''server settings file''.

To create a server settings file, look at the example file located in '''data/server-settings.example.json''' in the Factorio [[Application directory]]. The recommended way is to make a copy of this example file and edit the copy.

The following values can be changed:
; Name: This will be the name under which the server will be listed in the server browser
; Description: A description of your server. May contain up to 5000 characters. [https://factorio.com/blog/post/fff-304 MP server description]
; Tags: A list of game tags
; Max Players: Allows you to limit the number of players that can be connected to the server at the same time. If you want no limit, just set max_players to 0.
* Visibility for server browser: May be either public, LAN or hidden.
** Public: The server will appear in the public server list. This requires the login credentials below to be filled in.
** LAN: The server will not appear in the public server list, but will be available through the Play On LAN button
** Hidden: Clients will have to connect using the server's IP address
* User credentials using a username and password or authentication token (found on the factorio website or in the player-data.json): These are necessary if you wish to make the server public. Otherwise, they can be left empty.
** For security reasons it is recommended to use authentication token as this document is stored as plain text. Though it should be noted that an authentication token is a sensitive piece of information as well, and you are well-advised to keep it secret.
* Server Password
** Field name is game_password
* Whether to verify user identity
(There are additional values in v0.14 of factorio.)

=== Technical Implementation Details ===

Notes about some technical details surrounding multiplayer have been published by the development team in several Friday Facts blog posts:

* [http://www.factorio.com/blog/post/fff-76 Lock step architecture]
* [http://www.factorio.com/blog/post/fff-99 Client-server connections]
* [http://www.factorio.com/blog/post/fff-143 NAT punching, introduced in 0.13]

=== Miscellaneous Tips ===
* The key for [[Console|console commands]] is also used initiate chat in multiplayer. To execute a command instead of chatting, you need to type ''/c'' before the command. Commands executed are ''visible to all players''. Additionally, the multiplayer game must have been started with commands allowable for commands to work.
* Set the player's color using the command
/color r g b
r, g and b are for red, green and blue respectively (possible values are between 0 and 1, use [https://www.w3schools.com/colors/colors_converter.asp this site] to convert colors to rgb numbers).
* To give yourself admin access, you need to create a server-adminlist.json in the same directory as factorio-current.log. The file should contain a list of admins, like so: <code>[ "user1", "user2" ]</code>

This file will be created if you promote a player through the console.

== Joining a Multiplayer game ==

As of version 0.13, players no longer necessarily have to port-forward to play with others. Players may join each other through Steam, or by just the port-forwarded host.

Players wishing to join a game may do so in multiple ways:

* Joining by directly inputting a public IP and port into Factorio.
* Selecting the server from the active public server menu.
* Joining through Steam's services.
* Playing a local LAN game.

=== Joining by IP ===

To join a multiplayer game by IP, you will need to know the public IP of a valid server. You can find this through social media, websites, or by word of mouth. After acquiring the IP and port, simply go to play -> Multiplayer -> Connect to server, and provide all the information it asks for.

If the server has been set up correctly to accept public connections, you should be able to join the game.

=== Joining via server list ===

Factorio's devs keep a list of all public servers that declare themselves to the service, allowing players to join directly through Factorio. Most of these servers will be password-requiring, but many completely public servers can be connected to. To join via server list, go to Play -> Multiplayer -> Browse public games. Provide your Factorio.com login if asked, and a list of public servers will appear. Simply select one.

=== Joining through Steam ===

Steam provides a "game invite" system, simply use that to join. You can find more info about how to use steam in it's documentation. ''This is the most recommended way for the average player to use multiplayer with their friends, as it allows Steam to handle everything''.

=== Joining a local LAN game ===

If you have some friends on the same internet connection as you (in the same building or network), you may play a LAN game. Simply go to Play -> Multiplayer -> Play on LAN.

=== Connecting to a Server Behind NAT ===

Factorio requires that the server (in client-server mode) have a publicly accessible IP address or that all players are on the same LAN. If you are behind NAT, you must set up port forwarding ([[Multiplayer#Playing_over_LAN_.2F_Internet|see above]] for port number) or use virtual LAN software such as Hamachi or Evolve.

Multiplayer games will be launched in client-server mode (also [http://www.factorio.com/blog/post/fff-99 multiplayer forwarding] mode). In this mode, all clients send their network traffic to the server and the server forwards the traffic to the other clients. The advantage of this is that it allows games where some players are inside a LAN and others are outside. The disadvantage may be slightly more lag as packets must travel an extra hop (through the server).

* [https://forums.factorio.com/viewtopic.php?f=53&t=6393 Forwarding ports without logging into your router]
* [https://forums.factorio.com/viewtopic.php?f=53&t=7714 A guide for connecting with Evolve]
* [http://steamcommunity.com/sharedfiles/filedetails/?id=653628496 A guide for connecting with Hamachi]

== PvP ==

In PvP mode, players can be on different forces. Each force can have one (free-for-all) or more players (teams). Each force has its own independent research progression. Additionally, each force's [[Military units and structures]] will attack other players as enemies, unless a cease fire is set. Note that, depending on the scenario, cease fires may be unidirectional — setting a cease fire with an opposing force does not guarantee a cease fire from them in return.

To start a PvP game, you can select the 'PvP' scenario from the 'Play' menu, or download a custom scenario which also supports PvP.

After downloading a PvP scenario, you need to move it to your application directory, and create the multiplayer game using the scenario.

# Download the scenario and place the scenario directory in the ''scenarios'' directory within your [[Application_directory#Directory_locations_by_OS_and_installation_method|user data directory]].
# Launch Factorio
# Click ''Play''
# Click ''Multiplayer''
# Click ''Scenario''
# Choose the PvP scenario you want and click ''Create''
# Choose latency and other settings, then click ''Play''
# Other players can now join the game

=== Forces ===

Forces can be manually created via the console. This allows any map/scenario to be used for PvP. This may not be as convenient as a pre-made PvP scenario, as there will be no way for players to turn on/off cease fires other than through the console.

Each created force has its own research progression and different forces may attack each other.

The console commands for setting up and controlling forces are below:

<pre>
game.create_force("Name")
--Creates the force "Name"

game.players["Player_name"].force = game.forces["Name"]
--Sets this player to the new force

game.forces["Name"].set_cease_fire("Other_force_name", true)
--Sets the new force ceasefire to the "other force"

game.forces["Name"].set_spawn_position({x = 10, y = 20}, game.surfaces[1])
--Sets the spawn position of the force

game.print(#game.forces)
--Prints the number of forces

for name, force in pairs (game.forces) do
game.print(name)
end
--Prints the name of all the forces
</pre>

The ability of players and entities belonging to one force to interact with structures belonging to another, non-friendly force is limited. However, some types of interactions are still possible:

;Manual pickup from belts
: Players can pick up items traveling along a transport belt that belongs to an opposing force. Note however that this can't be automated: Inserters will ''not'' take items from an opposing force's belts.
;Belt network connection
: Belts will connect to each other regardless of force membership, so it's possible to extend an opposing force's belt line, and items will flow to them. It is also possible to side-load into, and place items onto (with inserters) an opposing force's belt line.
;Fluid network connection
: Pipes (and storage tanks, and pumps, &c) will connect to each other regardless of force membership. For example, it's possible to pump fluids out of or into a storage tank belonging to an opposing force.
;Power leeching
: Players can draw power from an opposing force's electric network, by building structures inside the coverage area of a power pole belonging to an opposing force. Power poles that you build next to a power pole belonging to an opposing force will automatically connect to it, but will be impossible to connect or disconnect manually.

== History ==

=== Narrative history ===

Because of the potentially immense amount of activity on a map, the game engine utilizes a [https://www.factorio.com/blog/post/fff-76 lock step architecture]. All instances of the game run full simulations of the entire world and only player actions are transferred across the network.

Multiplayer games were introduced to Factorio with version 0.11.0. The only connection method available was peer-to-peer mode which meant every player had to be able to directly communicate with every other player. In version 0.12.4, a client-server mode of communication was introduced in which the server (either a dedicated one or the player who hosted the game) relays messages to all peers. This means that direct connection between all players is no longer necessary. As of version 0.13, P2P connecting is completely removed.

As of version 0.12.0, the game features "latency hiding" mechanics where the game simulates some of the player's actions locally to make some common interactions (such as moving the player's character) more fluid. Not every action is a part of latency hiding – most notably, car or train driving and shooting are not a part of it.

=== Version history ===

Maintainer note: The following history may not be fully up to date, or comprehensive. Factorio's multiplayer has undergone a great deal of small changes since its inception, however this history will provide a rough overview.

{{history|0.14.14|
* Added multiplayer server option "Autosave only on server".
* Deconstructing/canceling deconstruction sets the "last user" on an entity.
* Decreased the size of connection accept message with lot of mod which could help some people with 50+ mod multiplayer games.
}}

{{history|0.14.13|
* Reconnecting to multiplayer game that the player is already in (due to being dropped, most often) instantly closes the previous connection and connects the player.}}

{{history|0.14.11|
* Multiplayer user names can only consist of letters, and <code> -_. </code> characters.}}

{{history|0.14.10|
* Disabled 32bit (x86) multiplayer. All hosts and members must be running the 64bit (x86_64) version of the game.}}

{{history|0.14.8|
* More than 10 players in one game will reduce the rate the game is saved to the server.}}

{{history|0.14.6|
* Username is now set to username setting, not email.}}

{{history|0.14.5|
* Added AFK Auto kick interval to multiplayer host settings (with never as default).}}

{{history|0.14.3|
* When save of scenario is loaded in multiplayer, it's scenario is saved in user scenarios.
* Added <code>/time</code> command to print the current map age.
* Added option to host multiplayer game with scenario (it only had new game/load game there).
}}

{{history|0.14.2|
* Can specify limit of upload speed when hosting.}}

{{history|0.14.0|
* Server doesn't stop/slow down the game when some client is too slow, stops communicating or saves the game longer than the server.
* Players automatically quit game after 3 desyncs.
* Removed the option to enable/disable latency hiding, it is always on on clients (and off on the server).
}}

{{history|0.13.10|
* Server stdout messages now contain time stamps and message-type tags}}

{{history|0.13.2|
* Limit multiplayer player name to 60 characters.}}

{{history|0.13.0|
* Improved Multiplayer game UX
* Server games are published to the server and clients can browse existing games.
* Removed multiplayer peer-to-peer mode.
* Building sound is played also for other players in multiplayer.
}}

{{history|0.12.31|
* Human readable error notice when multiplayer connection wasn't successful. (https://forums.factorio.com/23132)
* Improved map download speed when connecting to multiplayer game.}}

{{history|0.12.30|
* Mod checksums are calculated when the game starts and are compared with other peers when joining a multiplayer game. This is to ensure everyone has exactly the same mod in order to prevent desyncs caused by local changes made to mod files.}}

{{history|0.12.28|
* Added --port to specify which network port the game should use, when hosting with --start-server or --mp-load-game.}}

{{history|0.12.27|
* The report of different mods when trying to connect to multiplayer game is now scroll-able when needed.
* Better message when the server leaves a multiplayer game}}

{{history|0.12.11|
* Added --no-auto-pause: When running as a server, --no-auto-pause will prevent stopping the game when no players are connected.}}

{{history|0.12.9|
* Added resume button to multiplayer game menu}}

{{history|0.12.7|
*New command line options for the headless server: --disallow-commands and --peer-to-peer}}

{{history|0.12.5|
* Multiplayer broadcast (heartbeats) is done via a single message when not using peer2peer.
* Further optimizations in size of the Multiplayer heartbeat (message sent every tick).
* LatencyState is suspended when player is killed (and waiting for respawn) in Multiplayer.
}}

{{history|0.12.4|
* Simple mechanism for multiplayer relaying via the server.
* Less annoying glitches when running and shooting in multiplayer with latency hiding.}}

{{history|0.12.0|
* Multiplayer latency hiding (gives impression that some common tasks are performed immediately)
* Factorio can run as a dedicated server without graphics.
* Basic PvP: New forces can now be created and merged back together; a cease-fire can be agreed upon between forces
* IPv6 support for multiplayer.
* DNS names can be used when connecting to multiplayer game.
* Player's logistic filters are now remembered after respawn in multiplayer
* Smaller multiplayer heartbeat packet size.
}}

{{history|0.11.19|
* Multiplayer dropping threshold is doubled during map upload / download.}}

{{history|0.11.17|
* Autosaves in multiplayer are performed at the same time by all clients (interval is set by hosting player).
* Progress bar is shown when non-responsive peers are about to be dropped from the game in the Multiplayer.
* Progress bar is shown when other peers in multiplayer are saving map.}}

{{history|0.11.16|
* Revived character (after dying in multiplayer) are placed on the spawn point instead of the center of the map.}}

{{history|0.11.2|
* Mods that don't affect game state are not needed to be synchronized when playing multiplayer game or replaying game.}}

{{history|0.11.0|
* Introduced}}

Types/IconSpecification

2022-09-24T02:48:59Z

Honktown: /* icon_mipmaps */ description

== Basics ==
Specifies the icon of an entity/item/technology/recipe etc. The properties are specified directly in the prototype, not in another sub-property.

Either <code>icons</code> and optionally <code>icon_size</code>, or both <code>icon</code> and <code>icon_size</code> have to be specified. If both <code>icons</code> and <code>icon</code> are defined, <code>icon</code> is ignored.
== Prototype properties: Option 1 ==
=== icons ===
'''Type''': [[Types/table]] of [[Types/IconData]]

The rendering order of the individual icons follows the table (array) order: Later added icons (higher index) get drawn on top of previously added icons (lower index). Can't be an empty table.

=== icon_size ===
'''Type''': [[Types/SpriteSizeType]]

Mandatory if <code>icon_size</code> is not specified inside all instances of [[Types/IconData]] inside <code>icons</code>. The size of the square icon, in pixels, e.g. 32 for a 32px by 32px icon.

=== icon_mipmaps ===
'''Type''': [[Types/uint8]]

'''Default''': 0

== Prototype properties: Option 2 ==
=== icon ===
'''Type''': [[Types/FileName]]

Path to the icon file.
=== icon_size ===
'''Type''': [[Types/SpriteSizeType]]

Mandatory. The size of the square icon, in pixels, e.g. 32 for a 32px by 32px icon.

=== icon_mipmaps ===
'''Type''': [[Types/uint8]]

Icons of reduced size will be used at decreased scale. 0 or 1 mipmaps is a single image. The file must contain 1/2 size images with a geometric-ratio, for each mipmap level. Each next level is aligned to the upper-left corner. Example sequence: 128x128@(0,0), 64,64@(128,0), 32x32@(196,0) is 3 mipmaps.

'''Default''': 0

== Examples ==

Simple icon with size:
<syntaxhighlight lang="lua">
icon = "__base__/graphics/icons/fluid/heavy-oil.png",
icon_size = 32,
</syntaxhighlight>

Layered icon, size defined outside of layers:
<syntaxhighlight lang="lua">icon_size = 32,
icons = {
{
icon = "__base__/graphics/icons/fluid/barreling/empty-barrel.png"
},
{
icon = "__base__/graphics/icons/fluid/barreling/barrel-side-mask.png",
tint = { a = 0.75, b = 0, g = 0, r = 0 }
},
{
icon = "__base__/graphics/icons/fluid/barreling/barrel-hoop-top-mask.png",
tint = { a = 0.75, b = 0.5, g = 0.5, r = 0.5 }
}
}</syntaxhighlight>

Layered icon, size defined per layer:
<syntaxhighlight lang="lua">icons = {
{
icon = "__base__/graphics/icons/fluid/barreling/barrel-empty.png",
icon_size = 32
},
{
icon = "__base__/graphics/icons/fluid/barreling/barrel-empty-side-mask.png",
icon_size = 32,
tint = { a = 0.75, b = 0, g = 0, r = 0 }
},
{
icon = "__base__/graphics/icons/fluid/barreling/barrel-empty-top-mask.png",
icon_size = 32,
tint = { a = 0.75, b = 0.5, g = 0.5, r = 0.5 }
},
{
icon = "__base__/graphics/icons/fluid/crude-oil.png",
icon_size = 32,
scale = 0.5,
shift = {7, 8 }
}
}</syntaxhighlight>

Types/IconData

2022-09-24T02:46:18Z

Honktown: /* icon_mipmaps */

== Basics ==
Data of one icon "layer" for the <code>icons</code> property of the [[Types/IconSpecification]].

== Mandatory properties ==
=== icon ===
'''Type''': [[Types/FileName]]

The path to the icon.

=== icon_size ===
'''Type''': [[Types/SpriteSizeType]]

Mandatory if <code>icon_size</code> is not specified outside of <code>icons</code>. The size of the square icon, in pixels, e.g. 32 for a 32px by 32px icon.

== Optional properties ==
=== tint ===
'''Type''': [[Types/Color]]

'''Default''': <nowiki>{r=1, g=1, b=1, a=1} (white)</nowiki>

Tint of the icon.

=== shift ===
'''Type''': [[Types/vector]]

'''Default''': {0, 0}

Used to offset the icon "layer" from the overall icon. 
The shift is applied from the center (so negative shifts are left and up, respectively). Shift uses the unit "pixels after scaling", see [[#Notes]].

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

'''Default for items/recipes''': (32/icon_size)

'''Default for technologies''': (256/icon_size)

When set, specifies the scale of the icon on the GUI scale. 
Scale 2 means that the icon will be 2 times bigger on screen (and more pixelated).

=== icon_mipmaps ===
'''Type''': [[Types/uint8]]

Icons of reduced size will be used at decreased scale. 0 or 1 mipmaps is a single image. The file must contain 1/2 size images with a geometric-ratio, for each mipmap level. Each next level is aligned to the upper-left corner. Example sequence: 128x128@(0,0), 64,64@(128,0), 32x32@(196,0) is 3 mipmaps.

'''Default''': 0

== Notes ==

* Only the first icon layer will display a shadow.
* The final combination of icons will always be resized in GUI based on the first icon layer's size, but won't be resized when displayed on machines in alt-mode.
: (example: recipe first icon layer is size 128, scale 1, the icon group will be displayed at resolution /4 to fit the 32px GUI boxes, but will be displayed 4 times as large on buildings)
* Shift values are based on final size (icon_size * scale) of the first icon.

== Examples ==

<syntaxhighlight lang="lua">{
icon = "__base__/graphics/icons/fluid/heavy-oil.png",
icon_size = 64,
scale = 0.5,
shift = {4, -8}
}</syntaxhighlight>