Official Factorio Wiki - User contributions [en]

Prototype/Entity

2021-11-23T14:26:28Z

Snouz1: water reflection: added info (https://forums.factorio.com/viewtopic.php?f=28&t=100703)

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

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

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

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

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

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

== Optional properties ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The ones the game uses are:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Types/WaterReflectionDefinition

2021-11-23T14:23:10Z

Snouz1:

Entity water reflection.
Currently only renders for [[Prototype/EntityWithHealth]]

== Optional properties ==

=== pictures ===
'''Type''': [[Types/SpriteVariations]]

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

'''Default''': false

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

'''Default''': false

Tutorial:Mod settings

2021-10-16T14:31:39Z

Snouz1: Added where to access and modify settings from another mod (data.raw).

{{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 <sup>(in the same order)</sup> and finally the settings-final-fixes.lua file is called for each mod <sup>(in the same order)</sup>. 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.<sup>[https://forums.factorio.com/viewtopic.php?p=531322#p531322]
</sup>

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

=== 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.<sup>[https://forums.factorio.com/83316]</sup>

=== 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" using the [http://lua-api.factorio.com/latest/LuaSettings.html settings table]. 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>. 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 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>

These are then stored in data.raw until the end of the settings stage, so you can alter them from another mod

Example:
<syntaxhighlight lang="lua">
--in settings-updates.lua:
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/IconData

2021-08-08T12:15:35Z

Snouz1: Added an 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''': {r=1, g=1, b=1, a=1}

Tint of the icon. Default is when tint = nil. See Type for full details.

=== shift ===
'''Type''': [[Types/vector]]

'''Default''': {0, 0}

Used to offset the icon "layer" from the overall icon.

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

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

Types/IconData

2021-08-07T22:11:45Z

Snouz1: Added some precisions about scale, shift and shadow, based on my tests.

== 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''': {r=1, g=1, b=1, a=1}

Tint of the icon. Default is when tint = nil. See Type for full details.

=== shift ===
'''Type''': [[Types/vector]]

'''Default''': {0, 0}

Used to offset the icon "layer" from the overall icon.

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

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

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