Factorio API Docs

1.1.56 <>

Concepts

Commonly used conventions for passing data between mods and Factorio.

LocalisedString concept

Localised strings are a way to support translation of in-game text.




RealOrientation concept

The smooth orientation.


MapPosition table_or_array

Coordinates on a surface, for example of an entity.


ChunkPosition table_or_array

Coordinates of a chunk in a LuaSurface where each integer x/y represents a different chunk.


TilePosition table_or_array

Coordinates of a tile on a LuaSurface where each integer x/y represents a different tile.


EquipmentPosition table_or_array

Position inside an equipment grid.


GuiLocation table_or_array

Screen coordinates of a GUI element in a LuaGui.


ChunkPositionAndArea table

A ChunkPosition with an added bounding box for the area of the chunk.


EquipmentPoint table

A table used to define a manual shape for a piece of equipment.


GuiAnchor table



Tags concept

A dictionary of string to the four basic Lua types: string, boolean, number, table.


SmokeSource table

Vector concept

A vector is a two-element array containing the x and y components.


BoundingBox table_or_array

Two positions, specifying the top-left and bottom-right corner of the box respectively.


ScriptArea table

An area defined using the map editor.


ScriptPosition table

A position defined using the map editor.


Color table_or_array

Red, green, blue and alpha values, all in range [0, 1] or all in range [0, 255] if any value is > 1.


ColorModifier table_or_array

Same as Color, but red, green, blue and alpha values can be any floating point number, without any special handling of the range [1, 255].



Alert table

ScriptRenderVertexTarget table

One vertex of a ScriptRenderPolygon.




Decorative table


ChartTagSpec table

GameViewSettings struct

Parameters that affect the look and control of the game.


MapViewSettings table

What is shown in the map view.


PollutionMapSettings table

These values are for the time frame of one second (60 ticks).


EnemyEvolutionMapSettings table

These values represent a percentual increase in evolution.


EnemyExpansionMapSettings table

Candidate chunks are given scores to determine which one of them should be expanded into.






MapSettings table

Various game-related settings.


DifficultySettings table

Technology and recipe difficulty settings.


MapAndDifficultySettings table

All regular MapSettings plus an additional table that contains the DifficultySettings.


MapExchangeStringData table

The data that can be extracted from a map exchange string, as a plain table.




BlueprintEntity table

The representation of an entity inside of a blueprint.


Tile table

Fluid table

Ingredient table

Product table

Loot table

TechnologyModifier table

The effect that is applied when a technology is researched.


Offer table

A single offer on a market entity.


AutoplaceSpecification table

Specifies how probability and richness are calculated when placing something on the map.


NoiseExpression table

A fragment of a functional program used to generate coherent noise, probably for purposes related to terrain generation.




Resistance table

MapGenSize concept

A floating point number specifying an amount.






MapGenSettings table

The 'map type' dropdown in the map generation GUI is actually a selector for elevation generator.


SignalID table

Signal table

An actual signal transmitted by the network.



InfinityInventoryFilter table

A single filter used by an infinity-filters instance.


InfinityPipeFilter table

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




HeatSetting table

The settings used by a heat-interface type entity.



FluidBoxConnection table

A definition of a fluidbox connection point.













Command table

Commands can be given to enemies and unit groups.


















GuiArrowSpecification table

Used for specifying where a GUI arrow should point to.


AmmoType table

BeamTarget table

RidingState table

SpritePath concept

It is specified by string.


SoundPath concept

A sound defined by a string.




EntityPrototypeFlags flag

This is a set of flags given as a dictionary[stringboolean].


ItemPrototypeFlags flag

This is a set of flags given as dictionary[stringboolean].


CollisionMaskLayer concept

A string specifying a collision mask layer.


CollisionMask concept

This is a set of masks given as a dictionary[CollisionMaskLayerboolean].


CollisionMaskWithFlags concept

A CollisionMask which also includes any flags this mask has.


TriggerTargetMask concept

This is a set of trigger target masks given as a dictionary[stringboolean].




TriggerItem table


CircularProjectileCreationSpecification concept

An array with the following members:
- A RealOrientation
- A Vector





SelectionModeFlags flag

This is a set of flags given as a dictionary[stringboolean].



ModSetting table

AnyBasic concept

Any basic type (string, number, boolean) or table.


Any concept

Any basic type (string, number, boolean), table, or LuaObject.






Alignment enum

A string that specifies where a gui element should be.


EventData table

Information about the event that has been raised.








MouseButtonFlags concept

This is a set of flags given as a dictionary[stringboolean].




RenderLayer concept

A value between 0 and 255 inclusive represented by one of the following named string or string version of the value (for example "27" and "decals" are both valid).





SoundType enum

Defines which slider in the game's sound settings affects the volume of this sound.












EventFilter concept

Used to filter out irrelevant event callbacks in a performant way.





















concept 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. Localised strings can not be recursed deeper than 20 levels and can not have more than 20 parameters.

As a special case, when the key is just the empty string, all the parameters will be concatenated (after processing, if any are localised strings). If there is only one parameter, it 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, as well as a number or boolean, which will be converted to their textual representation.

Examples

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.

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

This will print "hello" in all translations:

game.player.print({"", "hello"})

This will print "Iron plate: 60" in the English translation and "Eisenplatte: 60" in the German translation.

game.print({"", {"item-name.iron-plate"}, ": ", 60})

table DisplayResolution

Fields

width
:: uint

height
:: uint

table LogisticParameters

Fields

name
:: string?

The item. nil clears the filter.


min
:: uint?

max
:: uint?

concept RealOrientation

The smooth orientation. It is a float in the range [0, 1) that covers a full circle, starting at the top and going clockwise. This means a value of 0 indicates "north", a value of 0.5 indicates "south".

For example then, a value of 0.625 would indicate "south-west", and a value of 0.875 would indicate "north-west".


table_or_array MapPosition

Coordinates on a surface, for example of an entity. MapPositions may be specified either as a dictionary with x, y as keys, or simply as an array with two elements.

The coordinates are saved as a fixed-size 32 bit integer, with 8 bits reserved for decimal precision, meaning the smallest value step is 1/2^8 = 0.00390625 tiles.

Fields

x
:: double

y
:: double

Examples

Explicit definition:

{x = 5.5, y = 2}
{y = 2.25, x = 5.125}

Shorthand:

{1.625, 2.375}

table_or_array ChunkPosition

Coordinates of a chunk in a LuaSurface where each integer x/y represents a different chunk. This uses the same format as MapPosition, meaning it can be specified either with or without explicit keys. A MapPosition can be translated to a ChunkPosition by dividing the x/y values by 32.

Fields

x
:: int

y
:: int

table_or_array TilePosition

Coordinates of a tile on a LuaSurface where each integer x/y represents a different tile. This uses the same format as MapPosition, except it rounds any non-integer x/y down to whole numbers. It can be specified either with or without explicit keys.

Fields

x
:: int

y
:: int

table_or_array EquipmentPosition

Position inside an equipment grid. This uses the same format as MapPosition, meaning it can be specified either with or without explicit keys.

Fields

x
:: int

y
:: int

Examples

Explicit definition:

{x = 5, y = 2}
{y = 2, x = 5}

Shorthand:

{1, 2}

table_or_array GuiLocation

Screen coordinates of a GUI element in a LuaGui. This uses the same format as TilePosition, meaning it can be specified either with or without explicit keys.

Fields

x
:: int

y
:: int

table ChunkPositionAndArea

A ChunkPosition with an added bounding box for the area of the chunk.

Fields

x
:: int

y
:: int

area

table EquipmentPoint

A table used to define a manual shape for a piece of equipment.

Fields

x
:: uint

y
:: uint

table GuiAnchor

Fields



type
:: string?

If provided, only anchors the GUI element when the opened things type matches the type.


name
:: string?

If provided, only anchors the GUI element when the opened thing matches the name. name takes precedence over names.


names
:: array[string]?

If provided, only anchors the GUI element when the opened thing matches one of the names. When reading an anchor, names is always populated.


table TabAndContent

Fields

tab

content

table OldTileAndPosition

Fields

old_tile

position

concept Tags

A dictionary of string to the four basic Lua types: string, boolean, number, table.

Example

{a = 1, b = true, c = "three", d = {e = "f"}}

table SmokeSource

Fields

name
:: string

frequency
:: double

offset
:: double

position
:: Vector?

north_position
:: Vector?

east_position
:: Vector?

south_position
:: Vector?

west_position
:: Vector?

deviation

starting_frame_speed
:: uint16

starting_frame_speed_deviation
:: double

starting_frame
:: uint16

starting_frame_deviation
:: double

slow_down_factor
:: uint8

height
:: float

height_deviation
:: float

starting_vertical_speed
:: float

starting_vertical_speed_deviation
:: float

vertical_speed_slowdown
:: float

Note

The vectors for all 5 position attributes are a table with x and y keys instead of an array.


concept Vector

A vector is a two-element array containing the x and y components. In some specific cases, the vector is a table with x and y keys instead, which the documentation will point out.

Example

right = {1.0, 0.0}

table_or_array BoundingBox

Two positions, specifying the top-left and bottom-right corner of the box respectively. Like with MapPosition, 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.

Fields

left_top

right_bottom

orientation

Examples

Explicit definition:

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

Shorthand:

{{-2, -3}, {5, 8}}

table ScriptArea

An area defined using the map editor.

Fields

area

name
:: string

color
:: Color

id
:: uint

table ScriptPosition

A position defined using the map editor.

Fields

position

name
:: string

color
:: Color

id
:: uint

table_or_array Color

Red, green, blue and alpha values, all in range [0, 1] or all in range [0, 255] if any value is > 1. All values here are optional. Color channels default to 0, the alpha channel defaults to 1.

Similar to MapPosition, Color allows the short-hand notation of passing an array of exactly 3 or 4 numbers. The game usually expects colors to be in pre-multiplied form (color channels are pre-multiplied by alpha).

Fields

r
:: float?

g
:: float?

b
:: float?

a
:: float?

Example

red1 = {r = 0.5, g = 0, b = 0, a = 0.5}  -- Half-opacity red
red2 = {r = 0.5, a = 0.5}                -- Same color as red1
black = {}                               -- All channels omitted: black
red1_short = {0.5, 0, 0, 0.5}            -- Same color as red1 in short-hand notation

table_or_array ColorModifier

Same as Color, but red, green, blue and alpha values can be any floating point number, without any special handling of the range [1, 255].

Fields

r
:: float?

g
:: float?

b
:: float?

a
:: float?

table CraftingQueueItem

Fields

index
:: uint

The index of the item in the crafting queue.


recipe
:: string

The recipe being crafted.


count
:: uint

The amount of items being crafted.


table Alert

Fields

tick
:: uint

The tick this alert was created.


target
:: LuaEntity?

prototype

position

icon
:: SignalID?

The SignalID used for a custom alert. Only present for custom alerts.


message

The message for a custom alert. Only present for custom alerts.


table ScriptRenderVertexTarget

One vertex of a ScriptRenderPolygon.

Fields

target

target_offset
:: Vector?

Only used if target is a LuaEntity.


table PathfinderWaypoint

Fields

position

The position of the waypoint on its surface.


needs_destroy_to_reach
:: boolean

true if the path from the previous waypoint to this one goes through an entity that must be destroyed.


table CutsceneWaypoint

Fields

position

Position to pan the camera to.


target

Entity or unit group to pan the camera to.


transition_time
:: uint

How many ticks it will take to reach this waypoint from the previous one.


time_to_wait
:: uint

Time in ticks to wait before moving to the next waypoint.


zoom
:: double?

Zoom level to be set when the waypoint is reached. When not specified, the previous waypoint's zoom is used.


table Decorative

Fields

name
:: string

The name of the decorative prototype.


position

amount
:: uint8

table DecorativeResult

Fields

position

decorative

amount
:: uint

table ChartTagSpec

Fields

position

icon
:: SignalID?

text
:: string?

last_user

Note

Either icon, text, or both must be provided.


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

Attributes

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.


table MapViewSettings

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

Fields

show-logistic-network
:: boolean?

show-electric-network
:: boolean?

show-turret-range
:: boolean?

show-pollution
:: boolean?

show-train-station-names
:: boolean?

show-player-names
:: boolean?

show-networkless-logistic-members
:: boolean?

show-non-standard-map-info
:: boolean?

table PollutionMapSettings

These values are for the time frame of one second (60 ticks).

Fields

enabled
:: boolean

Whether pollution is enabled at all.


diffusion_ratio
:: double

The amount that is diffused to a neighboring chunk (possibly repeated for other directions as well). Defaults to 0.02.


min_to_diffuse
:: double

The amount of PUs that need to be in a chunk for it to start diffusing. Defaults to 15.


aeging
:: double

The amount of pollution eaten by a chunk's tiles as a percentage of 1. Defaults to 1.


expected_max_per_chunk
:: double

Any amount of pollution larger than this value is visualized as this value instead. Defaults to 150.


min_to_show_per_chunk
:: double

Any amount of pollution smaller than this value (but bigger than zero) is visualized as this value instead. Defaults to 50.


min_pollution_to_damage_trees
:: double

Defaults to 60.


pollution_with_max_forest_damage
:: double

Defaults to 150.


pollution_per_tree_damage
:: double

Defaults to 50.


pollution_restored_per_tree_damage
:: double

Defaults to 10.


max_pollution_to_restore_trees
:: double

Defaults to 20.


enemy_attack_pollution_consumption_modifier
:: double

Defaults to 1.


table EnemyEvolutionMapSettings

These values represent a percentual increase in evolution. This means a value of 0.1 would increase evolution by 10%.

Fields

enabled
:: boolean

Whether enemy evolution is enabled at all.


time_factor
:: double

The amount evolution naturally progresses by every second. Defaults to 0.000004.


destroy_factor
:: double

The amount evolution progresses for every destroyed spawner. Defaults to 0.002.


pollution_factor
:: double

The amount evolution progresses for every unit of pollution. Defaults to 0.0000009.


table EnemyExpansionMapSettings

Candidate chunks are given scores to determine which one of them should be expanded into. This score takes into account various settings noted below. The iteration is over a square region centered around the chunk for which the calculation is done, and includes the central chunk as well. Distances are calculated as Manhattan distance.

The pseudocode algorithm to determine a chunk's score is as follows:

player = 0
for neighbour in all chunks within enemy_building_influence_radius from chunk:
  player += number of player buildings on neighbour
          * building_coefficient
          * neighbouring_chunk_coefficient^distance(chunk, neighbour)

base = 0
for neighbour in all chunk within friendly_base_influence_radius from chunk:
  base += num of enemy bases on neighbour
          * other_base_coefficient
          * neighbouring_base_chunk_coefficient^distance(chunk, neighbour)

score(chunk) = 1 / (1 + player + base)

Fields

enabled
:: boolean

Whether enemy expansion is enabled at all.


max_expansion_distance
:: uint

Distance in chunks from the furthest base around to prevent expansions from reaching too far into the player's territory. Defaults to 7.


friendly_base_influence_radius
:: uint

Defaults to 2.


enemy_building_influence_radius
:: uint

Defaults to 2.


building_coefficient
:: double

Defaults to 0.1.


other_base_coefficient
:: double

Defaults to 2.0.


neighbouring_chunk_coefficient
:: double

Defaults to 0.5.


neighbouring_base_chunk_coefficient
:: double

Defaults to 0.4.


max_colliding_tiles_coefficient
:: double

A chunk has to have at most this high of a percentage of unbuildable tiles for it to be considered a candidate to avoid chunks full of water as candidates. Defaults to 0.9, or 90%.


settler_group_min_size
:: uint

The minimum size of a biter group that goes to build a new base. This is multiplied by the evolution factor. Defaults to 5.


settler_group_max_size
:: uint

The maximum size of a biter group that goes to build a new base. This is multiplied by the evolution factor. Defaults to 20.


min_expansion_cooldown
:: uint

The minimum time between expansions in ticks. The actual cooldown is adjusted to the current evolution levels. Defaults to 4*3,600=14,400 ticks.


max_expansion_cooldown
:: uint

The maximum time between expansions in ticks. The actual cooldown is adjusted to the current evolution levels. Defaults to 60*3,600=216,000 ticks.


table UnitGroupMapSettings

Fields

min_group_gathering_time
:: uint

The minimum amount of time in ticks a group will spend gathering before setting off. The actual time is a random time between the minimum and maximum times. Defaults to 3,600 ticks.


max_group_gathering_time
:: uint

The maximum amount of time in ticks a group will spend gathering before setting off. The actual time is a random time between the minimum and maximum times. Defaults to 10*3,600=36,000 ticks.


max_wait_time_for_late_members
:: uint

After gathering has finished, the group is allowed to wait this long in ticks for delayed members. New members are not accepted anymore however. Defaults to 2*3,600=7,200 ticks.


min_group_radius
:: double

The minimum group radius in tiles. The actual radius is adjusted based on the number of members. Defaults to 5.0.


max_group_radius
:: double

The maximum group radius in tiles. The actual radius is adjusted based on the number of members. Defaults to 30.0.


max_member_speedup_when_behind
:: double

The maximum speed a percentage of its regular speed that a group member can speed up to when catching up with the group. Defaults to 1.4, or 140%.


max_member_slowdown_when_ahead
:: double

The minimum speed a percentage of its regular speed that a group member can slow down to when ahead of the group. Defaults to 0.6, or 60%.


max_group_slowdown_factor
:: double

The minimum speed as a percentage of its maximum speed that a group will slow down to so members that fell behind can catch up. Defaults to 0.3, or 30%.


max_group_member_fallback_factor
:: double

When a member of a group falls back more than this factor times the group radius, the group will slow down to its max_group_slowdown_factor speed to let them catch up. Defaults to 3.


member_disown_distance
:: double

When a member of a group falls back more than this factor times the group radius, it will be dropped from the group. Defaults to 10.


tick_tolerance_when_member_arrives
:: uint

max_gathering_unit_groups
:: uint

The maximum number of automatically created unit groups gathering for attack at any time. Defaults to 30.


max_unit_group_size
:: uint

The maximum number of members for an attack unit group. This only affects automatically created unit groups, manual groups created through the API are unaffected. Defaults to 200.


table SteeringMapSetting

Fields

radius
:: double

Does not include the radius of the unit.


separation_factor
:: double

separation_force
:: double

force_unit_fuzzy_goto_behavior
:: boolean

Used to make steering look better for aesthetic purposes.


table SteeringMapSettings

Fields

default

moving

table PathFinderMapSettings

Fields

fwd2bwd_ratio
:: uint

The pathfinder performs a step of the backward search every fwd2bwd_ratio'th step. The minimum allowed value is 2, which means symmetric search. The default value is 5.


goal_pressure_ratio
:: double

When looking at which node to check next, their heuristic value is multiplied by this ratio. The higher it is, the more the search is directed straight at the goal. Defaults to 2.


max_steps_worked_per_tick
:: double

The maximum number of nodes that are expanded per tick. Defaults to 1,000.


max_work_done_per_tick
:: uint

The maximum amount of work each pathfinding job is allowed to do per tick. Defaults to 8,000.


use_path_cache
:: boolean

Whether to cache paths at all. Defaults to true.


short_cache_size
:: uint

Number of elements in the short cache. Defaults to 5.


long_cache_size
:: uint

Number of elements in the long cache. Defaults to 25.


short_cache_min_cacheable_distance
:: double

The minimal distance to the goal in tiles required to be searched in the short path cache. Defaults to 10.


short_cache_min_algo_steps_to_cache
:: uint

The minimal number of nodes required to be searched in the short path cache. Defaults to 50.


long_cache_min_cacheable_distance
:: double

The minimal distance to the goal in tiles required to be searched in the long path cache. Defaults to 30.


cache_max_connect_to_cache_steps_multiplier
:: uint

When looking for a connection to a cached path, search at most for this number of steps times the original estimate. Defaults to 100.


cache_accept_path_start_distance_ratio
:: double

When looking for a path from cache, make sure it doesn't start too far from the requested start in relative terms. Defaults to 0.2.


cache_accept_path_end_distance_ratio
:: double

When looking for a path from cache, make sure it doesn't end too far from the requested end in relative terms. This is typically more lenient than the start ratio since the end target could be moving. Defaults to 0.15.


negative_cache_accept_path_start_distance_ratio
:: double

Same principle as cache_accept_path_start_distance_ratio, but used for negative cache queries. Defaults to 0.3.


negative_cache_accept_path_end_distance_ratio
:: double

Same principle as cache_accept_path_end_distance_ratio, but used for negative cache queries. Defaults to 0.3.


cache_path_start_distance_rating_multiplier
:: double

When assigning a rating to the best path, this multiplier times start distances is considered. Defaults to 10.


cache_path_end_distance_rating_multiplier
:: double

When assigning a rating to the best path, this multiplier times end distances is considered. This value is typically higher than the start multiplier as this results in better end path quality. Defaults to 20.


stale_enemy_with_same_destination_collision_penalty
:: double

A penalty that is applied for another unit that is on the way to the goal. This is mainly relevant for situations where a group of units has arrived at the target they are supposed to attack, making units further back circle around to reach the target. Defaults to 30.


ignore_moving_enemy_collision_distance
:: double

The distance in tiles after which other moving units are not considered for pathfinding. Defaults to 5.


enemy_with_different_destination_collision_penalty
:: double

A penalty that is applied for another unit that is too close and either not moving or has a different goal. Defaults to 30.


general_entity_collision_penalty
:: double

The general collision penalty with other units. Defaults to 10.


general_entity_subsequent_collision_penalty
:: double

The collision penalty for positions that require the destruction of an entity to get to. Defaults to 3.


extended_collision_penalty
:: double

The collision penalty for collisions in the extended bounding box but outside the entity's actual bounding box. Defaults to 3.


max_clients_to_accept_any_new_request
:: uint

The amount of path finder requests accepted per tick regardless of the requested path's length. Defaults to 10.


max_clients_to_accept_short_new_request
:: uint

When the max_clients_to_accept_any_new_request amount is exhausted, only path finder requests with a short estimate will be accepted until this amount (per tick) is reached. Defaults to 100.


direct_distance_to_consider_short_request
:: uint

The maximum direct distance in tiles before a request is no longer considered short. Defaults to 100.


short_request_max_steps
:: uint

The maximum amount of nodes a short request will traverse before being rescheduled as a long request. Defaults to 1000.


short_request_ratio
:: double

The amount of steps that are allocated to short requests each tick, as a percentage of all available steps. Defaults to 0.5, or 50%.


min_steps_to_check_path_find_termination
:: uint

The minimum amount of steps that are guaranteed to be performed for every request. Defaults to 2000.


start_to_goal_cost_multiplier_to_terminate_path_find
:: double

If the actual amount of steps is higher than the initial estimate by this factor, pathfinding is terminated. Defaults to 2000.0.


overload_levels
:: array[uint]

The thresholds of waiting clients after each of which the per-tick work limit will be increased by the corresponding value in overload_multipliers. This is to avoid clients having to wait too long. Must have the same number of elements as overload_multipliers. Defaults to {0, 100, 500}.


overload_multipliers
:: array[double]

The multipliers to the amount of per-tick work applied after the corresponding thresholds in overload_levels have been reached. Must have the same number of elements as overload_multipliers. Defaults to {2, 3, 4}.


negative_path_cache_delay_interval
:: uint

The delay in ticks between decrementing the score of all paths in the negative cache by one. Defaults to 20.


table MapSettings

Various game-related settings. Updating any of the attributes will immediately take effect in the game engine.

Fields

pollution

enemy_evolution

enemy_expansion

unit_group

steering

path_finder

max_failed_behavior_count
:: uint

If a behavior fails this many times, the enemy (or enemy group) is destroyed. This solves biters getting stuck within their own base.

Example

Increase the number of short paths the pathfinder can cache.

game.map_settings.path_finder.short_cache_size = 15

table DifficultySettings

Technology and recipe difficulty settings. Updating any of the attributes will immediately take effect in the game engine.

Fields



technology_price_multiplier
:: double

A value in range [0.001, 1000].


research_queue_setting
:: string

Either "after-victory", "always" or "never". Changing this to "always" or "after-victory" does not automatically unlock the research queue. See LuaForce for that.


table MapAndDifficultySettings

All regular MapSettings plus an additional table that contains the DifficultySettings.

Fields

pollution

enemy_evolution

enemy_expansion

unit_group

steering

path_finder

max_failed_behavior_count
:: uint

If a behavior fails this many times, the enemy (or enemy group) is destroyed. This solves biters getting stuck within their own base.


difficulty_settings

table MapExchangeStringData

The data that can be extracted from a map exchange string, as a plain table.

Fields

map_settings

map_gen_settings

table BlueprintItemIcon

Fields

name
:: string

Name of the item prototype whose icon should be used.


index
:: uint

Index of the icon in the blueprint icons slots. Has to be an integer in the range [1, 4].


table BlueprintSignalIcon

Fields

signal

The icon to use. It can be any item icon as well as any virtual signal icon.


index
:: uint

Index of the icon in the blueprint icons slots. Has to be an integer in the range [1, 4].


table BlueprintEntity

The representation of an entity inside of a blueprint. It has at least these fields, but can contain additional ones depending on the kind of entity.

Fields

entity_number
:: uint

The entity's unique identifier in the blueprint.


name
:: string

The prototype name of the entity.


position

The position of the entity.


direction

The direction the entity is facing. Only present for entities that can face in different directions and when the entity is not facing north.


tags
:: Tags?

The entity tags of the entity, if there are any. Only relevant for entity ghosts.


items
:: dictionary[stringuint]?

The items that the entity will request when revived, if there are any. It's a mapping of prototype names to amounts. Only relevant for entity ghosts.


connections

The circuit network connections of the entity, if there are any. Only relevant for entities that support circuit connections.


control_behavior

The control behavior of the entity, if it has one. The format of the control behavior depends on the entity's type. Only relevant for entities that support control behaviors.


schedule
:: array[TrainScheduleRecord]?

The schedule of the entity, if it has one. Only relevant for locomotives.


table Tile

Fields

position

The position of the tile.


name
:: string

The prototype name of the tile.


table Fluid

Fields

name
:: string

Fluid prototype name of the fluid.


amount
:: double

Amount of the fluid.


temperature
:: double?

The temperature. When reading from LuaFluidBox, this field will always be present. It is not necessary to specify it when writing, however. When not specified, the fluid will be set to the fluid's default temperature as specified in the fluid's prototype.


table Ingredient

Fields

type
:: string

"item" or "fluid".


name
:: string

Prototype name of the required item or fluid.


amount
:: double

Amount of the item or fluid.


catalyst_amount
:: uint or double?

How much of this ingredient is a catalyst.

Other attributes may be specified depending on type:

fluid

minimum_temperature
:: double?

The minimum fluid temperature required.


maximum_temperature
:: double?

The maximum fluid temperature allowed.


table Product

Fields

type
:: string

"item" or "fluid".


name
:: string

Prototype name of the result.


amount
:: double?

Amount of the item or fluid to give. If not specified, amount_min, amount_max and probability must all be specified.


amount_min
:: uint or double?

Minimal amount of the item or fluid to give. Has no effect when amount is specified.


amount_max
:: uint or double?

Maximum amount of the item or fluid to give. Has no effect when amount is specified.


probability
:: double?

A value in range [0, 1]. Item or fluid is only given with this probability; otherwise no product is produced.


catalyst_amount
:: uint or double?

How much of this product is a catalyst.

Other attributes may be specified depending on type:

fluid

temperature
:: double?

The fluid temperature of this product.

Examples

Products of the "steel-chest" recipe (an array of Product):

{{type="item", name="steel-chest", amount=1}}

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

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

table Loot

Fields

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.


table TechnologyModifier

The effect that is applied when a technology is researched. It is a table that contains at least the field type.

Fields

type
:: string

Modifier type. Specifies which of the other fields will be available. Possible values are: "inserter-stack-size-bonus", "stack-inserter-capacity-bonus", "laboratory-speed", "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", "max-failed-attempts-per-tick-per-construction-queue", "max-successful-attempts-per-tick-per-construction-queue", "character-health-bonus", "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-upgrade-planner-enabled", "zoom-to-world-selection-tool-enabled", "worker-robot-battery", "laboratory-productivity", "follower-robot-lifetime", "artillery-range", "nothing", "character-additional-mining-categories", "character-logistic-requests".

Other attributes may be specified 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.

ammo-damage

ammo_category
:: string

Prototype name of the ammunition category that is affected


modifier
:: double

Modification value. This will be added to the current ammo damage modifier upon researching.

give-item

item
:: string

Item prototype name to give.


count
:: uint?

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 damage modifier upon researching.

unlock-recipe

recipe
:: string

Recipe prototype name to unlock.

nothing

effect_description

Description of this nothing modifier.

Other types

modifier
:: double

Modification value. This value will be added to the variable it modifies.


table Offer

A single offer on a market entity.

Fields

price
:: array[Ingredient]

List of prices.


offer

The action that will take place when a player accepts the offer. Usually a "give-item" modifier.


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

Fields

probability_expression

richness_expression

coverage
:: double

sharpness
:: double

max_probability
:: double

placement_density
:: uint

richness_base
:: double

richness_multiplier
:: double

richness_multiplier_distance_bonus
:: double

starting_area_size
:: uint

order
:: string

default_enabled
:: boolean

peaks

control
:: string?

Control prototype name.


tile_restriction

force
:: string

random_probability_penalty
:: double

table NoiseExpression

A fragment of a functional program used to generate coherent noise, probably for purposes related to terrain generation. These can only be meaningfully written/modified during the data load phase. More detailed information is found on the wiki.

Fields

type
:: string

Names the type of the expression and determines what other fields are required.


table AutoplaceSpecificationPeak

Fields

influence
:: double

max_influence
:: double

min_influence
:: double

richness_influence
:: double

noisePersistence
:: double

noise_layer
:: string?

Prototype name of the noise layer.


noise_octaves_difference
:: double

water_optimal
:: double

water_range
:: double

water_max_range
:: double

water_top_property_limit
:: double

elevation_optimal
:: double

elevation_range
:: double

elevation_max_range
:: double

elevation_top_property_limit
:: double

temperature_optimal
:: double

temperature_range
:: double

temperature_max_range
:: double

temperature_top_property_limit
:: double

starting_area_weight_optimal
:: double

starting_area_weight_range
:: double

starting_area_weight_max_range
:: double

starting_area_weight_top_property_limit
:: double

tier_from_start_optimal
:: double

tier_from_start_range
:: double

tier_from_start_max_range
:: double

tier_from_start_top_property_limit
:: double

distance_optimal
:: double

distance_range
:: double

distance_max_range
:: double

distance_top_property_limit
:: double

aux_optimal
:: double

aux_range
:: double

aux_max_range
:: double

aux_top_property_limit
:: double

table AutoplaceSpecificationRestriction

Fields

first
:: string?

Tile prototype name


second
:: string?

Second prototype name


table Resistance

Fields

decrease
:: float

Absolute damage decrease


percent
:: float

Percentual damage decrease


concept MapGenSize

A floating point number specifying an amount.

For backwards compatibility, MapGenSizes can also be specified as one of the following strings, which will be converted to a number (when queried, a number will always be returned):

  • "none" - equivalent to 0
  • "very-low", "very-small", "very-poor" - equivalent to 1/2
  • "low", "small", "poor" - equivalent to 1/sqrt(2)
  • "normal", "medium", "regular" - equivalent to 1
  • "high", "big", "good" - equivalent to sqrt(2)
  • "very-high", "very-big", "very-good" - equivalent to 2

Note

The map generation algorithm officially supports the range of values the in-game map generation screen shows (specifically 0 and values from 1/6 to 6). Values outside this range are not guaranteed to work as expected.


table AutoplaceSetting

Fields

frequency

size

richness

table AutoplaceSettings

Fields

treat_missing_as_default
:: boolean

Whether missing autoplace names for this type should be default enabled.


settings
:: dictionary[stringAutoplaceSetting]

table AutoplaceControl

Fields

frequency

For things that are placed as spots such as ores and enemy bases, frequency is generally proportional to number of spots placed per unit area. For continuous features such as forests, frequency is how compressed the probability function is over distance, i.e. the inverse of 'scale' (similar to terrain_segmentation). When the LuaAutoplaceControlPrototype is of the category "terrain", then scale is shown in the map generator GUI instead of frequency.


size

For things that are placed as spots, size is proportional to the area of each spot. For continuous features, size affects how much of the map is covered with the thing, and is called 'coverage' in the GUI.


richness

Has different effects for different things, but generally affects the 'health' or density of a thing that is placed without affecting where it is placed. For trees, richness affects tree health. For ores, richness multiplies the amount of ore at any given tile in a patch. Metadata about autoplace controls (such as whether or not 'richness' does anything for them) can be found in the LuaAutoplaceControlPrototype by looking up game.autoplace_control_prototypes[(control prototype name)], e.g. game.autoplace_control_prototypes["enemy-base"].richness is false, because enemy base autoplacement doesn't use richness.


table CliffPlacementSettings

Fields

name
:: string

Name of the cliff prototype.


cliff_elevation_0
:: float

Elevation at which the first row of cliffs is placed. The default is 10, and this cannot be set from the map generation GUI.


cliff_elevation_interval
:: float

Elevation difference between successive rows of cliffs. This is inversely proportional to 'frequency' in the map generation GUI. Specifically, when set from the GUI the value is 40 / frequency.


richness

Corresponds to 'continuity' in the GUI. This value is not used directly, but is used by the 'cliffiness' noise expression, which in combination with elevation and the two cliff elevation properties drives cliff placement (cliffs are placed when elevation crosses the elevation contours defined by cliff_elevation_0 and cliff_elevation_interval when 'cliffiness' is greater than 0.5). The default 'cliffiness' expression interprets this value such that larger values result in longer unbroken walls of cliffs, and smaller values (between 0 and 1) result in larger gaps in cliff walls.


table MapGenSettings

The 'map type' dropdown in the map generation GUI is actually a selector for elevation generator. The base game sets property_expression_names.elevation to "0_16-elevation" to reproduce terrain from 0.16 or to "0_17-island" for the island preset. If generators are available for other properties, the 'map type' dropdown in the GUI will be renamed to 'elevation' and shown along with selectors for the other selectable properties.

Fields

terrain_segmentation

The inverse of 'water scale' in the map generator GUI. Lower terrain_segmentation increases the scale of elevation features (lakes, continents, etc). This behavior can be overridden with alternate elevation generators (see property_expression_names, below).


water

The equivalent to 'water coverage' in the map generator GUI. Specifically, when this value is non-zero, water_level = 10 * log2 (the value of this field), and the elevation generator subtracts water level from elevation before adding starting lakes. If water is set to 'none', elevation is clamped to a small positive value before adding starting lakes. This behavior can be overridden with alternate elevation generators (see property_expression_names, below).


autoplace_controls
:: dictionary[stringAutoplaceControl]

Indexed by autoplace control prototype name.


default_enable_all_autoplace_controls
:: boolean

Whether undefined autoplace_controls should fall back to the default controls or not. Defaults to true.


autoplace_settings
:: dictionary[stringAutoplaceSettings]

Each setting in this dictionary maps the string type to the settings for that type. Valid types are "entity", "tile" and "decorative".


cliff_settings

Map generation settings for entities of the type "cliff".


seed
:: uint

The random seed used to generated this map.


width
:: uint

Width in tiles. If 0, the map has 'infinite' width, with the actual limitation being one million tiles in each direction from the center.


height
:: uint

Height in tiles. If 0, the map has 'infinite' height, with the actual limitation being one million tiles in each direction from the center.


starting_area

Size of the starting area.


starting_points
:: array[MapPosition]

Positions of the starting areas.


peaceful_mode
:: boolean

Whether peaceful mode is enabled for this map.


property_expression_names
:: dictionary[stringstring]

Overrides for tile property value generators. Values either name a NamedNoiseExpression or can be literal numbers, stored as strings (e.g. "5"). All other controls can be overridden by a property expression names. Notable properties:
- moisture - a value between 0 and 1 that determines whether a tile becomes sandy (low moisture) or grassy (high moisture).
- aux - a value between 0 and 1 that determines whether low-moisture tiles become sand or red desert.
- temperature - provides a value (vaguely representing degrees Celsius, varying between -20 and 50) that is used (together with moisture and aux) as part of tree and decorative placement.
- elevation - tiles values less than zero become water. Cliffs are placed along certain contours according to CliffPlacementSettings.
- cliffiness - determines whether (when >0.5) or not (when <0.5) a cliff will be placed at an otherwise suitable (according to CliffPlacementSettings) location.
- enemy-base-intensity - a number that is referenced by both enemy-base-frequency and enemy-base-radius. i.e. if this is overridden, enemy base frequency and size will both be affected and do something reasonable. By default, this expression returns a value proportional to distance from any starting point, clamped at about 7.
- enemy-base-frequency - a number representing average number of enemy bases per tile for a region, by default in terms of enemy-base-intensity.
- enemy-base-radius - a number representing the radius of an enemy base, if one were to be placed on the given tile, by default proportional to a constant plus enemy-base-intensity. Climate controls ('Moisture' and 'Terrain type' at the bottom of the Terrain tab in the map generator GUI) don't have their own dedicated structures in MapGenSettings. Instead, their values are stored as property expression overrides with long names:
- control-setting:moisture:frequency:multiplier - frequency (inverse of scale) multiplier for moisture noise. Default is 1.
- control-setting:moisture:bias - global bias for moisture (which normally varies between 0 and 1). Default is 0.
- control-setting:aux:frequency:multiplier - frequency (inverse of scale) multiplier for aux (called 'terrain type' in the GUI) noise. Default is 1.
- control-setting:aux:bias - global bias for aux/terrain type (which normally varies between 0 and 1). Default is 0. All other MapGenSettings feed into named noise expressions, and therefore placement can be overridden by including the name of a property in this dictionary. The probability and richness functions for placing specific tiles, entities, and decoratives can be overridden by including an entry named {tile|entity|decorative}:(prototype name):{probability|richness}.

Examples

Assuming a NamedNoiseExpression with the name "my-alternate-grass1-probability" is defined

local surface = game.player.surface
local mgs = surface.map_gen_settings
mgs.property_expression_names["tile:grass1:probability"] = "my-alternate-grass1-probability"
surface.map_gen_settings = mgs

would override the probability of grass1 being placed at any given point on the current surface.

To make there be no deep water on (newly generated chunks) a surface:

local surface = game.player.surface
local mgs = surface.map_gen_settings
mgs.property_expression_names["tile:deepwater:probability"] = -1000
surface.map_gen_settings = mgs

This does not require a NamedNoiseExpression to be defined, since literal numbers (and strings naming literal numbers, e.g. "123") are understood to stand for constant value expressions.


table SignalID

Fields

type
:: string

"item", "fluid", or "virtual".


name
:: string?

Name of the item, fluid or virtual signal.


table Signal

An actual signal transmitted by the network.

Fields

signal

ID of the signal.


count
:: int

Value of the signal.


table UpgradeFilter

Fields

type
:: string

"item", or "entity".


name
:: string?

Name of the item, or entity.


table InfinityInventoryFilter

A single filter used by an infinity-filters instance.

Fields

name
:: string

Name of the item.


count
:: uint?

The count of the filter.


mode
:: string?

"at-least", "at-most", or "exactly". Defaults to "at-least".


index
:: uint

The index of this filter in the filters list.


table InfinityPipeFilter

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

Fields

name
:: string

Name of the fluid.


percentage
:: double?

The fill percentage the pipe (e.g. 0.5 for 50%). Can't be negative.


temperature
:: double?

The temperature of the fluid. Defaults to the default/minimum temperature of the fluid.


mode
:: string?

"at-least", "at-most", "exactly", "add", or "remove". Defaults to "at-least".


table FluidBoxFilter

Fields

name
:: string

Fluid prototype name of the filtered fluid.


minimum_temperature
:: double

The minimum temperature allowed into the fluidbox.


maximum_temperature
:: double

The maximum temperature allowed into the fluidbox.


table FluidBoxFilterSpec

Fields

name
:: string

Fluid prototype name of the filtered fluid.


minimum_temperature
:: double?

The minimum temperature allowed into the fluidbox.


maximum_temperature
:: double?

The maximum temperature allowed into the fluidbox.


force
:: boolean?

Force the filter to be set, regardless of current fluid content.


table HeatSetting

The settings used by a heat-interface type entity.

Fields

temperature
:: double?

The target temperature. Defaults to the minimum temperature of the heat buffer.


mode
:: string?

"at-least", "at-most", "exactly", "add", or "remove". Defaults to "at-least".


table HeatConnection

Fields

position
:: Vector

direction

table FluidBoxConnection

A definition of a fluidbox connection point.

Fields

type
:: string

The connection type: "input", "output", or "input-output".


positions
:: array[Vector]

The 4 cardinal direction connection points for this pipe. This vector is a table with x and y keys instead of an array.


max_underground_distance
:: uint?

The maximum tile distance this underground connection can connect at if this is an underground pipe.


table ArithmeticCombinatorParameters

Fields

first_signal
:: SignalID?

First signal to use in an operation. If not specified, the second argument will be the value of first_constant.


second_signal
:: SignalID?

Second signal to use in an operation. If not specified, the second argument will be the value of second_constant.


first_constant
:: int?

Constant to use as the first argument of the operation. Has no effect when first_signal is set. Defaults to 0.


second_constant
:: int?

Constant to use as the second argument of the operation. Has no effect when second_signal is set. Defaults to 0.


operation
:: string?

Must be one of "*", "/", "+", "-", "%", "^", "<<", ">>", "AND", "OR", "XOR". When not specified, defaults to "*".


output_signal
:: SignalID?

Specifies the signal to output.


table ConstantCombinatorParameters

Fields

signal

Signal to emit.


count
:: int

Value of the signal to emit.


index
:: uint

Index of the constant combinator's slot to set this signal to.


enum ComparatorString

Options

"="

"equal to"


">"

"greater than"


"<"

"lesser than"


"≥"

"greater than or equal to"


">="

"greater than or equal to"


"≤"

"lesser than or equal to"


"<="

"lesser than or equal to"


"≠"

"not equal to"


"!="

"not equal to"

Note

While the API accepts both versions for "less/greater than or equal to" and "not equal", it'll always return "≥", "≤" or "≠" respectively when reading them back.


table DeciderCombinatorParameters

Fields

first_signal
:: SignalID?

Defaults to blank.


second_signal
:: SignalID?

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?

Constant to use as the second argument of operation. Defaults to 0.


comparator

Specifies how the inputs should be compared. If not specified, defaults to "<".


output_signal
:: SignalID?

Defaults to blank.


copy_count_from_input
:: boolean?

Defaults to true. When false, will output a value of 1 for the given output_signal.


table InserterCircuitConditions

Fields

circuit

logistics

table CircuitCondition

Fields

comparator

Specifies how the inputs should be compared. If not specified, defaults to "<".


first_signal
:: SignalID?

Defaults to blank


second_signal
:: SignalID?

What to compare first_signal to. If not specified, first_signal will be compared to constant.


constant
:: int?

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.


table CircuitConditionDefinition

Fields

condition

fulfilled
:: boolean?

Whether the condition is currently fulfilled


table CircuitConnectionDefinition

Fields


target_entity

source_circuit_id

target_circuit_id

table WireConnectionDefinition

Fields


target_entity

The entity to (dis)connect the source entity with.


source_circuit_id

Mandatory if the source entity has more than one circuit connection using circuit wire.


target_circuit_id

Mandatory if the target entity has more than one circuit connection using circuit wire.


source_wire_id

Mandatory if the source entity has more than one wire connection using copper wire.


target_wire_id

Mandatory if the target entity has more than one wire connection using copper wire.


table InventoryFilter

Fields

index
:: uint

Position of the corresponding filter slot.


name
:: string

Item prototype name of the item to filter.


table PlaceAsTileResult

Fields

result

The tile prototype.


condition_size
:: uint

condition

table Command

Commands can be given to enemies and unit groups.

Fields

type

Type of command. The remaining fields depend on the value of this field.

Other attributes may be specified depending on type:

defines.command.attack

target

distraction

Defaults to defines.distraction.by_enemy.

defines.command.go_to_location

destination

The position to path to. Either this or destination_entity need to be specified. If both are, destination_entity is used.


destination_entity
:: LuaEntity?

The entity to path to. Either this or destination need to be specified. If both are, destination_entity is used.


distraction

Defaults to defines.distraction.by_enemy.


pathfind_flags

Flags that affect pathfinder behavior.


radius
:: double?

How close the pathfinder needs to get to its destination (in tiles). Defaults to 3.

defines.command.compound

structure_type

How the commands should be chained together.


commands
:: array[Command]

The sub-commands.

defines.command.group

group

The group whose command to follow.


distraction

Defaults to defines.distraction.by_enemy.


use_group_distraction
:: boolean?

Whether the unit will use the group distraction or the commands distraction. Defaults to true.

defines.command.attack_area

destination

Center of the attack area.


radius
:: double

Radius of the attack area.


distraction

Defaults to defines.distraction.by_enemy.

defines.command.wander

distraction

Defaults to defines.distraction.by_enemy.


radius
:: double?

Defaults to 10. Does not apply when wander_in_group is true.


wander_in_group
:: boolean?

When commanding a group, defines how the group will wander. When 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.


ticks_to_wait
:: uint?

Ticks to wander before successfully completing the command. Default is max uint, which means wander forever.

defines.command.stop

distraction

Defaults to defines.distraction.by_enemy.


ticks_to_wait
:: uint?

Ticks to wander before successfully completing the command. Default is max uint, which means stop forever.

defines.command.flee

from

The entity to flee from


distraction

Defaults to defines.distraction.by_enemy.

defines.command.build_base

destination

Where to build the base.


distraction

Defaults to defines.distraction.by_enemy.


ignore_planner
:: boolean?

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.


table PathfinderFlags

Fields

allow_destroy_friendly_entities
:: boolean?

Allows pathing through friendly entities. Defaults to false.


allow_paths_through_own_entities
:: boolean?

Allows the pathfinder to path through entities of the same force. Defaults to false.


cache
:: boolean?

Enables path caching. This can be more efficient, but might fail to respond to changes in the environment. Defaults to true.


prefer_straight_paths
:: boolean?

Makes the pathfinder try to path in straight lines. Defaults to false.


low_priority
:: boolean?

Sets lower priority on the path request, meaning it might take longer to find a path at the expense of speeding up others. Defaults to false.


no_break
:: boolean?

Makes the pathfinder not break in the middle of processing this pathfind, no matter how much work is needed. Defaults to false.


table UnitSpawnDefinition

Fields

unit
:: string

Prototype name of the unit that would be spawned.


spawn_points

The points at which to spawn the unit.


table SpawnPointDefinition

Fields

evolution_factor
:: double

Evolution factor for which this weight applies.


weight
:: double

Probability of spawning this unit at this evolution factor.


table ItemStackDefinition

Fields

name
:: string

Prototype name of the item the stack holds.


count
:: uint?

Number of items the stack holds. If not specified, defaults to 1.


health
:: float?

Health of the items in the stack. Defaults to 1.0.


durability
:: double?

Durability of the tool items in the stack.


ammo
:: double?

Amount of ammo in the ammo items in the stack.


tags
:: array[string]?

Tags of the items with tags in the stack.


union SimpleItemStack

Options

:: string

The name of the item, which represents a full stack of that item.


The detailed definition of an item stack.

Examples

Both of these lines specify an item stack of one iron plate:

{name="iron-plate"}
{name="iron-plate", count=1}

This is a stack of 47 copper plates:

{name="copper-plate", count=47}

These are both full stacks of iron plates (for iron-plate, a full stack is 100 plates):

"iron-plate"
{name="iron-plate", count=100}

union FluidIdentification

Options

:: string

The fluid name.


The fluid prototype.


:: Fluid

The fluid.


union ForceIdentification

Options

:: string

The force name.


A reference to LuaForce may be passed directly.


union TechnologyIdentification

Options

:: string

The technology name.


A reference to LuaTechnology may be passed directly.


A reference to LuaTechnologyPrototype may be passed directly.


union SurfaceIdentification

Options

:: uint

It will be the index of the surface. nauvis has index 1, the first surface-created surface will have index 2 and so on.


:: string

It will be the surface name. E.g. "nauvis".


A reference to LuaSurface may be passed directly.


union PlayerIdentification

Options

:: uint

The player index.


:: string

The player name.


A reference to LuaPlayer may be passed directly.


union ItemStackIdentification


union EntityPrototypeIdentification

Options

The entity.


The entity prototype.


:: string

The prototype name.


union ItemPrototypeIdentification

Options

The item.


The item prototype.


:: string

The prototype name.


table WaitCondition

Fields

type
:: string

One of "time", "inactivity", "full", "empty", "item_count", "circuit", "robots_inactive", "fluid_count", "passenger_present", "passenger_not_present".


compare_type
:: string

Either "and", or "or". Tells how this condition is to be compared with the preceding conditions in the corresponding wait_conditions array.


ticks
:: uint?

Number of ticks to wait or of inactivity. Only present when type is "time" or "inactivity".


condition

Only present when type is "item_count", "circuit" or "fluid_count".


table TrainScheduleRecord

Fields

station
:: string?

Name of the station.


rail
:: LuaEntity?

Rail to path to. Ignored if station is present.


rail_direction

When a train is allowed to reach rail target from any direction it will be nil. If rail has to be reached from specific direction, this value allows to choose the direction. This value corresponds to LuaEntity::connected_rail_direction of a TrainStop.


wait_conditions
:: array[WaitCondition]?

temporary
:: boolean?

Only present when the station is temporary, the value is then always true.


table TrainSchedule

Fields

current
:: uint

Index of the currently active record


records

table GuiArrowSpecification

Used for specifying where a GUI arrow should point to.

Fields

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.

Other attributes may be specified depending on type:

entity

entity

position

position

crafting_queue

crafting_queueindex
:: uint

Index in the crafting queue to point to.

item_stack

inventory_index

Which inventory the stack is in.


item_stack_index
:: uint

Which stack to point to.


source
:: string

Must be either "player", "target", "player-quickbar" or "player-equipment-bar".


table AmmoType

Fields

action
:: array[TriggerItem]?

target_type
:: string

One of "entity" (fires at an entity), "position" (fires directly at a position), or "direction" (fires in a direction).


clamp_position
:: boolean?

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


category
:: string

Ammo category of this ammo.


energy_consumption
:: double?

Energy consumption of a single shot, if applicable. Defaults to 0.


table BeamTarget

Fields

entity
:: LuaEntity?

The target entity.


position

The target position.


table RidingState

Fields

acceleration


concept SpritePath

It is specified by string. It can be either the name of a sprite prototype defined in the data stage or a path in form "type/name".

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


concept SoundPath

A sound defined by a string. It can be either the name of a sound prototype defined in the data stage or a path in the form "type/name". The latter option can be sorted into three categories.

The utility and ambient types each contain general use sound prototypes defined by the game itself.
- "utility" - Uses the UtilitySounds prototype. Example: "utility/wire_connect_pole"
- "ambient" - Uses AmbientSound prototypes. Example: "ambient/resource-deficiency"

The following types can be combined with any tile name as long as its prototype defines the
corresponding sound.
- "tile-walking" - Uses Tile::walking_sound. Example: "tile-walking/concrete"
- "tile-mined" - Uses Tile::mined_sound
- "tile-build-small" - Uses Tile::build_sound. Example: "tile-build-small/concrete"
- "tile-build-medium" - Uses Tile::build_sound
- "tile-build-large" - Uses Tile::build_sound

The following types can be combined with any entity name as long as its prototype defines the
corresponding sound.
- "entity-build" - Uses Entity::build_sound. Example: "entity-build/wooden-chest"
- "entity-mined" - Uses Entity::mined_sound
- "entity-mining" - Uses Entity::mining_sound
- "entity-vehicle_impact" - Uses Entity::vehicle_impact_sound
- "entity-rotated" - Uses Entity::rotated_sound
- "entity-open" - Uses Entity::open_sound
- "entity-close" - Uses Entity::close_sound


table ModuleEffectValue

Fields

bonus
:: float

The percentual increase of the attribute. A value of 0.6 means a 60% increase.


table ModuleEffects

Fields

consumption

speed

productivity

pollution

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

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

Options

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

"hidden"

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

"not-in-kill-statistics"

flag ItemPrototypeFlags

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

Options

"draw-logistic-overlay"

"hidden"

"always-show"

"hide-from-bonus-gui"

"hide-from-fuel-tooltip"

"not-stackable"

"can-extend-inventory"

"primary-place-result"

"mod-openable"

"only-in-cursor"

"spawnable"

concept CollisionMaskLayer

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"
- "rail-layer"
- "transport-belt-layer"
- "not-setup"

Additionally the values "layer-13" through "layer-55". These layers are currently unused by the game but may change. If a mod is going to use one of the unused layers it's recommended to start at the higher layers because the base game will take from the lower ones.


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


concept CollisionMaskWithFlags

A CollisionMask which also includes any flags this mask has.

Flags such as:
- "not-colliding-with-itself": Any two entities that both have this option enabled on their prototype and have an identical collision mask layers list will not collide. Other collision mask options are not included in the identical layer list check. This does mean that two different prototypes with the same collision mask layers and this option enabled will not collide.
- "consider-tile-transitions": Uses the prototypes position rather than its collision box when doing collision checks with tile prototypes. Allows the prototype to overlap colliding tiles up until its center point. This is only respected for character movement and cars driven by players.
- "colliding-with-tiles-only": Any prototype with this collision option will only be checked for collision with other prototype's collision masks if they are a tile.


concept TriggerTargetMask

This is a set of trigger target masks given as a dictionary[stringboolean].


table TriggerEffectItem

Fields

type
:: string

One of"damage", "create-entity", "create-explosion", "create-fire", "create-smoke", "create-trivial-smoke", "create-particle", "create-sticker", "nested-result", "play-sound", "push-back", "destroy-cliffs", "show-explosion-on-chart", "insert-item", "script".


repeat_count
:: uint

affects_target
:: boolean

show_in_tooltip
:: boolean

table TriggerDelivery

Fields

type
:: string

One of "instant", "projectile", "flame-thrower", "beam", "stream", "artillery".


source_effects
:: array[TriggerEffectItem]

target_effects
:: array[TriggerEffectItem]

table TriggerItem

Fields

type
:: string

One of "direct", "area", "line", "cluster".


action_delivery
:: array[TriggerDelivery]?

entity_flags

The trigger will only affect entities that contain any of these flags.


ignore_collision_condition
:: boolean

collision_mask

The trigger will only affect entities that would collide with given collision mask.


trigger_target_mask

force

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


repeat_count
:: uint

table CircularParticleCreationSpecification

Fields

name
:: string

Name of the LuaEntityPrototype


direction
:: float

direction_deviation
:: float

speed
:: float

speed_deviation
:: float

starting_frame_speed
:: float

starting_frame_speed_deviation
:: float

height
:: float

height_deviation
:: float

vertical_speed
:: float

vertical_speed_deviation
:: float

center
:: Vector

This vector is a table with x and y keys instead of an array.


creation_distance
:: double

creation_distance_orientation
:: double

use_source_position
:: boolean

concept CircularProjectileCreationSpecification

An array with the following members:
- A RealOrientation
- A Vector


table AttackParameterFluid

Fields

type
:: string

Name of the LuaFluidPrototype.


damage_modifier
:: double

Multiplier applied to the damage of an attack.


table AttackParameters

Fields

type
:: string

The type of AttackParameter. One of 'projectile', 'stream' or 'beam'.


range
:: float

Maximum range of attack.


min_range
:: float

Minimum range of attack. Used with flamethrower turrets to prevent self-immolation.


range_mode
:: string

Defines how the range is determined. Either 'center-to-center' or 'bounding-box-to-bounding-box'.


fire_penalty
:: float

When searching for the nearest enemy to attack, fire_penalty is added to the enemy's distance if they are on fire.


rotate_penalty
:: float

When searching for an enemy to attack, a higher rotate_penalty will discourage targeting enemies that would take longer to turn to face.


health_penalty
:: float

When searching for an enemy to attack, a higher health_penalty will discourage targeting enemies with high health. A negative penalty will do the opposite.


min_attack_distance
:: float

If less than range, the entity will choose a random distance between range and min_attack_distance and attack from that distance. Used for spitters.


turn_range
:: float

The arc that the entity can attack in as a fraction of a circle. A value of 1 means the full 360 degrees.


damage_modifier
:: float

Multiplier applied to the damage of an attack.


ammo_consumption_modifier
:: float

Multiplier applied to the ammo consumption of an attack.


cooldown
:: float

Minimum amount of ticks between shots. If this is less than 1, multiple shots can be performed per tick.


warmup
:: uint

Number of ticks it takes for the weapon to actually shoot after it has been ordered to do so.


movement_slow_down_factor
:: double

movement_slow_down_cooldown
:: float

ammo_type
:: AmmoType?

ammo_categories
:: array[string]?

List of the names of compatible LuaAmmoCategoryPrototypes.

Other attributes may be specified depending on type:

projectile

projectile_center
:: Vector

projectile_creation_distance
:: float

projectile_orientation_offset
:: float


projectile_creation_parameters

stream

gun_barrel_length
:: float

gun_center_shift
:: dictionary[stringVector]

fluid_consumption
:: float

fluids

projectile_creation_parameters

table CapsuleAction

Fields

type
:: string

One of "throw", "equipment-remote", "use-on-self".


attack_parameters

Only present when type is "throw" or "use-on-self".


equipment
:: string?

Only present when type is "equipment-remote". It is the equipment prototype name.


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

Options

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

table LogisticFilter

Fields

index
:: uint

The index this filter applies to.


name
:: string

The item name for this filter.


count
:: uint

The count for this filter.


table ModSetting

Fields

value
:: uint or double or boolean or string

The value of the mod setting. The type depends on the setting.

Note

Runtime settings can be changed through console commands and by the mod that owns the settings by writing a new table to the ModSetting.


concept AnyBasic

Any basic type (string, number, boolean) or table.


concept Any

Any basic type (string, number, boolean), table, or LuaObject.


table ProgrammableSpeakerParameters

Fields

playback_volume
:: double

playback_globally
:: boolean

allow_polyphony
:: boolean

table ProgrammableSpeakerAlertParameters

Fields

show_alert
:: boolean

show_on_map
:: boolean

icon_signal_id

alert_message
:: string

table ProgrammableSpeakerCircuitParameters

Fields

signal_value_is_pitch
:: boolean

instrument_id
:: uint

note_id
:: uint

table ProgrammableSpeakerInstrument

Fields

name
:: string

notes
:: array[string]

enum Alignment

A string that specifies where a gui element should be.

Options

"top-left"

"middle-left"

"left"

The same as "middle-left"


"bottom-left"

"top-center"

"middle-center"

"center"

The same as "middle-center"


"bottom-center"

"top-right"

"right"

The same as "middle-right"


"bottom-right"

table EventData

Information about the event that has been raised. The table can also contain other fields depending on the type of event. See the list of Factorio events for more information on these.

Fields

name

The identifier of the event this handler was registered to.


tick
:: uint

The tick during which the event happened.


mod_name
:: string?

The name of the mod that raised the event if it was raised using LuaBootstrap::raise_event.


table NthTickEventData

Fields

tick
:: uint

The tick during which the event happened.


nth_tick
:: uint

The nth tick this handler was registered to.


table ModChangeData

Fields

old_version
:: string

Old version of the mod. May be nil if the mod wasn't previously present (i.e. it was just added).


new_version
:: string

New version of the mod. May be nil if the mod is no longer present (i.e. it was just removed).


table ConfigurationChangedData

Fields

old_version
:: string?

Old version of the map. Present only when loading map version other than the current version.


new_version
:: string?

New version of the map. Present only when loading map version other than the current version.


mod_changes
:: dictionary[stringModChangeData]

Dictionary of mod changes. It is indexed by mod name.


mod_startup_settings_changed
:: boolean

true when mod startup settings have changed since the last time this save was loaded.


migration_applied
:: boolean

true when mod prototype migrations have been applied since the last time this save was loaded.


table CustomCommandData

Fields

name
:: string

The name of the command.


tick
:: uint

The tick the command was used in.


player_index
:: uint?

The player who issued the command, or nil if it was issued from the server console.


parameter
:: string?

The parameter passed after the command, if there is one.


table SelectedPrototypeData

Fields

base_type
:: string

E.g. "entity".


derived_type
:: string

E.g. "tree".


name
:: string

E.g. "tree-05".


table ScriptRenderTarget

Fields

entity
:: LuaEntity?

entity_offset
:: Vector?

position

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

To write to this, use an array[string] of the mouse buttons that should be possible to use with on button.

When setting flags, the flag "left-and-right" can also be set which 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"


enum CursorBoxRenderType

Options

"entity"

Yellow box.


"not-allowed"

Red box.


"electricity"

Light blue box.


"pair"

Light blue box.


"copy"

Green box.


"train-visualization"

White box.


"logistics"

Light blue box.


"blueprint-snap-rectangle"

Green box.


enum ForceCondition

Options

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


concept RenderLayer

A value between 0 and 255 inclusive represented by one of the following named string or string version of the value (for example "27" and "decals" are both valid). Higher values are rendered on top of lower values.

  • "water-tile": 15
  • "ground-tile": 25
  • "tile-transition": 26
  • "decals": 27
  • "lower-radius-visualization": 29
  • "radius-visualization": 30
  • "transport-belt-integration": 65
  • "resource":66
  • "building-smoke":67
  • "decorative": 92
  • "ground-patch": 93
  • "ground-patch-higher": 94
  • "ground-patch-higher2": 95
  • "remnants": 112
  • "floor": 113
  • "transport-belt": 114
  • "transport-belt-endings": 115
  • "floor-mechanics-under-corpse": 120
  • "corpse": 121
  • "floor-mechanics": 122
  • "item": 123
  • "lower-object": 124
  • "transport-belt-circuit-connector": 126
  • "lower-object-above-shadow": 127
  • "object": 129
  • "higher-object-under": 131
  • "higher-object-above": 132
  • "item-in-inserter-hand": 134
  • "wires": 135
  • "wires-above": 136
  • "entity-info-icon": 138
  • "entity-info-icon-above": 139
  • "explosion": 142
  • "projectile": 143
  • "smoke": 144
  • "air-object": 145
  • "air-entity-info-icon": 147
  • "light-effect": 148
  • "selection-box": 187
  • "higher-selection-box": 188
  • "collision-selection-box": 189
  • "arrow": 190
  • "cursor": 210

enum CliffOrientation

Options

"west-to-east"

"north-to-south"

"east-to-west"

"south-to-north"

"west-to-north"

"north-to-east"

"east-to-south"

"south-to-west"

"west-to-south"

"north-to-west"

"east-to-north"

"south-to-east"

"west-to-none"

"none-to-east"

"east-to-none"

"none-to-west"

"north-to-none"

"none-to-south"

"south-to-none"

"none-to-north"

table ItemStackLocation

Fields

inventory

slot
:: uint

table VehicleAutomaticTargetingParameters

Fields

auto_target_without_gunner
:: boolean

auto_target_with_gunner
:: boolean

enum SoundType

Defines which slider in the game's sound settings affects the volume of this sound. Furthermore, some sound types are mixed differently than others, e.g. zoom level effects are applied.

Options

"game-effect"

"gui-effect"

"ambient"

"environment"

"walking"

"alert"

"wind"

filter ItemPrototypeFilter

Fields

filter
:: string

The condition to filter on. One of "tool", "mergeable", "item-with-inventory", "selection-tool", "item-with-label", "has-rocket-launch-products", "fuel", "place-result", "burnt-result", "place-as-tile", "placed-as-equipment-result", "name", "type", "flag", "subgroup", "fuel-category", "stack-size", "default-request-amount", "wire-count", "fuel-value", "fuel-acceleration-multiplier", "fuel-top-speed-multiplier", "fuel-emissions-multiplier".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

place-result

elem_filters

Filters for the place result.

burnt-result

elem_filters
:: array[ItemPrototypeFilter]?

Filters for the burnt result.

place-as-tile

elem_filters
:: array[TilePrototypeFilter]?

Filters for the placed tile.

placed-as-equipment-result

elem_filters

Filters for the placed equipment.

name

name
:: string or array[string]

The prototype name, or list of acceptable names.

For use within nested filters such as the has-product-item filter of array[RecipePrototypeFilter]. To get a specific prototype by name, see LuaGameScript::item_prototypes.

type

type
:: string

The prototype type

Usage example:

game.get_filtered_item_prototypes({{filter = "type", type = "armor"}})

flag

flag
:: string

One of the values in ItemPrototypeFlags.

subgroup

subgroup
:: string

A LuaGroup (subgroup) name

fuel-category

fuel-category
:: string

A LuaFuelCategoryPrototype name

stack-size

comparison

value
:: uint

The value to compare against.

Usage example:

game.get_filtered_item_prototypes({{filter = "stack-size", comparison = ">", value = 20}, {filter = "stack-size", comparison = "<", value = 100, mode = "and"}})

default-request-amount

comparison

value
:: uint

The value to compare against.

wire-count

comparison

value
:: uint

The value to compare against.

fuel-value

comparison

value
:: double

The value to compare against.

fuel-acceleration-multiplier

comparison

value
:: double

The value to compare against.

fuel-top-speed-multiplier

comparison

value
:: double

The value to compare against.

fuel-emissions-multiplier

comparison

value
:: double

The value to compare against.


filter ModSettingPrototypeFilter

Fields

filter
:: string

The condition to filter on. One of "type", "mod", "setting-type".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

type

type
:: string

The prototype type

mod

mod
:: string

The mod name

setting-type

type
:: string

The setting scope type (startup, runtime-global, or runtime-per-user)


filter TechnologyPrototypeFilter

Fields

filter
:: string

The condition to filter on. One of "enabled", "hidden", "upgrade", "visible-when-disabled", "has-effects", "has-prerequisites", "research-unit-ingredient", "level", "max-level", "time".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

research-unit-ingredient

ingredient
:: string

The research ingredient to check.

level

comparison

value
:: uint

The value to compare against.

max-level

comparison

value
:: uint

The value to compare against.

time

comparison

value
:: uint

The value to compare against.


filter DecorativePrototypeFilter

Fields

filter
:: string

The condition to filter on. One of "decal", "autoplace", "collision-mask".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

collision-mask


mask_mode
:: string

How to filter: "collides" or "layers-equals"


filter AchievementPrototypeFilter

Fields

filter
:: string

The condition to filter on. One of "allowed-without-fight", "type".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

type

type
:: string

The prototype type


filter FluidPrototypeFilter

Fields

filter
:: string

The condition to filter on. One of "hidden", "name", "subgroup", "default-temperature", "max-temperature", "heat-capacity", "fuel-value", "emissions-multiplier", "gas-temperature".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

name

name
:: string or array[string]

The prototype name, or list of acceptable names.

For use within nested filters such as the has-product-fluid filter of array[RecipePrototypeFilter]. To get a specific prototype by name, see LuaGameScript::fluid_prototypes.

subgroup

subgroup
:: string

A LuaGroup (subgroup) name

default-temperature

comparison

value
:: double

The value to compare against.

max-temperature

comparison

value
:: double

The value to compare against.

heat-capacity

comparison

value
:: double

The value to compare against.

fuel-value

comparison

value
:: double

The value to compare against.

emissions-multiplier

comparison

value
:: double

The value to compare against.

gas-temperature

comparison

value
:: double

The value to compare against.


filter EquipmentPrototypeFilter

Fields

filter
:: string

The condition to filter on. One of "item-to-place", "type".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

type

type
:: string

The prototype type


filter TilePrototypeFilter

Fields

filter
:: string

The condition to filter on. One of "minable", "autoplace", "blueprintable", "item-to-place", "collision-mask", "walking-speed-modifier", "vehicle-friction-modifier", "decorative-removal-probability", "emissions".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

collision-mask


mask_mode
:: string

How to filter: "collides" or "layers-equals"

walking-speed-modifier

comparison

value
:: double

The value to compare against.

vehicle-friction-modifier

comparison

value
:: double

The value to compare against.

decorative-removal-probability

comparison

value
:: float

The value to compare against.

emissions

comparison

value
:: double

The value to compare against.


filter RecipePrototypeFilter

Fields

filter
:: string

The condition to filter on. One of "enabled", "hidden", "hidden-from-flow-stats", "hidden-from-player-crafting", "allow-as-intermediate", "allow-intermediates", "allow-decomposition", "always-show-made-in", "always-show-products", "show-amount-in-title", "has-ingredients", "has-products", "has-ingredient-item", "has-ingredient-fluid", "has-product-item", "has-product-fluid", "subgroup", "category", "energy", "emissions-multiplier", "request-paste-multiplier", "overload-multiplier".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

has-ingredient-item

elem_filters
:: array[ItemPrototypeFilter]?

Matches if at least 1 ingredient is an item that matches these filters.

has-ingredient-fluid

elem_filters

Matches if at least 1 ingredient is a fluid that matches these filters.

Usage example:

-- selects recipes that consume sulfuric acid
{{filter = "has-ingredient-fluid", elem_filters = {{filter = "name", name = "sulfuric-acid"}}}}

has-product-item

elem_filters
:: array[ItemPrototypeFilter]?

Matches if at least 1 product is an item that matches these filters.

Usage example:

-- selects recipes that produce an item
{{filter = "has-product-item"}}
-- selects recipes that produce iron plates
{{filter = "has-product-item", elem_filters = {{filter = "name", name = "iron-plate"}}}}
-- selects recipes that produce items that place furnaces
{{filter = "has-product-item", elem_filters = {{filter = "place-result", elem_filters = {{filter = "type", type = "furnace"}}}}}}

has-product-fluid

elem_filters

Matches if at least 1 product is a fluid that matches these filters.

subgroup

subgroup
:: string

A LuaGroup (subgroup) name

category

category
:: string

A LuaRecipeCategoryPrototype name

energy

comparison

value
:: double

The value to compare against.

emissions-multiplier

comparison

value
:: double

The value to compare against.

request-paste-multiplier

comparison

value
:: uint

The value to compare against.

overload-multiplier

comparison

value
:: uint

The value to compare against.


filter EntityPrototypeFilter

Fields

filter
:: string

The condition to filter on. One of "flying-robot", "robot-with-logistics-interface", "rail", "ghost", "explosion", "vehicle", "crafting-machine", "rolling-stock", "turret", "transport-belt-connectable", "wall-connectable", "buildable", "placable-in-editor", "clonable", "selectable", "hidden", "entity-with-health", "building", "fast-replaceable", "uses-direction", "minable", "circuit-connectable", "autoplace", "blueprintable", "item-to-place", "name", "type", "collision-mask", "flag", "build-base-evolution-requirement", "selection-priority", "emissions", "crafting-category".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

name

name
:: string or array[string]

The prototype name, or list of acceptable names.

For use within nested filters such as the place-result filter of array[ItemPrototypeFilter]. To get a specific prototype by name, see LuaGameScript::entity_prototypes.

type

type
:: string

The prototype type

Usage example:

game.get_filtered_entity_prototypes({{filter = "type", type = "unit"}})

collision-mask


mask_mode
:: string

How to filter: "collides" or "layers-equals"

Usage example:

game.get_filtered_entity_prototypes({{filter = "collision-mask", mask = "player-layer", mask_mode = "collides"}})

flag

flag
:: string

One of the values in EntityPrototypeFlags.

Usage example:

game.get_filtered_entity_prototypes({{filter = "flag", flag = "placeable-player"}, {filter = "flag", flag = "placeable-enemy", mode = "and"}})

build-base-evolution-requirement

comparison

value
:: double

The value to compare against.

selection-priority

comparison

value
:: uint8

The value to compare against.

emissions

comparison

value
:: double

The value to compare against.

crafting-category

crafting_category
:: string

Matches if the prototype is for a crafting machine with this crafting category.



filter LuaScriptRaisedReviveEventFilter

Fields

filter
:: string

The condition to filter on. One of "ghost", "rail", "rail-signal", "rolling-stock", "robot-with-logistics-interface", "vehicle", "turret", "crafting-machine", "wall-connectable", "transport-belt-connectable", "circuit-network-connectable", "type", "name", "ghost_type", "ghost_name".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

type

type
:: string

The prototype type

name

name
:: string

The prototype name

ghost_type

type
:: string

The ghost prototype type

ghost_name

name
:: string

The ghost prototype name


filter LuaEntityDiedEventFilter

Fields

filter
:: string

The condition to filter on. One of "ghost", "rail", "rail-signal", "rolling-stock", "robot-with-logistics-interface", "vehicle", "turret", "crafting-machine", "wall-connectable", "transport-belt-connectable", "circuit-network-connectable", "type", "name", "ghost_type", "ghost_name".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

type

type
:: string

The prototype type

name

name
:: string

The prototype name

ghost_type

type
:: string

The ghost prototype type

ghost_name

name
:: string

The ghost prototype name


filter LuaEntityMarkedForDeconstructionEventFilter

Fields

filter
:: string

The condition to filter on. One of "ghost", "rail", "rail-signal", "rolling-stock", "robot-with-logistics-interface", "vehicle", "turret", "crafting-machine", "wall-connectable", "transport-belt-connectable", "circuit-network-connectable", "type", "name", "ghost_type", "ghost_name".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

type

type
:: string

The prototype type

name

name
:: string

The prototype name

ghost_type

type
:: string

The ghost prototype type

ghost_name

name
:: string

The ghost prototype name


filter LuaPreGhostDeconstructedEventFilter

Fields

filter
:: string

The condition to filter on. One of "ghost", "rail", "rail-signal", "rolling-stock", "robot-with-logistics-interface", "vehicle", "turret", "crafting-machine", "wall-connectable", "transport-belt-connectable", "circuit-network-connectable", "type", "name", "ghost_type", "ghost_name".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

type

type
:: string

The prototype type

name

name
:: string

The prototype name

ghost_type

type
:: string

The ghost prototype type

ghost_name

name
:: string

The ghost prototype name


filter LuaScriptRaisedDestroyEventFilter

Fields

filter
:: string

The condition to filter on. One of "ghost", "rail", "rail-signal", "rolling-stock", "robot-with-logistics-interface", "vehicle", "turret", "crafting-machine", "wall-connectable", "transport-belt-connectable", "circuit-network-connectable", "type", "name", "ghost_type", "ghost_name".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

type

type
:: string

The prototype type

name

name
:: string

The prototype name

ghost_type

type
:: string

The ghost prototype type

ghost_name

name
:: string

The ghost prototype name


filter LuaUpgradeCancelledEventFilter

Fields

filter
:: string

The condition to filter on. One of "ghost", "rail", "rail-signal", "rolling-stock", "robot-with-logistics-interface", "vehicle", "turret", "crafting-machine", "wall-connectable", "transport-belt-connectable", "circuit-network-connectable", "type", "name", "ghost_type", "ghost_name".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

type

type
:: string

The prototype type

name

name
:: string

The prototype name

ghost_type

type
:: string

The ghost prototype type

ghost_name

name
:: string

The ghost prototype name


filter LuaPlayerRepairedEntityEventFilter

Fields

filter
:: string

The condition to filter on. One of "ghost", "rail", "rail-signal", "rolling-stock", "robot-with-logistics-interface", "vehicle", "turret", "crafting-machine", "wall-connectable", "transport-belt-connectable", "circuit-network-connectable", "type", "name", "ghost_type", "ghost_name".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

type

type
:: string

The prototype type

name

name
:: string

The prototype name

ghost_type

type
:: string

The ghost prototype type

ghost_name

name
:: string

The ghost prototype name


filter LuaEntityMarkedForUpgradeEventFilter

Fields

filter
:: string

The condition to filter on. One of "ghost", "rail", "rail-signal", "rolling-stock", "robot-with-logistics-interface", "vehicle", "turret", "crafting-machine", "wall-connectable", "transport-belt-connectable", "circuit-network-connectable", "type", "name", "ghost_type", "ghost_name".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

type

type
:: string

The prototype type

name

name
:: string

The prototype name

ghost_type

type
:: string

The ghost prototype type

ghost_name

name
:: string

The ghost prototype name


filter LuaPostEntityDiedEventFilter

Fields

filter
:: string

The condition to filter on. Can only be "type".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

type

type
:: string

The prototype type


filter LuaPreRobotMinedEntityEventFilter

Fields

filter
:: string

The condition to filter on. One of "ghost", "rail", "rail-signal", "rolling-stock", "robot-with-logistics-interface", "vehicle", "turret", "crafting-machine", "wall-connectable", "transport-belt-connectable", "circuit-network-connectable", "type", "name", "ghost_type", "ghost_name".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

type

type
:: string

The prototype type

name

name
:: string

The prototype name

ghost_type

type
:: string

The ghost prototype type

ghost_name

name
:: string

The ghost prototype name


filter LuaEntityClonedEventFilter

Fields

filter
:: string

The condition to filter on. One of "ghost", "rail", "rail-signal", "rolling-stock", "robot-with-logistics-interface", "vehicle", "turret", "crafting-machine", "wall-connectable", "transport-belt-connectable", "circuit-network-connectable", "type", "name", "ghost_type", "ghost_name".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

type

type
:: string

The prototype type

name

name
:: string

The prototype name

ghost_type

type
:: string

The ghost prototype type

ghost_name

name
:: string

The ghost prototype name


filter LuaScriptRaisedBuiltEventFilter

Fields

filter
:: string

The condition to filter on. One of "ghost", "rail", "rail-signal", "rolling-stock", "robot-with-logistics-interface", "vehicle", "turret", "crafting-machine", "wall-connectable", "transport-belt-connectable", "circuit-network-connectable", "type", "name", "ghost_type", "ghost_name".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

type

type
:: string

The prototype type

name

name
:: string

The prototype name

ghost_type

type
:: string

The ghost prototype type

ghost_name

name
:: string

The ghost prototype name


filter LuaRobotMinedEntityEventFilter

Fields

filter
:: string

The condition to filter on. One of "ghost", "rail", "rail-signal", "rolling-stock", "robot-with-logistics-interface", "vehicle", "turret", "crafting-machine", "wall-connectable", "transport-belt-connectable", "circuit-network-connectable", "type", "name", "ghost_type", "ghost_name".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

type

type
:: string

The prototype type

name

name
:: string

The prototype name

ghost_type

type
:: string

The ghost prototype type

ghost_name

name
:: string

The ghost prototype name


filter LuaPrePlayerMinedEntityEventFilter

Fields

filter
:: string

The condition to filter on. One of "ghost", "rail", "rail-signal", "rolling-stock", "robot-with-logistics-interface", "vehicle", "turret", "crafting-machine", "wall-connectable", "transport-belt-connectable", "circuit-network-connectable", "type", "name", "ghost_type", "ghost_name".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

type

type
:: string

The prototype type

name

name
:: string

The prototype name

ghost_type

type
:: string

The ghost prototype type

ghost_name

name
:: string

The ghost prototype name


filter LuaRobotBuiltEntityEventFilter

Fields

filter
:: string

The condition to filter on. One of "ghost", "rail", "rail-signal", "rolling-stock", "robot-with-logistics-interface", "vehicle", "turret", "crafting-machine", "wall-connectable", "transport-belt-connectable", "circuit-network-connectable", "type", "name", "ghost_type", "ghost_name", "force".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

type

type
:: string

The prototype type

name

name
:: string

The prototype name

ghost_type

type
:: string

The ghost prototype type

ghost_name

name
:: string

The ghost prototype name

force

force
:: string

The entity force


filter LuaEntityDeconstructionCancelledEventFilter

Fields

filter
:: string

The condition to filter on. One of "ghost", "rail", "rail-signal", "rolling-stock", "robot-with-logistics-interface", "vehicle", "turret", "crafting-machine", "wall-connectable", "transport-belt-connectable", "circuit-network-connectable", "type", "name", "ghost_type", "ghost_name".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

type

type
:: string

The prototype type

name

name
:: string

The prototype name

ghost_type

type
:: string

The ghost prototype type

ghost_name

name
:: string

The ghost prototype name


filter LuaPlayerBuiltEntityEventFilter

Fields

filter
:: string

The condition to filter on. One of "ghost", "rail", "rail-signal", "rolling-stock", "robot-with-logistics-interface", "vehicle", "turret", "crafting-machine", "wall-connectable", "transport-belt-connectable", "circuit-network-connectable", "type", "name", "ghost_type", "ghost_name", "force".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

type

type
:: string

The prototype type

name

name
:: string

The prototype name

ghost_type

type
:: string

The ghost prototype type

ghost_name

name
:: string

The ghost prototype name

force

force
:: string

The entity force


filter LuaPlayerMinedEntityEventFilter

Fields

filter
:: string

The condition to filter on. One of "ghost", "rail", "rail-signal", "rolling-stock", "robot-with-logistics-interface", "vehicle", "turret", "crafting-machine", "wall-connectable", "transport-belt-connectable", "circuit-network-connectable", "type", "name", "ghost_type", "ghost_name".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

type

type
:: string

The prototype type

name

name
:: string

The prototype name

ghost_type

type
:: string

The ghost prototype type

ghost_name

name
:: string

The ghost prototype name


filter LuaEntityDamagedEventFilter

Fields

filter
:: string

The condition to filter on. One of "ghost", "rail", "rail-signal", "rolling-stock", "robot-with-logistics-interface", "vehicle", "turret", "crafting-machine", "wall-connectable", "transport-belt-connectable", "circuit-network-connectable", "type", "name", "ghost_type", "ghost_name", "original-damage-amount", "final-damage-amount", "damage-type", "final-health".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

type

type
:: string

The prototype type

name

name
:: string

The prototype name

ghost_type

type
:: string

The ghost prototype type

ghost_name

name
:: string

The ghost prototype name

original-damage-amount

comparison

value
:: float

The value to compare against.

final-damage-amount

comparison

value
:: float

The value to compare against.

damage-type

type
:: string

A LuaDamagePrototype name

final-health

comparison

value
:: float

The value to compare against.


filter LuaSectorScannedEventFilter

Fields

filter
:: string

The condition to filter on. One of "ghost", "rail", "rail-signal", "rolling-stock", "robot-with-logistics-interface", "vehicle", "turret", "crafting-machine", "wall-connectable", "transport-belt-connectable", "circuit-network-connectable", "type", "name", "ghost_type", "ghost_name".


mode
:: string?

How to combine this with the previous filter. Must be "or" or "and". Defaults to "or". When evaluating the filters, "and" has higher precedence than "or".


invert
:: boolean?

Inverts the condition. Default is false.

Other attributes may be specified depending on filter:

type

type
:: string

The prototype type

name

name
:: string

The prototype name

ghost_type

type
:: string

The ghost prototype type

ghost_name

name
:: string

The ghost prototype name

|<

Classes

Events

Concepts

Defines

Builtin types

>|