LuaItemCommon

Common methods related to usage of item with data. It is useful when LuaItemStack contains item with data or in general with LuaItem as it can only point at an item with data.

Attributes

is_blueprint

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

If this is a blueprint item.

is_blueprint_book

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

If this is a blueprint book item.

is_item_with_label

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

If this is an item with label item.

is_item_with_inventory

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

If this is an item with inventory item.

is_item_with_entity_data

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

If this is an item with entity data item.

is_selection_tool

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

If this is a selection tool item.

is_item_with_tags

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

If this is an item with tags item.

is_deconstruction_item

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

If this is a deconstruction tool item.

is_upgrade_item

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

If this is a upgrade item.

is_tool

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

If this is a tool item.

is_ammo

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

If this is an ammo item.

is_armor

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

If this is an armor item.

is_repair_tool

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

If this is a repair tool item.

item_number

• Read: uint64
• Write: unknown
• Optional: true

The unique identifier for this item, if any. Note that this ID stays the same no matter where the item is moved to.

preview_icons

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

Icons of this blueprint item, blueprint book, deconstruction item or upgrade planner. An item that doesn't have icons returns nil on read and throws error on write.

grid

• Read: LuaEquipmentGrid
• Write: unknown
• Optional: true

The equipment grid of this item, if any.

owner_location

• Read: ItemLocationData
• Write: unknown
• Optional: false

The location of this item if it can be found.

blueprint_snap_to_grid

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

The snapping grid size in this blueprint item. 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 item.

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

active_index

• Read: uint32
• Write: uint32
• Optional: true

The active blueprint index for this blueprint book. nil if this blueprint book is empty.

label

• Read: string
• Write: string
• Optional: true

The current label for this item, if any.

label_color

• Read: Color
• Write: Color
• Optional: true

The current label color for this item, if any.

allow_manual_label_change

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

Whether the label for this item can be manually changed. When false the label can only be changed through the API.

entity_label

• Read: string
• Write: string
• Optional: true

If this is an item with entity data, get the stored entity label.

entity_color

• Read: Color
• Write: Color
• Optional: true

If this is an item with entity data, get the stored entity color.

entity_logistic_sections

• Read: LogisticSections
• Write: LogisticSections
• Optional: false

If this is an item with entity data, get the stored logistic filters.

entity_request_from_buffers

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

If this is an item with entity data, get the stored request from buffer state.

entity_logistics_enabled

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

If this is an item with entity data, get the stored vehicle logistics enabled state.

entity_enable_logistics_while_moving

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

If this is an item with entity data, get the stored enable logistics while moving state.

entity_driver_is_gunner

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

If this is an item with entity data, get the stored driver is gunner state.

entity_auto_target_without_gunner

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

If this is an item with entity data, get the stored auto target without gunner state.

entity_auto_target_with_gunner

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

If this is an item with entity data, get the stored auto target with gunner state.

tags

• Read: Tags
• Write: Tags
• Optional: false

custom_description

• Read: LocalisedString
• Write: LocalisedString
• Optional: false

The custom description this item-with-tags. This is shown over the normal item description if this is set to a non-empty value.

entity_filter_count

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

The number of entity filters this deconstruction item supports.

entity_filters

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

The entity filters for this deconstruction item. 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_filter_count

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

The number of tile filters this deconstruction item supports.

tile_filters

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

The tile filters for this deconstruction item. 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 item.

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

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

trees_and_rocks_only

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

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

mapper_count

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

The current count of mappers in the upgrade item.

durability

• Read: double
• Write: double
• Optional: false

Durability of the contained item. Automatically capped at the item's maximum durability.

ammo

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

Number of bullets left in the magazine.

Methods

get_inventory

LuaItemCommon.get_inventory(inventory: defines.inventory) -> LuaInventory?

Call As

itemCommon.get_inventory(inventory)

Call Convention

• takes_table: false
• table_optional: false

Access the inner inventory of an item.

Parameters

• inventory: defines.inventory — Index of the inventory to access, which can only be defines.inventory.item_main.

Returns

• LuaInventory? — nil if there is no inventory with the given index.

clear_blueprint

LuaItemCommon.clear_blueprint()

Call As

itemCommon.clear_blueprint()

Call Convention

• takes_table: false
• table_optional: false

Clears this blueprint item.

is_blueprint_setup

LuaItemCommon.is_blueprint_setup() -> boolean

Call As

itemCommon.is_blueprint_setup()

Call Convention

• takes_table: false
• table_optional: false

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

Returns

• boolean

build_blueprint

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

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

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

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

LuaItemCommon.get_blueprint_entity_tags(index: uint32) -> Tags

Call As

itemCommon.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 item.

Parameters

• index: uint32

Returns

• Tags

set_blueprint_entity_tags

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

Call As

itemCommon.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 item.

Parameters

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

get_blueprint_entity_tag

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

Call As

itemCommon.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 item.

Parameters

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

Returns

• AnyBasic?

set_blueprint_entity_tag

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

Call As

itemCommon.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 item.

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

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

Call As

itemCommon.get_blueprint_entities()

Call Convention

• takes_table: false
• table_optional: false

The entities in this blueprint.

Returns

• Array<BlueprintEntity>?

set_blueprint_entities

LuaItemCommon.set_blueprint_entities(entities: Array<BlueprintEntity>)

Call As

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

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

Call As

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

LuaItemCommon.set_blueprint_tiles(tiles: Array<Tile>)

Call As

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

LuaItemCommon.get_blueprint_entity_count() -> uint32

Call As

itemCommon.get_blueprint_entity_count()

Call Convention

• takes_table: false
• table_optional: false

Gets the number of entities in this blueprint item.

Returns

• uint32

get_tag

LuaItemCommon.get_tag(tag_name: string) -> AnyBasic?

Call As

itemCommon.get_tag(tag_name)

Call Convention

• takes_table: false
• table_optional: false

Gets the tag with the given name or returns nil if it doesn't exist.

Parameters

• tag_name: string

Returns

• AnyBasic?

set_tag

LuaItemCommon.set_tag(tag_name: string, tag: AnyBasic)

Call As

itemCommon.set_tag(tag_name, tag)

Call Convention

• takes_table: false
• table_optional: false

Sets the tag with the given name and value.

Parameters

• tag_name: string
• tag: AnyBasic

remove_tag

LuaItemCommon.remove_tag(tag: string) -> boolean

Call As

itemCommon.remove_tag(tag)

Call Convention

• takes_table: false
• table_optional: false

Removes a tag with the given name.

Parameters

• tag: string

Returns

• boolean — If the tag existed and was removed.

get_entity_filter

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

Call As

itemCommon.get_entity_filter(index)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

• index: uint32

Returns

• ItemFilter?

set_entity_filter

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

Call As

itemCommon.set_entity_filter(index, filter)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

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

Returns

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

get_tile_filter

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

Call As

itemCommon.get_tile_filter(index)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

• index: uint32

Returns

• string?

set_tile_filter

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

Call As

itemCommon.set_tile_filter(index, filter)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

• index: uint32
• filter: string | LuaTilePrototype | LuaTile | nil — Writing nil removes the filter.

Returns

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

deconstruct_area

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

Call As

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

Call Convention

• takes_table: true
• table_optional: false

Deconstruct the given area with this deconstruction item.

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

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

Call As

itemCommon.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 item.

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_item

LuaItemCommon.clear_deconstruction_item()

Call As

itemCommon.clear_deconstruction_item()

Call Convention

• takes_table: false
• table_optional: false

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

clear_upgrade_item

LuaItemCommon.clear_upgrade_item()

Call As

itemCommon.clear_upgrade_item()

Call Convention

• takes_table: false
• table_optional: false

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

get_mapper

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

Call As

itemCommon.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 LuaItemCommon::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

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

Call As

itemCommon.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 LuaItemCommon::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.