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.

Attributes

valid_for_write

• Read: boolean
• Write: unknown
• Optional: false

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" | "blueprint-book" | "deconstruction-planner" | "upgrade-planner"
• Write: unknown
• Optional: false

The type of this blueprint record.

preview_icons

• Read: Array<BlueprintSignalIcon>
• Write: Array<BlueprintSignalIcon>
• Optional: false

The preview icons for this record.

is_preview

• Read: boolean
• Write: unknown
• Optional: false

Checks if this record is in a preview state.

is_blueprint_preview

• Read: boolean
• Write: unknown
• Optional: false

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.

blueprint_snap_to_grid

• Read: TilePosition
• Write: TilePosition
• Optional: true

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

blueprint_position_relative_to_grid

• Read: TilePosition
• Write: TilePosition
• Optional: true

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

blueprint_absolute_snapping

• Read: boolean
• Write: boolean
• Optional: false

If absolute snapping is enabled on this blueprint.

blueprint_description

• Read: string
• Write: string
• Optional: false

The description for this blueprint or blueprint book.

cost_to_build

• Read: ItemWithQualityCounts
• Write: unknown
• Optional: false

List of raw materials required to build this blueprint.

default_icons

• Read: Array<BlueprintSignalIcon>
• Write: unknown
• Optional: false

The default icons for a blueprint blueprint.

contents

• Read: Dict<ItemStackIndex, LuaRecord>
• Write: unknown
• Optional: false

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.

contents_size

• Read: ItemStackIndex
• Write: unknown
• Optional: false

The highest populated index in the contents of this BlueprintBookRecord.

entity_filters

• Read: Array<ItemFilter>
• Write: Array<ItemFilter>
• Optional: false

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.

tile_filters

• Read: Array<TileID>
• Write: Array<TileID>
• Optional: false

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.

entity_filter_mode

• Read: defines.deconstruction_item.entity_filter_mode
• Write: defines.deconstruction_item.entity_filter_mode
• Optional: false

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

tile_filter_mode

• Read: defines.deconstruction_item.tile_filter_mode
• Write: defines.deconstruction_item.tile_filter_mode
• Optional: false

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

tile_selection_mode

• Read: defines.deconstruction_item.tile_selection_mode
• Write: defines.deconstruction_item.tile_selection_mode
• Optional: false

The tile selection mode for this deconstruction planner.

trees_and_rocks_only

• Read: boolean
• Write: boolean
• Optional: false

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

entity_filter_count

• Read: uint32
• Write: unknown
• Optional: false

The number of entity filters this deconstruction planner supports.

tile_filter_count

• Read: uint32
• Write: unknown
• Optional: false

The number of tile filters this deconstruction planner supports.

mapper_count

• Read: uint32
• Write: unknown
• Optional: false

The current count of mappers in the upgrade item.

valid

• Read: boolean
• Write: unknown
• Optional: false

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
• Write: unknown
• Optional: false

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.

Methods

export_record

LuaRecord.export_record() -> string

Call As

record.export_record()

Call Convention

• takes_table: false
• table_optional: false

Exports this record to a string.

Returns

• string

clear_blueprint

LuaRecord.clear_blueprint()

Call As

record.clear_blueprint()

Call Convention

• takes_table: false
• table_optional: false

Clears this blueprint.

is_blueprint_setup

LuaRecord.is_blueprint_setup() -> boolean

Call As

record.is_blueprint_setup()

Call Convention

• takes_table: false
• table_optional: false

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

Returns

• boolean

build_blueprint

LuaRecord.build_blueprint{ surface: SurfaceIdentification, force: ForceID, position: MapPosition, direction?: defines.direction, build_mode?: defines.build_mode, skip_fog_of_war?: boolean, by_player?: PlayerIdentification, raise_built?: boolean } -> Array<LuaEntity>

Call As

record.build_blueprint{ surface=surface, force=force, position=position }

Call Convention

• takes_table: true
• table_optional: false

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

• surface: SurfaceIdentification — Surface to build on
• force: ForceID — Force to use for the building
• position: MapPosition — The position to build at
• direction?: defines.direction — 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.
• skip_fog_of_war?: boolean — 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.
• 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.

Returns

• Array<LuaEntity> — Array of created ghosts

create_blueprint

LuaRecord.create_blueprint{ surface: SurfaceIdentification, force: ForceID, area: BoundingBox, always_include_tiles?: boolean, include_entities?: boolean, include_modules?: boolean, include_station_names?: boolean, include_trains?: boolean, include_fuel?: boolean } -> Dict<uint32, LuaEntity>

Call As

record.create_blueprint{ surface=surface, force=force, area=area }

Call Convention

• takes_table: true
• table_optional: false

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

Parameters

• surface: SurfaceIdentification — Surface to create from
• force: ForceID — Force to use for the creation
• area: BoundingBox — 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.
• include_entities?: boolean — 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.
• include_station_names?: boolean — 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.
• include_fuel?: boolean — When true, train fuel is included in the blueprint, Defaults to true.

Returns

• Dict<uint32, LuaEntity> — The blueprint entity index to source entity mapping.

get_blueprint_entity_tags

LuaRecord.get_blueprint_entity_tags(index: uint32) -> Tags

Call As

record.get_blueprint_entity_tags(index)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

• index: uint32

Returns

• Tags

set_blueprint_entity_tags

LuaRecord.set_blueprint_entity_tags(index: uint32, tags: Tags)

Call As

record.set_blueprint_entity_tags(index, tags)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

• index: uint32 — The entity index
• tags: Tags

get_blueprint_entity_tag

LuaRecord.get_blueprint_entity_tag(index: uint32, tag: string) -> AnyBasic?

Call As

record.get_blueprint_entity_tag(index, tag)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

• index: uint32 — The entity index.
• tag: string — The tag to get.

Returns

• AnyBasic?

set_blueprint_entity_tag

LuaRecord.set_blueprint_entity_tag(index: uint32, tag: string, value: AnyBasic)

Call As

record.set_blueprint_entity_tag(index, tag, value)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

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

get_blueprint_entities

LuaRecord.get_blueprint_entities() -> Array<BlueprintEntity>?

Call As

record.get_blueprint_entities()

Call Convention

• takes_table: false
• table_optional: false

The entities in this blueprint.

Returns

• Array<BlueprintEntity>?

set_blueprint_entities

LuaRecord.set_blueprint_entities(entities: Array<BlueprintEntity>)

Call As

record.set_blueprint_entities(entities)

Call Convention

• takes_table: false
• table_optional: false

Set new entities to be a part of this blueprint.

Parameters

• entities: Array<BlueprintEntity> — The new blueprint entities.

get_blueprint_tiles

LuaRecord.get_blueprint_tiles() -> Array<Tile>?

Call As

record.get_blueprint_tiles()

Call Convention

• takes_table: false
• table_optional: false

A list of the tiles in this blueprint.

Returns

• Array<Tile>?

set_blueprint_tiles

LuaRecord.set_blueprint_tiles(tiles: Array<Tile>)

Call As

record.set_blueprint_tiles(tiles)

Call Convention

• takes_table: false
• table_optional: false

Set specific tiles in this blueprint.

Parameters

• tiles: Array<Tile> — Tiles to be a part of the blueprint.

get_blueprint_entity_count

LuaRecord.get_blueprint_entity_count() -> uint32

Call As

record.get_blueprint_entity_count()

Call Convention

• takes_table: false
• table_optional: false

Gets the number of entities in this blueprint blueprint.

Returns

• uint32

get_active_index

LuaRecord.get_active_index(player: PlayerIdentification) -> uint32

Call As

record.get_active_index(player)

Call Convention

• takes_table: false
• table_optional: false

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

Returns

• uint32

get_selected_record

LuaRecord.get_selected_record(player: PlayerIdentification) -> LuaRecord?

Call As

record.get_selected_record(player)

Call Convention

• takes_table: false
• table_optional: false

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

Returns

• LuaRecord?

get_entity_filter

LuaRecord.get_entity_filter(index: uint32) -> ItemFilter?

Call As

record.get_entity_filter(index)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

• index: uint32

Returns

• ItemFilter?

set_entity_filter

LuaRecord.set_entity_filter(index: uint32, filter: ItemFilter | nil) -> boolean

Call As

record.set_entity_filter(index, filter)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

• index: uint32
• filter: ItemFilter | nil — Writing nil removes the filter.

Returns

• boolean — Whether the new filter was successfully set (ie. was valid).

get_tile_filter

LuaRecord.get_tile_filter(index: uint32) -> string?

Call As

record.get_tile_filter(index)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

• index: uint32

Returns

• string?

set_tile_filter

LuaRecord.set_tile_filter(index: uint32, filter: string | LuaTilePrototype | LuaTile) -> boolean

Call As

record.set_tile_filter(index, filter)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

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

Returns

• boolean — Whether the new filter was successfully set (ie. was valid).

deconstruct_area

LuaRecord.deconstruct_area{ surface: SurfaceIdentification, force: ForceID, area: BoundingBox, skip_fog_of_war?: boolean, by_player?: PlayerIdentification, super_forced?: boolean }

Call As

record.deconstruct_area{ surface=surface, force=force, area=area }

Call Convention

• takes_table: true
• table_optional: false

Deconstruct the given area with this deconstruction planner.

Parameters

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

cancel_deconstruct_area

LuaRecord.cancel_deconstruct_area{ surface: SurfaceIdentification, force: ForceID, area: BoundingBox, skip_fog_of_war?: boolean, by_player?: PlayerIdentification, super_forced?: boolean }

Call As

record.cancel_deconstruct_area{ surface=surface, force=force, area=area }

Call Convention

• takes_table: true
• table_optional: false

Cancel deconstruct the given area with this deconstruction planner.

Parameters

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

clear_deconstruction_data

LuaRecord.clear_deconstruction_data()

Call As

record.clear_deconstruction_data()

Call Convention

• takes_table: false
• table_optional: false

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

clear_upgrade_data

LuaRecord.clear_upgrade_data()

Call As

record.clear_upgrade_data()

Call Convention

• takes_table: false
• table_optional: false

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

get_mapper

LuaRecord.get_mapper(index: uint32, type: "from" | "to") -> UpgradeMapperSource | UpgradeMapperDestination

Call As

record.get_mapper(index, type)

Call Convention

• takes_table: false
• table_optional: false

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.
• type: "from" | "to"

Returns

• UpgradeMapperSource | UpgradeMapperDestination

set_mapper

LuaRecord.set_mapper(index: uint32, type: "from" | "to", mapper: UpgradeMapperSource | UpgradeMapperDestination | nil)

Call As

record.set_mapper(index, type, mapper)

Call Convention

• takes_table: false
• table_optional: false

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.
• type: "from" | "to"
• mapper: UpgradeMapperSource | UpgradeMapperDestination | nil — The mapper to set. Set nil to clear the mapper.