LuaItemStack

A reference to an item and count owned by some external entity.

Note: In most instances this is a simple reference as in: it points at a specific slot in an inventory and not the item in the slot.
Note: In the instance this references an item on a LuaTransportLine the reference is only guaranteed to stay valid (and refer to the same item) as long as nothing changes the transport line.
class LuaItemStack - sort
is_blueprint_setup() → boolean Is this blueprint item setup?
get_blueprint_entities() → array of blueprint entity Entities in this blueprint.
set_blueprint_entities(entities) Set new entities to be a part of this blueprint.
add_ammo(amount) Add ammo to this ammo item.
drain_ammo(amount) Remove ammo from this ammo item.
add_durability(amount) Add durability to this tool item.
drain_durability(amount) Remove durability from this tool item.
can_set_stack(stack) → boolean Would a call to LuaItemStack::set_stack succeed?
set_stack(stack) → boolean Set this item stack to another item stack.
transfer_stack(stack) → boolean Transfers the given item stack into this item stack.
export_stack() → string Export a supported item (blueprint, blueprint-book, deconstruction-planner, upgrade-planner, item-with-tags) to a string
import_stack(data) → int Import a supported item (blueprint, blueprint-book, deconstruction-planner, upgrade-planner, item-with-tags) from a string
swap_stack(stack) → boolean Swaps this item stack with the given item stack if allowed.
clear() Clear this item stack.
get_blueprint_tiles() → array of blueprint tile Tiles in this blueprint
set_blueprint_tiles(tiles) Set tiles in this blueprint
get_inventory(inventory) → LuaInventory Access the inner inventory of an item.
build_blueprint{surface=…, force=…, position=…, force_build=…, direction=…, skip_fog_of_war=…, by_player=…, raise_built=…} → array of LuaEntity Build this blueprint
deconstruct_area{surface=…, force=…, area=…, skip_fog_of_war=…, by_player=…} Deconstruct the given area with this deconstruction item.
cancel_deconstruct_area{surface=…, force=…, area=…, skip_fog_of_war=…, by_player=…} Cancel deconstruct the given area with this deconstruction item.
create_blueprint{surface=…, force=…, area=…, always_include_tiles=…} → dictionary uintLuaEntity Sets up this blueprint using the found blueprintable entities/tiles on the surface.
get_tag(tag_name) → Any Gets the tag with the given name or returns nil if it doesn't exist.
set_tag(tag_name, tag) → Any Sets the tag with the given name and value.
remove_tag(tag) → boolean Removes a tag with the given name.
clear_blueprint() Clears this blueprint item.
get_entity_filter(index) → string Gets the entity filter at the given index for this deconstruction item.
set_entity_filter(index, filter) → boolean Sets the entity filter at the given index for this deconstruction item.
get_tile_filter(index) → string Gets the tile filter at the given index for this deconstruction item.
set_tile_filter(index, filter) → boolean Sets the tile filter at the given index for this deconstruction item.
clear_deconstruction_item() Clears all settings/filters on this deconstruction item resetting it to default values.
clear_upgrade_item() Clears all settings/filters on this upgrade item resetting it to default values.
get_mapper(index, type) → UpgradeFilter Gets the filter at the given index for this upgrade item.
set_mapper(index, type, filter) Sets the module filter at the given index for this upgrade item.
get_blueprint_entity_count() → uint Gets the number of entities in this blueprint item.
get_blueprint_entity_tags(index) → Tags Gets the tags for the given blueprint entity index in this blueprint item.
set_blueprint_entity_tags(index, tags) Sets the tags on the given blueprint entity index in this blueprint item.
get_blueprint_entity_tag(index, tag) → Any Gets the given tag on the given blueprint entity index in this blueprint item.
set_blueprint_entity_tag(index, tag, value) Sets the given tag on the given blueprint entity index in this blueprint item.
valid_for_read :: boolean [R] Is this valid for reading?
prototype :: LuaItemPrototype [R] Prototype of the item held in this stack.
name :: string [R] Prototype name of the item held in this stack.
type :: string [R] Type of the item prototype.
count :: uint [RW] Number of items in this stack.
grid :: LuaEquipmentGrid [R] The equipment grid of this item or nil if this item doesn't have a grid.
health :: float [RW] How much health the item has, as a number in range [0, 1].
durability :: double [RW] Durability of the contained item.
ammo :: uint [RW] Number of bullets left in the magazine.
blueprint_icons :: array of Icon [RW] Icons of a blueprint item.
label :: string [RW] The current label for this item.
label_color :: Color [RW] The current label color for this item.
allow_manual_label_change :: boolean [RW] If the label for this item can be manually changed.
cost_to_build :: dictionary stringuint [R] Raw materials required to build this blueprint.
extends_inventory :: boolean [RW] If this item extends the inventory it resides in (provides its contents for counts, crafting, insertion).
prioritize_insertion_mode :: string [RW] The insertion mode priority this ItemWithInventory uses when items are inserted into an inventory it resides in.
default_icons :: array of Icon [R] The default icons for a blueprint item.
tags :: Tags [RW]
custom_description :: LocalisedString [RW] The custom description this item-with-tags.
entity_filters :: array of string [RW] The entity filters for this deconstruction item.
tile_filters :: array of string [RW] The tile filters for this deconstruction item.
entity_filter_mode :: defines.deconstruction_item.entity_filter_mode [RW] The blacklist/whitelist entity filter mode for this deconstruction item.
tile_filter_mode :: defines.deconstruction_item.tile_filter_mode [RW] The blacklist/whitelist tile filter mode for this deconstruction item.
tile_selection_mode :: defines.deconstruction_item.tile_selection_mode [RW] The tile selection mode for this deconstruction item.
trees_and_rocks_only :: boolean [RW] If this deconstruction item is set to allow trees and rocks only.
entity_filter_count :: uint [R] The number of entity filters this deconstruction item supports.
tile_filter_count :: uint [R] The number of tile filters this deconstruction item supports.
active_index :: uint [RW] The active blueprint index for this blueprint book.
item_number :: uint [R] The unique ID for this item if it has a unique ID or nil.
is_blueprint :: boolean [R] If this is a blueprint item.
is_blueprint_book :: boolean [R] If this is a blueprint book item.
is_module :: boolean [R] If this is a module item.
is_tool :: boolean [R] If this is a tool item.
is_mining_tool :: boolean [R] If this is a mining tool item.
is_armor :: boolean [R] If this is an armor item.
is_repair_tool :: boolean [R] If this is a repair tool item.
is_item_with_label :: boolean [R] If this is an item with label item.
is_item_with_inventory :: boolean [R] If this is an item with inventory item.
is_item_with_entity_data :: boolean [R] If this is an item with entity data item.
is_selection_tool :: boolean [R] If this is a selection tool item.
is_item_with_tags :: boolean [R] If this is an item with tags item.
is_deconstruction_item :: boolean [R] If this is a deconstruction tool item.
is_upgrade_item :: boolean [R] If this is a upgrade item.
valid :: boolean [R] Is this object valid?
help() → string All methods, and properties that this object supports.
is_blueprint_setup() → boolean

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

get_blueprint_entities() → array of blueprint entity

Entities in this blueprint.

Return value
The fields of an entity table depend on the type of the entity. Every entity has at least the following fields:
  • entity_number :: uint: Entity's unique identifier in this blueprint
  • name :: string: Prototype name of the entity
  • position :: Position: Position of the entity
  • direction :: defines.direction (optional): The direction the entity is facing. Only present for entities that can face in different directions.
  • other: Entity-specific fields...
Can only be used if this is BlueprintItem
set_blueprint_entities(entities)

Set new entities to be a part of this blueprint.

Parameters
entities :: array of blueprint entity: New blueprint entities. The format is the same as in LuaItemStack::get_blueprint_entities.
Can only be used if this is BlueprintItem
add_ammo(amount)

Add ammo to this ammo item.

Parameters
amount :: uint: Amount of ammo to add.
Can only be used if this is AmmoItem
drain_ammo(amount)

Remove ammo from this ammo item.

Parameters
amount :: uint: Amount of ammo to remove.
Can only be used if this is AmmoItem
add_durability(amount)

Add durability to this tool item.

Parameters
amount :: double: Amount of durability to add.
Can only be used if this is ToolItem
drain_durability(amount)

Remove durability from this tool item.

Parameters
amount :: double: Amount of durability to remove.
Can only be used if this is ToolItem
can_set_stack(stack) → boolean

Would a call to LuaItemStack::set_stack succeed?

Parameters
stack :: ItemStackSpecification (optional): Stack that would be set, possibly nil.
set_stack(stack) → boolean

Set this item stack to another item stack.

Parameters
stack :: ItemStackSpecification (optional): Item stack to set this one to. Omitting this parameter or passing nil will clear this item stack, as if by calling LuaItemStack::clear.
Return value
Was the stack set successfully?
transfer_stack(stack) → boolean

Transfers the given item stack into this item stack.

Parameters
Return value
True if the full stack was transferred.
export_stack() → string

Export a supported item (blueprint, blueprint-book, deconstruction-planner, upgrade-planner, item-with-tags) to a string

Return value
The exported string
import_stack(data) → int

Import a supported item (blueprint, blueprint-book, deconstruction-planner, upgrade-planner, item-with-tags) from a string

Parameters
data :: string: The string to import
Return value
0 if the import succeeded with no errors. -1 if the import succeeded with errors. 1 if the import failed.
swap_stack(stack) → boolean

Swaps this item stack with the given item stack if allowed.

Parameters
stack :: LuaItemStack
Return value
if the 2 stacks were swapped successfully.
clear()

Clear this item stack.

get_blueprint_tiles() → array of blueprint tile

Tiles in this blueprint

Return value
A blueprint tile is a table:
Can only be used if this is BlueprintItem
set_blueprint_tiles(tiles)

Set tiles in this blueprint

Parameters
tiles :: array of blueprint tile: Tiles to be a part of the blueprint; the format is the same as is returned from the corresponding get function; see LuaItemStack::get_blueprint_tiles.
Can only be used if this is BlueprintItem
get_inventory(inventory) → LuaInventory

Access the inner inventory of an item.

Parameters
inventory :: defines.inventory: Index of the inventory to access -- currently can only be defines.inventory.item_main.
Return value
or nil if there is no inventory with the given index.
build_blueprint{surface=…, force=…, position=…, force_build=…, direction=…, skip_fog_of_war=…, by_player=…, raise_built=…} → array of LuaEntity

Build this blueprint

Parameters
Table with the following fields:
Return value
Array of created ghosts
Note: 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.
deconstruct_area{surface=…, force=…, area=…, skip_fog_of_war=…, by_player=…}

Deconstruct the given area with this deconstruction item.

Parameters
Table with the following fields:
cancel_deconstruct_area{surface=…, force=…, area=…, skip_fog_of_war=…, by_player=…}

Cancel deconstruct the given area with this deconstruction item.

Parameters
Table with the following fields:
create_blueprint{surface=…, force=…, area=…, always_include_tiles=…} → dictionary uintLuaEntity

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

Parameters
Table with the following fields:
  • surface :: SurfaceSpecification: Surface to create from
  • force :: ForceSpecification: Force to use for the creation
  • area :: BoundingBox: The bounding box
  • always_include_tiles :: boolean (optional): When true, blueprintable tiles are always included in the blueprint. When false they're only included if no entities exist in the setup area.
Return value
The blueprint entity index to source entity mapping.
get_tag(tag_name) → Any

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

Parameters
tag_name :: string
Can only be used if this is ItemWithTags
set_tag(tag_name, tag) → Any

Sets the tag with the given name and value.

Parameters
tag_name :: string
tag :: Any
Can only be used if this is ItemWithTags
remove_tag(tag) → boolean

Removes a tag with the given name.

Parameters
tag :: string
Return value
If the tag existed and was removed.
Can only be used if this is ItemWithTags
clear_blueprint()

Clears this blueprint item.

Can only be used if this is BlueprintItem
get_entity_filter(index) → string

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

Parameters
index :: uint
Can only be used if this is DeconstructionItem
set_entity_filter(index, filter) → boolean

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

Parameters
index :: uint
filter :: string or LuaEntityPrototype or LuaEntity: Setting to nil erases the filter.
Return value
If the new filter was set (was valid.)
Can only be used if this is DeconstructionItem
get_tile_filter(index) → string

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

Parameters
index :: uint
Can only be used if this is DeconstructionItem
set_tile_filter(index, filter) → boolean

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

Parameters
index :: uint
filter :: string or LuaTilePrototype or LuaTile: Setting to nil erases the filter.
Return value
If the new filter was set (was valid.)
Can only be used if this is DeconstructionItem
clear_deconstruction_item()

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

Can only be used if this is DeconstructionItem
clear_upgrade_item()

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

Can only be used if this is UpgradeItem
get_mapper(index, type) → UpgradeFilter

Gets the filter at the given index for this upgrade item.

Parameters
index :: uint: The index of the mapper to read.
type :: string: 'from' or 'to'.
Can only be used if this is UpgradeItem
set_mapper(index, type, filter)

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

Parameters
index :: uint: The index of the mapper to set.
type :: string: from or to.
filter :: UpgradeFilter: The filter to set or nil
Can only be used if this is UpgradeItem
get_blueprint_entity_count() → uint

Gets the number of entities in this blueprint item.

Can only be used if this is BlueprintItem
get_blueprint_entity_tags(index) → Tags

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

Parameters
index :: uint
Can only be used if this is BlueprintItem
set_blueprint_entity_tags(index, tags)

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

Parameters
index :: uint: The entity index
tags :: Tags
Can only be used if this is BlueprintItem
get_blueprint_entity_tag(index, tag) → Any

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

Parameters
index :: uint: The entity index
tag :: string: The tag to get
Can only be used if this is BlueprintItem
set_blueprint_entity_tag(index, tag, value)

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

Parameters
index :: uint: The entity index
tag :: string: The tag to set
value :: Any: The tag value to set or nil to clear the tag
Can only be used if this is BlueprintItem
valid_for_read :: boolean [Read-only]

Is this valid for reading? Differs from the usual valid in that valid will be true even if the item stack is blank but the entity that holds it is still valid.

prototype :: LuaItemPrototype [Read-only]

Prototype of the item held in this stack.

name :: string [Read-only]

Prototype name of the item held in this stack.

type :: string [Read-only]

Type of the item prototype.

count :: uint [Read-Write]

Number of items in this stack.

grid :: LuaEquipmentGrid [Read-only]

The equipment grid of this item or nil if this item doesn't have a grid.

health :: float [Read-Write]

How much health the item has, as a number in range [0, 1].

durability :: double [Read-Write]

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

Note: When used on a non-tool item, the value of this attribute is nil.
ammo :: uint [Read-Write]

Number of bullets left in the magazine.

Can only be used if this is AmmoItem
blueprint_icons :: array of Icon [Read-Write]

Icons of a blueprint item. Every entry of this array has the following fields:

  • signal :: SignalID: Slot icon to use. The slot will have the icon of the specified signal. This allows the use of any item icon, as well as virtual signal icons.
  • index :: uint: Index of the icon in the blueprint icons slots. Has to be in {1, 2, 3, 4}.

Can only be used if this is BlueprintItem
label :: string [Read-Write]

The current label for this item. Nil when none.

Can only be used if this is ItemWithLabel
label_color :: Color [Read-Write]

The current label color for this item. Nil when none.

Can only be used if this is ItemWithLabel
allow_manual_label_change :: boolean [Read-Write]

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

Can only be used if this is ItemWithLabel
cost_to_build :: dictionary stringuint [Read-only]

Raw materials required to build this blueprint. Result is a dictionary mapping each item prototype name to the required count.

Can only be used if this is BlueprintItem
extends_inventory :: boolean [Read-Write]

If this item extends the inventory it resides in (provides its contents for counts, crafting, insertion). Only callable on items with inventories.

Can only be used if this is ItemWithInventory
prioritize_insertion_mode :: string [Read-Write]

The insertion mode priority this ItemWithInventory uses when items are inserted into an inventory it resides in. Only callable on items with inventories.

Can only be used if this is ItemWithInventory
default_icons :: array of Icon [Read-only]

The default icons for a blueprint item. Every entry of this array has the following fields :

  • name :: string: Prototype name of the item whose icon to use
  • index :: uint: Index of the icon in the blueprint icons slots. Has to be in {1, 2, 3, 4}.

Can only be used if this is BlueprintItem
tags :: Tags [Read-Write]

Can only be used if this is ItemWithTags
custom_description :: LocalisedString [Read-Write]

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_filters :: array of string [Read-Write]

The entity filters for this deconstruction item.

tile_filters :: array of string [Read-Write]

The tile filters for this deconstruction item.

entity_filter_mode :: defines.deconstruction_item.entity_filter_mode [Read-Write]

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

Can only be used if this is DeconstructionItem
tile_filter_mode :: defines.deconstruction_item.tile_filter_mode [Read-Write]

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

Can only be used if this is DeconstructionItem
tile_selection_mode :: defines.deconstruction_item.tile_selection_mode [Read-Write]

The tile selection mode for this deconstruction item.

Can only be used if this is DeconstructionItem
trees_and_rocks_only :: boolean [Read-Write]

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

Can only be used if this is DeconstructionItem
entity_filter_count :: uint [Read-only]

The number of entity filters this deconstruction item supports.

Can only be used if this is DeconstructionItem
tile_filter_count :: uint [Read-only]

The number of tile filters this deconstruction item supports.

Can only be used if this is DeconstructionItem
active_index :: uint [Read-Write]

The active blueprint index for this blueprint book.

Can only be used if this is BlueprintBookItem
item_number :: uint [Read-only]

The unique ID for this item if it has a unique ID or nil. The following item types have unique IDs:

  • "armor"
  • "blueprint"
  • "blueprint-book"
  • "deconstruction-item"
  • "item-with-entity-data"
  • "item-with-inventory"
  • "selection-tool"
  • "item-with-tags"

is_blueprint :: boolean [Read-only]

If this is a blueprint item.

is_blueprint_book :: boolean [Read-only]

If this is a blueprint book item.

is_module :: boolean [Read-only]

If this is a module item.

is_tool :: boolean [Read-only]

If this is a tool item.

is_mining_tool :: boolean [Read-only]

If this is a mining tool item.

is_armor :: boolean [Read-only]

If this is an armor item.

is_repair_tool :: boolean [Read-only]

If this is a repair tool item.

is_item_with_label :: boolean [Read-only]

If this is an item with label item.

is_item_with_inventory :: boolean [Read-only]

If this is an item with inventory item.

is_item_with_entity_data :: boolean [Read-only]

If this is an item with entity data item.

is_selection_tool :: boolean [Read-only]

If this is a selection tool item.

is_item_with_tags :: boolean [Read-only]

If this is an item with tags item.

is_deconstruction_item :: boolean [Read-only]

If this is a deconstruction tool item.

is_upgrade_item :: boolean [Read-only]

If this is a upgrade item.