Factorio » ConceptsFactorio 0.14.21

Concepts

Commonly used conventions for passing data between mods and Factorio

type LocalisedString
type Position
type ChunkPosition
type Vector
type BoundingBox
type Color
struct GameViewSettings
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.
struct TileProperties
tier_from_start :: double [RW]
roughness :: double [RW]
elevation :: double [RW]
available_water :: double [RW]
temperature :: double [RW]
type MapSettings
type Ingredient
type Product
type Loot
type Modifier
type AutoplaceSpecification
type Resistances
type MapGenSize
type MapGenSettings
type SignalID
type Signal
type ArithmeticCombinatorParameters
type ConstantCombinatorParameters
type DeciderCombinatorParameters
type CircuitCondition
type CircuitConditionSpecification
type Filter
type SimpleItemStack
type Command
type SurfaceSpecification
type WaitCondition
type TrainScheduleRecord
type TrainSchedule
type GuiArrowSpecification
type AmmoType
type SpritePath
type ModConfigurationChangedData
type ConfigurationChangedData
type EffectValue
type EntityPrototypeFlags
type CollisionMask
type TriggerEffectItem
type TriggerDelivery
type TriggerItem
type AttackParameters
type CapsuleAction
type SelectionModeFlags

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.local_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.local_player.print{"description.durability", 5, 9}
Example
This will print "hello" in all translations:
game.local_player.print{"", "hello"}

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

See also

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.

Members:

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

Color

Red, green, blue and alpha values, all in range [0, 1]. All values here are optional; colour 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 colour 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

GameViewSettings

Parameters that affect the look and control of the game. Updating any of the member attributes here will immediatelly 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.

TileProperties

Properties of a tile. Updating any of the member attributes here will immediatelly 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]

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

Ingredient

An ingredient is a table

Product

Table with the following fields:

Example
Products of the "steel-chest" recipe (an array of Product)
{{type=0, name="steel-chest", amount=1}}
Example
Products of the "advanced-oil-processing" recipe
{{type=1, name="heavy-oil", amount=1},
 {type=1, name="light-oil", amount=4.5},
 {type=1, 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}}
See also

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.

AutoplaceSpecification

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 string specifying an amount. Possible values are:

Each of the values in a triplet (such as "low", "small", and "poor") are synonymous.

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:

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:

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:

SurfaceSpecification

A surface may be specified in one of three 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:

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.

ModConfigurationChangedData

Table with the following fields:

ConfigurationChangedData

Table with the following fields:

EffectValue

Table with the following fields:

EntityPrototypeFlags

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.

Possible flags are:

CollisionMask

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

Possible masks are:

TriggerEffectItem

Table with the following fields:

TriggerDelivery

Table with the following fields:

TriggerItem

Table with the following fields:

AttackParameters

Table with the following fields:

CapsuleAction

Table with the following fields:

SelectionModeFlags

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: