Concepts

Commonly used conventions for passing data between mods and Factorio

type LocalisedString
type DisplayResolution
type Position
type ChunkPosition
type TilePosition
type OldTileAndPosition
type Vector
type BoundingBox
type ScriptArea
type ScriptPosition
type Color
type PathFindFlags
struct GameViewSettings - sort
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.
struct TileProperties - sort
tier_from_start :: double [RW]
roughness :: double [RW]
elevation :: double [RW]
available_water :: double [RW]
temperature :: double [RW]
type MapViewSettings
type MapSettings
type DifficultySettings
type Fluid
type Ingredient
type Product
type Loot
type Modifier
type Offer
type AutoplaceSpecification
type NoiseExpression
type Resistances
type MapGenSize
type AutoplaceSettings
type CliffPlacementSettings
type MapGenSettings
type SignalID
type Signal
type UpgradeFilter
type InfinityContainerFilter
type InfinityPipeFilter
type HeatSetting
type FluidBoxConnection
type ArithmeticCombinatorParameters
type ConstantCombinatorParameters
type DeciderCombinatorParameters
type CircuitCondition
type CircuitConditionSpecification
type Filter
type PlaceAsTileResult
type SimpleItemStack
type Command
type PathfindFlags
type ForceSpecification
type TechnologySpecification
type SurfaceSpecification
type PlayerSpecification
type ItemStackSpecification
type EntityPrototypeSpecification
type ItemPrototypeSpecification
type WaitCondition
type TrainScheduleRecord
type TrainSchedule
type GuiArrowSpecification
type AmmoType
type BeamTarget
type RidingState
type SpritePath
type SoundPath
type ModConfigurationChangedData
type ConfigurationChangedData
type EffectValue
type Effects
type EntityPrototypeFlags
type CollisionMaskLayer
type CollisionMask
type TriggerEffectItem
type TriggerDelivery
type TriggerItem
type Trigger
type AttackParameters
type CapsuleAction
type SelectionModeFlags
type LogisticFilter
type ModSetting
type Any
type ProgrammableSpeakerParameters
type ProgrammableSpeakerAlertParameters
type ProgrammableSpeakerCircuitParameters
type ProgrammableSpeakerInstrument
type Alignment
type NthTickEvent
type ScriptRenderTarget
type MouseButtonFlags
type CursorBoxRenderType
type ForceCondition
type RenderLayer

LocalisedString

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.

Example
In the English translation, this will print "No ammo"; in the Czech translation, it will print "Bez munice":
game.player.print{"description.no-ammo"}
The description.no-ammo template contains no placeholders, so no further parameters are necessary.
Example
In the English translation, this will print "Durability: 5/9"; in the Japanese one, it will print "耐久度: 5/9":
game.player.print{"description.durability", 5, 9}
Example
This will print "hello" in all translations:
game.player.print{"", "hello"}

DisplayResolution

Members:

Position

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.

Example
{10, 20}
Example
{x = 50, y = 20}
{y = 20, x = 50}

ChunkPosition

Coordinates of a chunk in a LuaSurface where each integer x/y represents a different chunk. This uses the same format as

See also

TilePosition

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

See also

OldTileAndPosition

Members:

Vector

A vector is a two-element array containing the x and y components. Unlike Positions, vectors don't use the x, y keys.

Example
right = {1.0, 0.0}

BoundingBox

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:

Example
Explicit specification:
{left_top = {-2, -3}, right_bottom = {5, 8}}
Example
Shorthand:
{{-2, -3}, {5, 8}}

ScriptArea

An area defined using the map editor.

Members:

ScriptPosition

A position defined using the map editor.

Members:

Color

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:

Example
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

PathFindFlags

A table with one or more of the following values.

Members:

GameViewSettings

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_controller_gui :: boolean [Read-Write]

Show the controller GUI elements. This includes the toolbar, the selected tool slot, the armour slot, and the gun and ammunition slots.

show_minimap :: boolean [Read-Write]

Show the chart in the upper right-hand corner of the screen.

show_research_info :: boolean [Read-Write]

Show research progress and name in the upper right-hand corner of the screen.

show_entity_info :: boolean [Read-Write]

Show overlay icons on entities. Also known as "alt-mode".

show_alert_gui :: boolean [Read-Write]

Show the flashing alert icons next to the player's toolbar.

update_entity_selection :: boolean [Read-Write]

When true (the default), mousing over an entity will select it. Otherwise, moving the mouse won't update entity selection.

show_rail_block_visualisation :: boolean [Read-Write]

When true (false is default), the rails will always show the rail block visualisation.

show_side_menu :: boolean [Read-Write]

Shows or hides the buttons row.

show_map_view_options :: boolean [Read-Write]

Shows or hides the view options when map is opened.

show_quickbar :: boolean [Read-Write]

Shows or hides quickbar of shortcuts.

show_shortcut_bar :: boolean [Read-Write]

Shows or hides the shortcut bar.

TileProperties

Properties of a tile. Updating any of the member attributes here will immediately take effect in the game engine.

tier_from_start :: double [Read-Write]

roughness :: double [Read-Write]

elevation :: double [Read-Write]

available_water :: double [Read-Write]

temperature :: double [Read-Write]

MapViewSettings

What is shown in the map view. If a field is not given, that setting will not be changed.

MapSettings

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.

Example
Increase the number of short paths the pathfinder can cache.
game.map_settings.path_finder.short_cache_size = 15

DifficultySettings

Technology and recipe difficulty settings.

Fluid

Fluid is represented as a table

Ingredient

An ingredient is a table

Product

Table with the following fields:

Example
Products of the "steel-chest" recipe (an array of Product)
{{type="item", name="steel-chest", amount=1}}
Example
Products of the "advanced-oil-processing" recipe
{{type="fluid", name="heavy-oil", amount=1},
 {type="fluid", name="light-oil", amount=4.5},
 {type="fluid", name="petroleum-gas", amount=5.5}}
Example
What a custom recipe would look like that had a probability of 0.5 to return a minimum amount of 1 and a maximum amount of 5
{{type=0, name="custom-item", probability=0.5, amount_min=1, amount_max=5}}

Loot

Loot is an array of loot items. Each loot item is a table:

Modifier

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.

Offer

A single offer on a market entity.

Table with the following fields:

AutoplaceSpecification

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:

NoiseExpression

Table with the following fields:

Resistances

Dictionary of resistances toward each damage type. It is a dictionary indexed by damage type names (see data/base/prototypes/damage-type.lua). Each resistance is a table:

MapGenSize

A float or a string specifying an amount. Possible values for the string are:

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.

AutoplaceSettings

Table with the following fields:

CliffPlacementSettings

Table with the following fields:

MapGenSettings

Table with the following fields:

SignalID

Table with the following fields:

Signal

An actual signal transmitted by the network.

Table with the following fields:

UpgradeFilter

Table with the following fields:

InfinityContainerFilter

A single filter used by an infinity-container type entity.

Table with the following fields:

InfinityPipeFilter

A single filter used by an infinity-pipe type entity.

Table with the following fields:

HeatSetting

The settings used by a heat-interface type entity.

Table with the following fields:

FluidBoxConnection

A definition of a fluidbox connection point.

Table with the following fields:

ArithmeticCombinatorParameters

Table with the following fields:

ConstantCombinatorParameters

This is an array of tables with the following fields:

DeciderCombinatorParameters

Table with the following fields:

CircuitCondition

Table with the following fields:

CircuitConditionSpecification

Table with the following fields:

Filter

Table with the following fields:

PlaceAsTileResult

Table with the following fields:

SimpleItemStack

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:

Example
Both of these lines specify an item stack of one iron plate:
{name="iron-plate"}
{name="iron-plate", count=1}
Example
This is a stack of 47 copper plates:
{name="copper-plate", count=47}
Example
These are both full stacks of iron plates (for iron-plate, a full stack is 100 plates):
"iron-plate"
{name="iron-plate", count=100}

Command

Commands can be given to enemies and unit groups. It is a table:

PathfindFlags

Table with the following fields:

ForceSpecification

A force may be specified in one of two ways.

TechnologySpecification

A technology may be specified in one of three ways.

SurfaceSpecification

A surface may be specified in one of three ways.

PlayerSpecification

A player may be specified in one of three ways.

ItemStackSpecification

An item may be specified in one of the following ways.

EntityPrototypeSpecification

An entity prototype may be specified in one of the following ways.

ItemPrototypeSpecification

An item prototype may be specified in one of the following ways.

WaitCondition

Table with the following fields:

TrainScheduleRecord

Table with the following fields:

TrainSchedule

Table with the following fields:

GuiArrowSpecification

Used for specifying where a GUI arrow should point to. It is a table:

AmmoType

Table with the following fields:

BeamTarget

Table with the following fields:

RidingState

It is a table with two fields:

Table with the following fields:

SpritePath

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.

SoundPath

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.

ModConfigurationChangedData

Table with the following fields:

ConfigurationChangedData

Table with the following fields:

EffectValue

Table with the following fields:

Effects

This is a mapping of effect name to effect values given as a dictionary stringEffectValue.

Example
These are the effects of the vanilla Productivity Module 3 (up to floating point imprecisions):
{consumption={bonus=0.6},
 speed={bonus=-0.15},
 productivity={bonus=0.06},
 pollution={bonus=0.075}}

EntityPrototypeFlags

This is a set of flags given as a dictionary stringboolean. 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:

CollisionMaskLayer

A string specifying a collision mask layer.

Possible values for the string are:

CollisionMask

This is a set of masks given as a dictionary CollisionMaskLayerboolean. Only set masks are present in the dictionary and they have the value true. Unset flags aren't present at all.

TriggerEffectItem

Table with the following fields:

TriggerDelivery

Table with the following fields:

TriggerItem

Table with the following fields:

Trigger

An array of TriggerItem

AttackParameters

Table with the following fields:

CapsuleAction

Table with the following fields:

SelectionModeFlags

This is a set of flags given as a dictionary stringboolean. Set flags are present in the dictionary with the value true; unset flags aren't present at all.

Possible flags are:

LogisticFilter

Table with the following fields:

ModSetting

Table with the following fields:

Any

Any basic type (string, number, boolean) plus tables.

ProgrammableSpeakerParameters

Table with the following fields:

ProgrammableSpeakerAlertParameters

Table with the following fields:

ProgrammableSpeakerCircuitParameters

Table with the following fields:

ProgrammableSpeakerInstrument

Table with the following fields:

Alignment

A string that specifies where a gui element should be.

Possible values are:

NthTickEvent

Table with the following fields:

ScriptRenderTarget

Table with the following fields:

MouseButtonFlags

This is a set of flags given as a dictionary stringboolean. 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:

CursorBoxRenderType

It is specified by string.

ForceCondition

It is specified by string.

RenderLayer

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