Factorio.com|Forums|Wiki|Mod Portal|API Docs

# Factorio Runtime Docs Version 2.0.77

# LuaRecord - Runtime Docs

## Class LuaRecord

A reference to a record in the blueprint library. Records in the "my blueprints" shelf are read-only, but records in the "game blueprints" shelf are read/write.

## Members

export_record() | → string | Exports this record to a string.
Exports this record to a string.
clear_blueprint() |  | Clears this blueprint.
Clears this blueprint.
is_blueprint_setup() | → boolean | Is this blueprint setup? [...]
Is this blueprint setup? [...]
build_blueprint{surface=…, force=…, position=…, direction?=…, build_mode?=…, skip_fog_of_war?=…, by_player?=…, raise_built?=…} | → array[LuaEntity] | Build this blueprint at the given location. [...]
Build this blueprint at the given location. [...]
create_blueprint{surface=…, force=…, area=…, always_include_tiles?=…, include_entities?=…, include_modules?=…, include_station_names?=…, include_trains?=…, include_fuel?=…} | → dictionary[uint32 → LuaEntity] | Sets up this blueprint using the found blueprintable entities/tiles on the surface.
Sets up this blueprint using the found blueprintable entities/tiles on the surface.
get_blueprint_entity_tags(index) | → Tags | Gets the tags for the given blueprint entity index in this blueprint.
Gets the tags for the given blueprint entity index in this blueprint.
set_blueprint_entity_tags(index, tags) |  | Sets the tags on the given blueprint entity index in this blueprint.
Sets the tags on the given blueprint entity index in this blueprint.
get_blueprint_entity_tag(index, tag) | → AnyBasic? | Gets the given tag on the given blueprint entity index in this blueprint.
Gets the given tag on the given blueprint entity index in this blueprint.
set_blueprint_entity_tag(index, tag, value) |  | Sets the given tag on the given blueprint entity index in this blueprint.
Sets the given tag on the given blueprint entity index in this blueprint.
get_blueprint_entities() | → array[BlueprintEntity]? | The entities in this blueprint.
The entities in this blueprint.
set_blueprint_entities(entities) |  | Set new entities to be a part of this blueprint.
Set new entities to be a part of this blueprint.
get_blueprint_tiles() | → array[Tile]? | A list of the tiles in this blueprint.
A list of the tiles in this blueprint.
set_blueprint_tiles(tiles) |  | Set specific tiles in this blueprint.
Set specific tiles in this blueprint.
get_blueprint_entity_count() | → uint32 | Gets the number of entities in this blueprint blueprint.
Gets the number of entities in this blueprint blueprint.
get_active_index(player) | → uint32 | The active index of this BlueprintBookRecord. [...]
The active index of this BlueprintBookRecord. [...]
get_selected_record(player) | → LuaRecord? | Gets the currently selected record of the book for the given player. [...]
Gets the currently selected record of the book for the given player. [...]
get_entity_filter(index) | → ItemFilter? | Gets the entity filter at the given index for this deconstruction planner.
Gets the entity filter at the given index for this deconstruction planner.
set_entity_filter(index, filter) | → boolean | Sets the entity filter at the given index for this deconstruction planner.
Sets the entity filter at the given index for this deconstruction planner.
get_tile_filter(index) | → string? | Gets the tile filter at the given index for this deconstruction planner.
Gets the tile filter at the given index for this deconstruction planner.
set_tile_filter(index, filter) | → boolean | Sets the tile filter at the given index for this deconstruction planner.
Sets the tile filter at the given index for this deconstruction planner.
deconstruct_area{surface=…, force=…, area=…, skip_fog_of_war?=…, by_player?=…, super_forced?=…} |  | Deconstruct the given area with this deconstruction planner.
Deconstruct the given area with this deconstruction planner.
cancel_deconstruct_area{surface=…, force=…, area=…, skip_fog_of_war?=…, by_player?=…, super_forced?=…} |  | Cancel deconstruct the given area with this deconstruction planner.
Cancel deconstruct the given area with this deconstruction planner.
clear_deconstruction_data() |  | Clears all settings/filters on this deconstruction planner, resetting it to default values.
Clears all settings/filters on this deconstruction planner, resetting it to default values.
clear_upgrade_data() |  | Clears all settings/filters on this upgrade planner, resetting it to default values.
Clears all settings/filters on this upgrade planner, resetting it to default values.
get_mapper(index, type) | → UpgradeMapperSource or UpgradeMapperDestination | Gets the filter at the given index for this upgrade item. [...]
Gets the filter at the given index for this upgrade item. [...]
set_mapper(index, type, mapper) |  | Sets the module filter at the given index for this upgrade item. [...]
Sets the module filter at the given index for this upgrade item. [...]
valid_for_write | :: R boolean | Is this record valid for writing? [...]
Is this record valid for writing? [...]
type | :: R `"blueprint"` or `"blueprint-book"` or `"deconstruction-planner"` or `"upgrade-planner"` | The type of this blueprint record.
The type of this blueprint record.
preview_icons | :: RW array[BlueprintSignalIcon] | The preview icons for this record.
The preview icons for this record.
is_preview | :: R boolean | Checks if this record is in a preview state.
Checks if this record is in a preview state.
is_blueprint_preview | :: R boolean | Is this blueprint record a preview? [...]
Is this blueprint record a preview? [...]
blueprint_snap_to_grid | :: RW TilePosition? | The snapping grid size in this blueprint. [...]
The snapping grid size in this blueprint. [...]
blueprint_position_relative_to_grid | :: RW TilePosition? | The offset from the absolute grid. [...]
The offset from the absolute grid. [...]
blueprint_absolute_snapping | :: RW boolean | If absolute snapping is enabled on this blueprint.
If absolute snapping is enabled on this blueprint.
blueprint_description | :: RW string | The description for this blueprint or blueprint book.
The description for this blueprint or blueprint book.
cost_to_build | :: R array[ItemWithQualityCount] | List of raw materials required to build this blueprint.
List of raw materials required to build this blueprint.
default_icons | :: R array[BlueprintSignalIcon] | The default icons for a blueprint blueprint.
The default icons for a blueprint blueprint.
contents | :: R dictionary[ItemStackIndex → LuaRecord] | The contents of this BlueprintBookRecord. [...]
The contents of this BlueprintBookRecord. [...]
contents_size | :: R ItemStackIndex | The highest populated index in the contents of this BlueprintBookRecord.
The highest populated index in the contents of this BlueprintBookRecord.
entity_filters | :: RW array[ItemFilter] | The entity filters for this deconstruction planner. [...]
The entity filters for this deconstruction planner. [...]
tile_filters | :: RW array[TileID] | The tile filters for this deconstruction planner. [...]
The tile filters for this deconstruction planner. [...]
entity_filter_mode | :: RW defines.deconstruction_item.entity_filter_mode | The blacklist/whitelist entity filter mode for this deconstruction planner.
The blacklist/whitelist entity filter mode for this deconstruction planner.
tile_filter_mode | :: RW defines.deconstruction_item.tile_filter_mode | The blacklist/whitelist tile filter mode for this deconstruction planner.
The blacklist/whitelist tile filter mode for this deconstruction planner.
tile_selection_mode | :: RW defines.deconstruction_item.tile_selection_mode | The tile selection mode for this deconstruction planner.
The tile selection mode for this deconstruction planner.
trees_and_rocks_only | :: RW boolean | If this deconstruction planner, is set to allow trees and rocks only.
If this deconstruction planner, is set to allow trees and rocks only.
entity_filter_count | :: R uint32 | The number of entity filters this deconstruction planner supports.
The number of entity filters this deconstruction planner supports.
tile_filter_count | :: R uint32 | The number of tile filters this deconstruction planner supports.
The number of tile filters this deconstruction planner supports.
mapper_count | :: R uint32 | The current count of mappers in the upgrade item.
The current count of mappers in the upgrade item.
valid | :: R boolean | Is this object valid? [...]
Is this object valid? [...]
object_name | :: R string | The class name of this object. [...]
The class name of this object. [...]

## Methods

### export_record() → string

Exports this record to a string.

### clear_blueprint()

Clears this blueprint.

Can only be used if this is BlueprintRecord

### is_blueprint_setup() → boolean

Is this blueprint setup? I.e. is it a non-empty blueprint?

Can only be used if this is BlueprintRecord

### build_blueprint{surface=…, force=…, position=…, direction?=…, build_mode?=…, skip_fog_of_war?=…, by_player?=…, raise_built?=…} → array[LuaEntity]

Build this blueprint at the given location.

Built entities can be come invalid between the building of the blueprint and the function returning if by_player or raise_built is used and one of those events invalidates the entity.

#### Parameters

Table with the following fields:

surface | :: SurfaceIdentification | Surface to build on
Surface to build on
force | :: ForceID | Force to use for the building
Force to use for the building
position | :: MapPosition | The position to build at
The position to build at
direction | :: defines.direction? | The direction to use when building
The direction to use when building
build_mode | :: defines.build_mode? | If `normal`, blueprint will not be built if any one thing can't be built. If `forced`, anything that can be built is built and obstructing nature entities will be deconstructed. If `superforced`, all obstructions will be deconstructed and the blueprint will be built.
If `normal`, blueprint will not be built if any one thing can't be built. If `forced`, anything that can be built is built and obstructing nature entities will be deconstructed. If `superforced`, all obstructions will be deconstructed and the blueprint will be built.
skip_fog_of_war | :: boolean? | If chunks covered by fog-of-war are skipped.
If chunks covered by fog-of-war are skipped.
by_player | :: PlayerIdentification? | The player to use if any. If provided defines.events.on_built_entity will also be fired on successful entity creation.
The player to use if any. If provided defines.events.on_built_entity will also be fired on successful entity creation.
raise_built | :: boolean? | If true; defines.events.script_raised_built will be fired on successful entity creation. Note: this is ignored if by_player is provided.
If true; defines.events.script_raised_built will be fired on successful entity creation. Note: this is ignored if by_player is provided.

#### Return values

→ array[LuaEntity] | Array of created ghosts

Can only be used if this is BlueprintRecord

### create_blueprint{surface=…, force=…, area=…, always_include_tiles?=…, include_entities?=…, include_modules?=…, include_station_names?=…, include_trains?=…, include_fuel?=…} → dictionary[uint32 → LuaEntity]

Sets up this blueprint using the found blueprintable entities/tiles on the surface.

#### Parameters

Table with the following fields:

surface | :: SurfaceIdentification | Surface to create from
Surface to create from
force | :: ForceID | Force to use for the creation
Force to use for the creation
area | :: BoundingBox | The bounding box
The bounding box
always_include_tiles | :: boolean? | When true, blueprintable tiles are always included in the blueprint. When false they're only included if no entities exist in the setup area. Defaults to false.
When true, blueprintable tiles are always included in the blueprint. When false they're only included if no entities exist in the setup area. Defaults to false.
include_entities | :: boolean? | When true, entities are included in the blueprint. Defaults to true.
When true, entities are included in the blueprint. Defaults to true.
include_modules | :: boolean? | When true, modules are included in the blueprint. Defaults to true.
When true, modules are included in the blueprint. Defaults to true.
include_station_names | :: boolean? | When true, station names are included in the blueprint. Defaults to false.
When true, station names are included in the blueprint. Defaults to false.
include_trains | :: boolean? | When true, trains are included in the blueprint. Defaults to false.
When true, trains are included in the blueprint. Defaults to false.
include_fuel | :: boolean? | When true, train fuel is included in the blueprint, Defaults to true.
When true, train fuel is included in the blueprint, Defaults to true.

#### Return values

→ dictionary[uint32 → LuaEntity] | The blueprint entity index to source entity mapping.

Can only be used if this is BlueprintRecord

### get_blueprint_entity_tags(index) → Tags

Gets the tags for the given blueprint entity index in this blueprint.

#### Parameters

index | :: uint32 |

Can only be used if this is BlueprintRecord

### set_blueprint_entity_tags(index, tags)

Sets the tags on the given blueprint entity index in this blueprint.

#### Parameters

index | :: uint32 | The entity index
The entity index
tags | :: Tags |

Can only be used if this is BlueprintRecord

### get_blueprint_entity_tag(index, tag) → AnyBasic?

Gets the given tag on the given blueprint entity index in this blueprint.

#### Parameters

index | :: uint32 | The entity index.
The entity index.
tag | :: string | The tag to get.
The tag to get.

Can only be used if this is BlueprintRecord

### set_blueprint_entity_tag(index, tag, value)

Sets the given tag on the given blueprint entity index in this blueprint.

#### Parameters

index | :: uint32 | The entity index.
The entity index.
tag | :: string | The tag to set.
The tag to set.
value | :: AnyBasic | The tag value to set or `nil` to clear the tag.
The tag value to set or `nil` to clear the tag.

Can only be used if this is BlueprintRecord

### get_blueprint_entities() → array[BlueprintEntity]?

The entities in this blueprint.

Can only be used if this is BlueprintRecord

### set_blueprint_entities(entities)

Set new entities to be a part of this blueprint.

#### Parameters

entities | :: array[BlueprintEntity] | The new blueprint entities.
The new blueprint entities.

Can only be used if this is BlueprintRecord

### get_blueprint_tiles() → array[Tile]?

A list of the tiles in this blueprint.

Can only be used if this is BlueprintRecord

### set_blueprint_tiles(tiles)

Set specific tiles in this blueprint.

#### Parameters

tiles | :: array[Tile] | Tiles to be a part of the blueprint.
Tiles to be a part of the blueprint.

Can only be used if this is BlueprintRecord

### get_blueprint_entity_count() → uint32

Gets the number of entities in this blueprint blueprint.

Can only be used if this is BlueprintRecord

### get_active_index(player) → uint32

The active index of this BlueprintBookRecord. For records in "my blueprints", the result will be the same regardless of the player, but records in "game blueprints" may have different active indices per player.

#### Parameters

player | :: PlayerIdentification |

Can only be used if this is BlueprintBookRecord

### get_selected_record(player) → LuaRecord?

Gets the currently selected record of the book for the given player.

Note: this will return a record even if the book is in a preview state.

#### Parameters

player | :: PlayerIdentification |

Can only be used if this is BlueprintBookRecord

### get_entity_filter(index) → ItemFilter?

Gets the entity filter at the given index for this deconstruction planner.

#### Parameters

index | :: uint32 |

Can only be used if this is DeconstructionRecord

### set_entity_filter(index, filter) → boolean

Sets the entity filter at the given index for this deconstruction planner.

#### Parameters

index | :: uint32 |
filter | :: ItemFilter or nil | Writing `nil` removes the filter.
Writing `nil` removes the filter.

#### Return values

→ boolean | Whether the new filter was successfully set (ie. was valid).

Can only be used if this is DeconstructionRecord

### get_tile_filter(index) → string?

Gets the tile filter at the given index for this deconstruction planner.

#### Parameters

index | :: uint32 |

Can only be used if this is DeconstructionRecord

### set_tile_filter(index, filter) → boolean

Sets the tile filter at the given index for this deconstruction planner.

#### Parameters

index | :: uint32 |
filter | :: string or LuaTilePrototype or LuaTile | Setting to nil erases the filter.
Setting to nil erases the filter.

#### Return values

→ boolean | Whether the new filter was successfully set (ie. was valid).

Can only be used if this is DeconstructionRecord

### deconstruct_area{surface=…, force=…, area=…, skip_fog_of_war?=…, by_player?=…, super_forced?=…}

Deconstruct the given area with this deconstruction planner.

#### Parameters

Table with the following fields:

surface | :: SurfaceIdentification | Surface to deconstruct on
Surface to deconstruct on
force | :: ForceID | Force to use for the deconstruction
Force to use for the deconstruction
area | :: BoundingBox | The area to deconstruct
The area to deconstruct
skip_fog_of_war | :: boolean? | If chunks covered by fog-of-war are skipped. Defaults to `false`.
If chunks covered by fog-of-war are skipped. Defaults to `false`.
by_player | :: PlayerIdentification? | The player to use if any.
The player to use if any.
super_forced | :: boolean? | If the deconstruction is super-forced. Defaults to `false`.
If the deconstruction is super-forced. Defaults to `false`.

Can only be used if this is DeconstructionRecord

### cancel_deconstruct_area{surface=…, force=…, area=…, skip_fog_of_war?=…, by_player?=…, super_forced?=…}

Cancel deconstruct the given area with this deconstruction planner.

#### Parameters

Table with the following fields:

surface | :: SurfaceIdentification | Surface to cancel deconstruct on
Surface to cancel deconstruct on
force | :: ForceID | Force to use for canceling deconstruction
Force to use for canceling deconstruction
area | :: BoundingBox | The area to deconstruct
The area to deconstruct
skip_fog_of_war | :: boolean? | If chunks covered by fog-of-war are skipped. Defaults to `false`.
If chunks covered by fog-of-war are skipped. Defaults to `false`.
by_player | :: PlayerIdentification? | The player to use if any.
The player to use if any.
super_forced | :: boolean? | If the cancel deconstruction is super-forced. Defaults to `false`.
If the cancel deconstruction is super-forced. Defaults to `false`.

Can only be used if this is DeconstructionRecord

### clear_deconstruction_data()

Clears all settings/filters on this deconstruction planner, resetting it to default values.

Can only be used if this is DeconstructionRecord

### clear_upgrade_data()

Clears all settings/filters on this upgrade planner, resetting it to default values.

Can only be used if this is UpgradeRecord

### get_mapper(index, type) → UpgradeMapperSource or UpgradeMapperDestination

Gets the filter at the given index for this upgrade item. Note that sources (`"from"` type) that are undefined will read as `{type = "item"}`, while destinations (`"to"` type) that are undefined will read as `nil`.

In contrast to LuaRecord::set_mapper, indices past the upgrade item's current size are considered to be out of bounds.

#### Parameters

index | :: uint32 | The index of the mapper to read.
The index of the mapper to read.
type | :: `"from"` or `"to"` |

Can only be used if this is UpgradeRecord

### set_mapper(index, type, mapper)

Sets the module filter at the given index for this upgrade item.

In contrast to LuaRecord::get_mapper, indices past the upgrade item's current size are valid and expand the list of mappings accordingly, if within reasonable bounds.

#### Parameters

index | :: uint32 | The index of the mapper to set.
The index of the mapper to set.
type | :: `"from"` or `"to"` |
mapper | :: UpgradeMapperSource or UpgradeMapperDestination or nil | The mapper to set. Set `nil` to clear the mapper.
The mapper to set. Set `nil` to clear the mapper.

Can only be used if this is UpgradeRecord

## Attributes

### valid_for_write :: Read boolean

Is this record valid for writing? A record is invalid for write if it is a BlueprintRecord preview or if it is in the "My blueprints" shelf.

### type :: Read `"blueprint"` or `"blueprint-book"` or `"deconstruction-planner"` or `"upgrade-planner"`

The type of this blueprint record.

### preview_icons :: Read|Write array[BlueprintSignalIcon]

The preview icons for this record.

### is_preview :: Read boolean

Checks if this record is in a preview state.

### is_blueprint_preview :: Read boolean

Is this blueprint record a preview? A preview record must be synced by the player before entity and tile data can be read. This property is deprecated in favor of LuaRecord::is_preview and should not be used.

Can only be used if this is BlueprintRecord

### blueprint_snap_to_grid :: Read|Write TilePosition?

The snapping grid size in this blueprint. `nil` if snapping is not enabled.

Can only be used if this is BlueprintRecord

### blueprint_position_relative_to_grid :: Read|Write TilePosition?

The offset from the absolute grid. `nil` if absolute snapping is not enabled.

Can only be used if this is BlueprintRecord

### blueprint_absolute_snapping :: Read|Write boolean

If absolute snapping is enabled on this blueprint.

Can only be used if this is BlueprintRecord

### blueprint_description :: Read|Write string

The description for this blueprint or blueprint book.

Can only be used if this is BlueprintRecord or BlueprintBookRecord

### cost_to_build :: Read array[ItemWithQualityCount]

List of raw materials required to build this blueprint.

Can only be used if this is BlueprintRecord

### default_icons :: Read array[BlueprintSignalIcon]

The default icons for a blueprint blueprint.

Can only be used if this is BlueprintRecord

### contents :: Read dictionary[ItemStackIndex → LuaRecord]

The contents of this BlueprintBookRecord. This is sparse array - it may have gaps, so using `#` will not be reliable. Use LuaRecord::contents_size or `pairs()` to iterate this table.

Can only be used if this is BlueprintBookRecord

### contents_size :: Read ItemStackIndex

The highest populated index in the contents of this BlueprintBookRecord.

Can only be used if this is BlueprintBookRecord

### entity_filters :: Read|Write array[ItemFilter]

The entity filters for this deconstruction planner. The attribute is a sparse array with the keys representing the index of the filter. All prototypes in this array must not have the `"not-deconstructable"` flag set and are either a `cliff` or marked as `minable`.

Can only be used if this is DeconstructionRecord

### tile_filters :: Read|Write array[TileID]

The tile filters for this deconstruction planner. The attribute is a sparse array with the keys representing the index of the filter. Reading filters always returns an array of strings which are the tile prototype names.

Can only be used if this is DeconstructionRecord

### entity_filter_mode :: Read|Write defines.deconstruction_item.entity_filter_mode

The blacklist/whitelist entity filter mode for this deconstruction planner.

Can only be used if this is DeconstructionRecord

### tile_filter_mode :: Read|Write defines.deconstruction_item.tile_filter_mode

The blacklist/whitelist tile filter mode for this deconstruction planner.

Can only be used if this is DeconstructionRecord

### tile_selection_mode :: Read|Write defines.deconstruction_item.tile_selection_mode

The tile selection mode for this deconstruction planner.

Can only be used if this is DeconstructionRecord

### trees_and_rocks_only :: Read|Write boolean

If this deconstruction planner, is set to allow trees and rocks only.

Can only be used if this is DeconstructionRecord

### entity_filter_count :: Read uint32

The number of entity filters this deconstruction planner supports.

Can only be used if this is DeconstructionRecord

### tile_filter_count :: Read uint32

The number of tile filters this deconstruction planner supports.

Can only be used if this is DeconstructionRecord

### mapper_count :: Read uint32

The current count of mappers in the upgrade item.

Can only be used if this is UpgradeRecord

### valid :: Read boolean

Is this object valid? This Lua object holds a reference to an object within the game engine. It is possible that the game-engine object is removed whilst a mod still holds the corresponding Lua object. If that happens, the object becomes invalid, i.e. this attribute will be `false`. Mods are advised to check for object validity if any change to the game state might have occurred between the creation of the Lua object and its access.

### object_name :: Read string

The class name of this object. Available even when `valid` is false. For LuaStruct objects it may also be suffixed with a dotted path to a member of the struct.

Class used in

- LuaControl::cursor_record
- LuaGameScript::blueprints
- LuaPlayer::blueprints
- LuaRecord::get_selected_record()
- LuaRecord::contents
- on_player_deconstructed_area
- on_player_setup_blueprint