Commonly used conventions for passing data between mods and Factorio
show_controller_gui :: boolean [RW] | Show the controller GUI elements. |
show_minimap :: boolean [RW] | Show the chart in the upper right-hand corner of the screen. |
show_research_info :: boolean [RW] | Show research progress and name in the upper right-hand corner of the screen. |
show_entity_info :: boolean [RW] | Show overlay icons on entities. |
show_alert_gui :: boolean [RW] | Show the flashing alert icons next to the player's toolbar. |
update_entity_selection :: boolean [RW] |
When true (the default), mousing over an entity will select it. |
show_rail_block_visualisation :: boolean [RW] |
When true (false is default), the rails will always show the rail block visualisation. |
show_side_menu :: boolean [RW] | Shows or hides the buttons row. |
show_map_view_options :: boolean [RW] | Shows or hides the view options when map is opened. |
show_quickbar :: boolean [RW] | Shows or hides quickbar of shortcuts. |
show_shortcut_bar :: boolean [RW] | Shows or hides the shortcut bar. |
tier_from_start :: double [RW] | |
roughness :: double [RW] | |
elevation :: double [RW] | |
available_water :: double [RW] | |
temperature :: double [RW] |
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.
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
).
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.
As a special case, when the key is just the empty string, the first parameter 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 number which will be converted to its textual representation.
"No ammo"
; in the Czech translation, it will print "Bez munice"
:
game.player.print{"description.no-ammo"}
description.no-ammo
template contains no placeholders, so no further parameters are necessary.
"Durability: 5/9"
; in the Japanese one, it will print
"耐久度: 5/9"
:
game.player.print{"description.durability", 5, 9}
"hello"
in all translations:
game.player.print{"", "hello"}
Coordinates of a tile in a map.
Positions may be specified either as a dictionary with x
, y
as keys,
or simply as an array with two elements.
{10, 20}
{x = 50, y = 20}
{y = 20, x = 50}
Coordinates of a chunk in a LuaSurface where each integer x/y represents a different chunk. This uses the same format as
Coordinates of a tile in a chunk on a LuaSurface where each integer x/y represents a different tile. This uses the same format as
A vector is a two-element array containing the x and y components. Unlike Positions, vectors don't use the
x
, y
keys.
right = {1.0, 0.0}
Two positions, specifying the top-left and bottom-right corner of the box, respectively. Like with Position, the names of the members may be omitted. When read from the game, the third member "orientation" is present if it is non-zero, however it is ignored when provided to the game.
Members:
{left_top = {-2, -3}, right_bottom = {5, 8}}
{{-2, -3}, {5, 8}}
An area defined using the map editor.
Members:
Red, green, blue and alpha values, all in range [0, 1]. All values here are optional; color channels default to 0, the alpha channel defaults to 1. Unlike Position, Color does not allow the short-hand notation of passing an array.
Members:
red1 = {r = 1, g = 0, b = 0, a = 0.5} -- Half-opacity red
red2 = {r = 1, a = 0.5} -- Same color as red1
black = {} -- All channels omitted: black
not_a_color = {1, 0, 0, 0.5} -- Actually also black: None of r, g, b have been specified
Parameters that affect the look and control of the game. Updating any of the member attributes here will immediately take effect in the game engine.
Show the controller GUI elements. This includes the toolbar, the selected tool slot, the armour slot, and the gun and ammunition slots.
Show the chart in the upper right-hand corner of the screen.
Show research progress and name in the upper right-hand corner of the screen.
Show overlay icons on entities. Also known as "alt-mode".
Show the flashing alert icons next to the player's toolbar.
When true
(the default), mousing over an entity will select it. Otherwise, moving the mouse won't update
entity selection.
When true
(false is default), the rails will always show the rail block visualisation.
Shows or hides the view options when map is opened.
Shows or hides quickbar of shortcuts.
Shows or hides the shortcut bar.
What is shown in the map view. If a field is not given, that setting will not be changed.
Various game-related settings. See data/base/prototypes/map-settings.lua
for a description
of all attributes. Updating any of the attributes will immediately take effect in the game engine.
game.map_settings.path_finder.short_cache_size = 15
Technology and recipe difficulty settings.
Fluid is represented as a table
An ingredient is a table
"item"
or "fluid"
.
Table with the following fields:
"item"
or "fluid"
.amount_min
,
amount_max
and probability
must all be specified.amount
is specified.amount
is specified.amount
is specified.
{{type="item", name="steel-chest", amount=1}}
{{type="fluid", name="heavy-oil", amount=1},
{type="fluid", name="light-oil", amount=4.5},
{type="fluid", name="petroleum-gas", amount=5.5}}
{{type=0, name="custom-item", probability=0.5, amount_min=1, amount_max=5}}
Loot is an array of loot items. Each loot item is a table:
The effect that is applied when a technology is researched. It is a table that contains at least the field
type
. A modifier may also have other fields depending on the type.
"inserter-stack-size-bonus"
, "stack-inserter-capacity-bonus"
, "laboratory-speed"
, "character-logistic-slots"
,
"character-logistic-trash-slots"
, "maximum-following-robots-count"
, "worker-robot-speed"
,
"worker-robot-storage"
, "ghost-time-to-live"
, "turret-attack"
, "ammo-damage"
, "give-item"
, "gun-speed"
,
"unlock-recipe"
, "character-crafting-speed"
, "character-mining-speed"
, "character-running-speed"
,
"character-build-distance"
, "character-item-drop-distance"
, "character-reach-distance"
, "character-resource-reach-distance"
,
"character-item-pickup-distance"
, "character-loot-pickup-distance"
, "character-inventory-slots-bonus"
,
"deconstruction-time-to-live"
, "character-health-bonus"
, "auto-character-logistic-trash-slots"
,
"mining-drill-productivity-bonus"
, "train-braking-force-bonus"
, "zoom-to-world-enabled"
,
"zoom-to-world-ghost-building-enabled"
, "zoom-to-world-blueprint-enabled"
, "zoom-to-world-deconstruction-planner-enabled"
,
"zoom-to-world-selection-tool-enabled"
, "worker-robot-battery"
, "laboratory-productivity"
, "follower-robot-lifetime"
,
"artillery-range"
, "nothing"
,type
"gun-speed"
"give-item"
"turret-attack"
"unlock-recipe"
"nothing"
A single offer on a market entity.
Table with the following fields:"give-item"
modifier.
Specifies how probability and richness are calculated when placing something on the map.
Can be specified either using probability_expression
and richness_expression
or by using all the other fields.
Table with the following fields:
d
is the dimension name; this attribute may occur multiple times, once for each
dimension, every time with a different prefix.d
is the dimension name.d
is the dimension name.d
is the dimension name.
Table with the following fields:
A float or a string specifying an amount. Possible values for the string are:
"none"
"very-low"
, "very-small"
, "very-poor"
"low"
, "small"
, "poor"
"normal"
, "medium"
, "regular"
"high"
, "big"
, "good"
"very-high"
, "very-big"
, "very-good"
Each of the values in a triplet (such as "low"
, "small"
, and "poor"
) are synonymous. When reading from the game, it will always provide a float.
Table with the following fields:
Table with the following fields:
Table with the following fields:
"entity"
"tile"
"optimized-decorative"
"5"
).
A single filter used by an infinity-pipe type entity.
Table with the following fields:"at-least"
, "at-most"
, or "exactly"
A definition of a fluidbox connection point.
Table with the following fields:
Table with the following fields:
first_constant
.second_constant
.first_signal
is set. Defaults to 0
.second_signal
is set. Defaults to 0
."*"
, "/"
, "+"
, "-"
, "%"
, "^"
, "<<"
, ">>"
, "AND"
, "OR"
, "XOR"
. When not specified,
defaults to "*"
.
Table with the following fields:
constant
.0
."<"
, ">"
, "="
, "≥"
, "≤"
, "≠"
. Specifies how the inputs should be
compared. If not specified, defaults to "<"
.true
. When false
, will output a value of 1
for
the given output_signal
.
Table with the following fields:
"<"
, ">"
, "="
, "≥"
, "≤"
, "≠"
. Specifies how the inputs should be
compared. If not specified, defaults to "<"
.first_signal
to. If not specified, first_signal
will be compared to constant
.first_signal
to. Has no effect when second_signal
is set.
When neither second_signal
nor constant
are specified, the effect is as though constant
were specified
with the value 0
.
Table with the following fields:
Table with the following fields:
An item stack may be specified either as a string (in which case it represents a full stack containing the specified item), or as the following table:
1
.1.0
.
{name="iron-plate"}
{name="iron-plate", count=1}
{name="copper-plate", count=47}
"iron-plate"
{name="iron-plate", count=100}
Commands can be given to enemies and unit groups. It is a table:
type
defines.distraction.by_enemy
.defines.distraction.by_enemy
.defines.distraction.by_enemy
.defines.distraction.by_enemy
.defines.distraction.by_enemy
.wander_in_group
is true
.true
, the units in the group will wander around inside the group's radius, just like gathering biters.
When false
, the units will wander as a group, ie they will all walk together in the same random direction.
Default is true for groups. Passing true for a single unit is an error.defines.distraction.by_enemy
.defines.distraction.by_enemy
.defines.distraction.by_enemy
.false
, they will obey and not build a base in a non-candidate chunk. Defaults to false
.
Table with the following fields:
A technology may be specified in one of three ways.
A surface may be specified in one of three ways.
nauvis
has index 1
, the first surface-created
surface will have index 2
and so on."nauvis"
.
An entity prototype may be specified in one of the following ways.
An item prototype may be specified in one of the following ways.
Table with the following fields:
"time"
, "inactivity"
, "full"
, "empty"
, "item_count"
, "circuit"
, "robots_inactive"
, "fluid_count"
."and"
, or "or"
. Tells how this condition is to be compared with
the preceding conditions in the corresponding wait_conditions
array.type
is "time"
or "inactivity"
.type
is "item_count"
or "circuit"
.
Table with the following fields:
Table with the following fields:
Used for specifying where a GUI arrow should point to. It is a table:
"nowhere"
(will remove the arrow entirely), "goal"
(will point to the current goal), "entity_info"
, "active_window"
,
"entity"
, "position"
, "crafting_queue"
or "item_stack"
(will point to a given item stack in an
inventory). Depending on this value, other fields may have to be specified.type
"entity"
"position"
"crafting_queue"
"item_stack"
"player"
or "target"
.
Table with the following fields:
"entity"
(fires at an entity), "position"
(fires directly at a position),
or "direction"
(fires in a direction).true
, the gun will be able to shoot even when the target is out of range. Only applies when
target_type
is position
. The gun will fire at the maximum range in the direction of the target position.
Defaults to false
.0
.
It is a table with two fields:
Table with the following fields:
It is specified by string. It can be either the name of the sprite prototype defined in the data or path in form "type/name". Supported types are.
"item"
- for example "item/iron-plate" is the icon sprite of iron plate"entity"
- for example "entity/small-biter" is the icon sprite of the small biter"technology"
"recipe"
"item-group"
"fluid"
"tile"
"virtual-signal"
"achievement"
"equipment"
"file"
- path to an image file located inside the current scenario. This file is not preloaded so it will be slower; for frequently used sprites, it is better to define sprite prototype and use it instead."utility"
- sprite defined in the utility-sprites object, these are the pictures used by the game internally for the UI.
A sound specification defined by a string. It can be either the name of a sound prototype defined in the data or a path in the form "type/name". Supported types are.
"utility"
- a sound defined in the utility-sounds object, for example "utility/wire_connect_pole""ambient"
- a sound defined using the "ambient-sound" type, for example "ambient/resource-deficiency""tile-walking"
- for example "tile-walking/concrete""tile-build"
"tile-mined"
"entity-build"
- for example "entity-build/wooden-chest""entity-mined"
"entity-vehicle_impact"
"entity-open"
"entity-close"
Table with the following fields:
Table with the following fields:
0.6
means 60% increase.
This is a mapping of effect name to effect values given as a dictionary string → EffectValue.
{consumption={bonus=0.6},
speed={bonus=-0.15},
productivity={bonus=0.06},
pollution={bonus=0.075}}
This is a set of flags given as a dictionary string → boolean. When a flag is set, it is present
in the dictionary with the value true
. Unset flags aren't present in the dictionary at all.
So, the boolean value is meaningless and exists just for easy table lookup if a flag is set.
Possible flags are:
"not-rotatable"
"placeable-neutral"
"placeable-player"
"placeable-enemy"
"placeable-off-grid"
"player-creation"
"building-direction-8-way"
"filter-directions"
"fast-replaceable-no-build-while-moving"
"breaths-air"
"not-repairable"
"not-on-map"
"not-deconstructable"
"not-blueprintable"
"hide-from-bonus-gui"
"hide-alt-info"
"fast-replaceable-no-cross-type-while-moving"
"no-gap-fill-while-building"
"not-flammable"
"no-automated-item-removal"
"no-automated-item-insertion"
"no-copy-paste"
"not-selectable-in-game"
"not-upgradable"
A string specifying a collision mask layer.
Possible values for the string are:
"ground-tile"
"water-tile"
"resource-layer"
"doodad-layer"
"floor-layer"
"item-layer"
"ghost-layer"
"object-layer"
"player-layer"
"train-layer"
"layer-11"
"layer-12"
"layer-13"
"layer-14"
"layer-15"
"not-setup"
This is a set of masks given as a dictionary CollisionMaskLayer → boolean. Only set masks are present in the
dictionary and they have the value true
. Unset flags aren't present at all.
Table with the following fields:
"instant"
, "projectile"
, "flame-thrower"
, "beam"
, "stream"
Table with the following fields:
"direct"
, "area"
, "line"
, "cluster"
"all"
, "enemy"
, "ally"
. If "enemy"
, the trigger will only affect
entities whose force is different from the attacker's and for which there is no cease-fire set. "ally"
is the opposite of "enemy"
.
An array of TriggerItem
Table with the following fields:
1
is
the full circle).range
, the entity will choose a random distance between
range
and min_attack_distance
and attack from that distance. Used for spitters.
Table with the following fields:
"throw"
, "equipment-remote"
, "use-on-self"
.type
is "throw"
or "use-on-self"
.type
is "equipment-remote"
. It is the equipment
prototype name.
This is a set of flags given as a dictionary string → boolean. Set flags are present in the dictionary
with the value true
; unset flags aren't present at all.
Possible flags are:
"blueprint"
: Entities that can be selected for blueprint."deconstruct"
: Entities that can be marked for deconstruction."cancel-deconstruct"
: Entities that can be marked for deconstruction cancelling."items"
"trees"
"buildable-type"
: Buildable entities."nothing"
: Only select an area."items-to-place"
: Entities that can be placed using an item."any-entity"
"any-tile"
"same-force"
: Entities with the same force as the selector."not-same-force"
"friend"
"enemy"
"upgrade"
"cancel-upgrade"
"entity-with-health"
"entity-with-force"
"entity-with-owner"
Any basic type (string, number, boolean) plus tables.
A string that specifies where a gui element should be.
Possible values are:
"top-left"
"middle-left"
or just "left"
"bottom-left"
"top-center"
"middle-center"
or just "center"
"bottom-center"
"top-right"
"middle-right"
or just "right"
"bottom-right"
This is a set of flags given as a dictionary string → boolean. When a flag is set, it is present
in the dictionary with the value true
. Unset flags aren't present in the dictionary at all.
When setting flags, the flag "left-and-right"
can also be set, it will set "left"
and "right"
true.
Possible flags when reading are:
"left"
"right"
"middle"
"button-4"
"button-5"
"button-6"
"button-7"
"button-8"
"button-9"
It is specified by string.
"electricity"
"copy"
"not-allowed"
"pair"
"logistics"
"train-visualization"
It is specified by string.
"all"
- All forces pass."enemy"
- Forces which will attack pass."ally"
- Forces which won't attack pass."friend"
- Forces which are friends pass."not-friend"
- Forces which are not friends pass."same"
- The same force pass."not-same"
- The non-same forces pass.
A value between 0 and 255 inclusive represented by one of the following named string or string version of the value (for example "7"
and "decals"
are both valid).
"water-tile"
"ground-tile"
"tile-transition"
"decals"
"lower-radius-visualization"
"radius-visualization"
"transport-belt-integration"
"resource"
"building-smoke"
"decorative"
"ground-patch"
"ground-patch-higher"
"ground-patch-higher2"
"remnants"
"floor"
"transport-belt"
"transport-belt-endings"
"corpse"
"floor-mechanics"
"item"
"lower-object"
"transport-belt-circuit-connector"
"lower-object-above-shadow"
"object"
"higher-object-under"
"higher-object-above"
"item-in-inserter-hand"
"wires"
"wires-above"
"entity-info-icon"
"entity-info-icon-above"
"explosion"
"projectile"
"smoke"
"air-object"
"air-entity-info-icon"
"light-effect"
"selection-box"
"collision-selection-box"
"arrow"
"cursor"