Concepts

showcontrollergui :: boolean [RW]	Show the controller GUI elements.
showminimap :: boolean [RW]	Show the chart in the upper right-hand corner of the screen.
showresearchinfo :: boolean [RW]	Show research progress and name in the upper right-hand corner of the screen.
showentityinfo :: boolean [RW]	Show overlay icons on entities.
showalertgui :: boolean [RW]	Show the flashing alert icons next to the player's toolbar.
updateentityselection :: 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 MapGenFrequency

type MapGenSize

type MapGenRichness

type MapGenSettings

type SignalID

type ArithmeticCombinatorParameters

type ConstantCombinatorParameters

type DeciderCombinatorParameters

type CircuitCondition

type Filter

type SimpleItemStack

type Command

type SurfaceSpecification

type TrainSchedule

type GuiArrowSpecification

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

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}

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:

left_top :: Position
right_bottom :: Position

Example

Explicit specification:

{left_top = {-2, -3}, right_bottom = {5, 8}}

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:

r :: float (optional)
g :: float (optional)
b :: float (optional)
a :: float (optional)

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.

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

showminimap :: boolean [Read-Write]

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

showresearchinfo :: boolean [Read-Write]

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

showentityinfo :: boolean [Read-Write]

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

showalertgui :: boolean [Read-Write]

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

updateentityselection :: 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

type :: string: "item" or "fluid"
name :: string: Prototype name of the required item or fluid
amount :: uint: Amount of the item.

Product

Table with the following fields:

type :: uint: 0 for items, 1 for fluids.
name :: string: Prototype name of the result
amount :: float (optional): Amount of the item or fluid to give. If not specified, amount_min, amount_max and probability must all be specified.
amount_min :: uint (optional): Minimal amount of the item or fluid to give. Has no effect when amount is specified.
amount_max :: uint (optional): Maximum amount of the item or fluid to give. Has no effect when amount is specified.
probability :: double (optional): A value in range [0, 1]. Item or fluid is only given with this probability; otherwise no product is produced. Has no effect when amount is specified.

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

Loot

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

item :: string: Item prototype name of the result.
probability :: double: Probability that any loot at all will drop, as a number in range [0, 1].
count_min :: double: Minimum amount of loot to drop.
count_max :: double: Maximum amount of loot to drop.

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.

type :: string: Modifier type. Specifies which of the other fields will be available. Possible values are "inserter-stack-size-bonus", "laboratory-speed", "character-logistic-slots", "character-logistic-trash-slots", "num-quick-bars", "maximum-following-robots-count", "logistic-robot-speed", "logistic-robot-storage", "ghost-time-to-live", "turret-attack", "ammo-damage", "give-item", "gun-speed", "unlock-recipe".
Depending on type
- "gun-speed"
  - ammo_category :: string: Prototype name of the ammunition category that is affected
  - modifier :: double: Modification value. This will be added to the current gun speed modifier upon researching.
- "give-item"
  - item :: string: Item prototype name to give.
  - count :: uint (optional): Number of items to give. Defaults to 1.
- "turret-attack"
  - turret_id :: string: Turret prototype name this modifier will affect.
  - modifier :: double: Modification value. This will be added to the current turret speed modifier upon researching.
- "unlock-recipe"
  - recipe :: string: Recipe prototype name to unlock.
- others
  - modifier :: double: Modification value. This value will be added to the variable it modifies.

AutoplaceSpecification

Table with the following fields:

sharpness :: double
max_probability :: double
placement_density :: uint
richness_base :: double
richness_multiplier :: double
order :: string
peaks :: array of peak (optional): A peak is a table:
- influence :: double
- max_influence :: double
- min_influence :: double
- richness_influence :: double
- noisePersistence :: double
- noise_layer :: string (optional): Prototype name of the noise layer
- noise_octaves_difference :: double
- d_optimal :: double: d is the dimension name; this attribute may occur multiple times, once for each dimension, every time with a different prefix.
- d_range :: double: d is the dimension name.
- d_top_property_limit :: double: d is the dimension name.
- d_max_range :: double: d is the dimension name.
control :: string (optional): Control prototype name
tile_restriction :: array of restriction (optional): Restriction is a table:
- first :: string (optional): Tile prototype name
- second :: string (optional): Second prototype name
size_control_multiplier :: double
force :: string
random_probability_penalty :: double

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:

decrease :: float: Absolute damage decrease
percent :: float: Percentual damage decrease

MapGenFrequency

It is a string specifying frequency. Possible values are

"none"
"very-low"
"low"
"normal"
"high"
"very-high"

MapGenSize

It is a string specifying size. Possible values are

"none"
"very-small"
"small"
"medium"
"big"
"very-big"

MapGenRichness

A string specifying richness. Possible values are

"very-poor"
"poor"
"regular"
"good"
"very-good"

MapGenSettings

Table with the following fields:

terrain_segmentation :: MapGenFrequency
water :: MapGenSize
autoplace_controls :: dictionary string → table: Each table of this dictionary has the following fields:
- frequency :: MapGenFrequency
- size :: MapGenSize
- richness :: MapGenRichness
seed :: uint: The random seed used to generated this map.
shift :: Position: How much the (0, 0) tile is shifted from what would have been generated otherwise.
width :: uint: Width in tiles. If 0, the map has infinite width.
height :: uint: Height in tiles. If 0, the map has infinite height.
peaceful_mode :: boolean: Whether peaceful mode is enabled for this map.

SignalID

Table with the following fields:

type :: string: "item", "fluid", or "virtual".
name :: string (optional): Name of the item, fluid or virtual signal.

ArithmeticCombinatorParameters

Table with the following fields:

first_signal :: SignalID (optional): Defaults to blank
second_signal :: SignalID (optional): Second signal to use in an operation. If not specified, the second argument will be the value of constant.
constant :: int (optional): Constant to use as the second argument of the operation. Has no effect when second_signal is set. Defaults to 0.
operation :: string (optional): Must be one of "*", "/", "+", "-". When not specified, defaults to "*".
output_signal :: SignalID (optional): Specifies the signal to output.

ConstantCombinatorParameters

This is an array of tables with the following fields:

signal :: SignalID: Signal to emit.
count :: uint: Value of the signal to emit.
index :: uint: Index of the constant combinator's slot to set this signal to.

DeciderCombinatorParameters

Table with the following fields:

first_signal :: SignalID (optional): Defaults to blank.
second_signal :: SignalID (optional): Second signal to use in an operation, if any. If this is not specified, the second argument to a decider combinator's operation is assumed to be the value of constant.
constant :: uint (optional): Constant to use as the second argument of operation. Defaults to 0.
comparator :: string (optional): Must be one of "<", ">", "=". Specifies how the inputs should be compared. If not specified, defaults to ">".
output_signal :: SignalID (optional): Defaults to blank.
copy_count_from_input :: boolean (optional): Defaults to true. When false, will output a value of 1 for on the given output_signal.

CircuitCondition

Table with the following fields:

comparator :: string (optional): Must be one of "<", ">", "=". Specifies how the inputs should be compared. If not specified, defaults to ">".
first_signal :: SignalID (optional): Defaults to blank
second_signal :: SignalID (optional): What to compare first_signal to. If not specified, first_signal will be compared to constant.
constant :: int (optional): Constant to compare 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.

Filter

Table with the following fields:

index :: uint: Position of the corresponding filter slot.
name :: string: Item prototype name of the item to filter.

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:

name :: string: Prototype name of the item the stack holds.
count :: uint (optional): Number of items the stack holds. If not specified, defaults to 1.
health :: float (optional): Health of the items in the stack. Defaults to 1.0.

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:

type :: defines.command: Type of command. The remaining fields depend on the value of this field.
Depending on type
- defines.command.attack
  - target :: LuaEntity
  - distraction :: defines.distraction (optional): Defaults to defines.distraction.by_enemy.
- defines.command.go_to_location
  - destination :: Position
  - distraction :: defines.distraction (optional): Defaults to defines.distraction.by_enemy.
- defines.command.compound
  - structure_type :: defines.compoundcommandtype: How the commands should be chained together.
  - commands :: array of Command: The sub-commands.
- defines.command.group
  - group :: LuaUnitGroup: The group whose command to follow.
  - distraction :: defines.distraction (optional): Defaults to defines.distraction.by_enemy.
- defines.command.attack_area
  - destination :: Position: Centre of the attack area.
  - radius :: double: Radius of the attack area.
  - distraction :: defines.distraction (optional): Defaults to defines.distraction.by_enemy.
- defines.command.wander
  - distraction :: defines.distraction (optional): Defaults to defines.distraction.by_enemy.
- defines.command.build_base
  - destination :: Position: Where to build the base.
  - distraction :: defines.distraction (optional): Defaults to defines.distraction.by_enemy.
  - ignore_planner :: boolean (optional): Whether the units should ignore expansion candidate chunks. When false, they will obey and not build a base in a non-candidate chunk. Defaults to false.

SurfaceSpecification

A surface may be specified in one of three ways.

As an uint: It will be the index of the surface. nauvis has index 1, the first user-created surface will have index 2 and so on.
As a string: It will be the surface name. E.g. "nauvis".
As a LuaSurface: If you have a reference to LuaSurface, you may pass it directly.

TrainSchedule

Table with the following fields:

current :: uint: Current stop on the schedule.
records :: array of table: Each record has the following fields:
- station :: string: Station name
- time_to_wait :: uint: Number of ticks to wait at the station.

GuiArrowSpecification

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

type :: string: This determines which of the following fields will be required. Must be one of "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.
Depending on type
- "entity"
  - entity :: LuaEntity
- "position"
  - position :: Position
- "crafting_queue"
  - crafting_queueindex :: uint: Index in the crafting queue to point to.
- "item_stack"
  - inventory_index :: defines.inventory: Which inventory the stack is in.
  - item_stack_index :: uint: Which stack to point to.
  - source :: string: Must be either "player" or "target".