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

# Factorio Runtime Docs Version 2.0.77

# LuaItemStack - Runtime Docs

## Class LuaItemStack extends LuaItemCommon

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

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.

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.

Inherits from LuaItemCommon

## Members

add_ammo(amount) |  | Add ammo to this ammo item.
Add ammo to this ammo item.
drain_ammo(amount) |  | Remove ammo from this ammo item.
Remove ammo from this ammo item.
add_durability(amount) |  | Add durability to this tool item.
Add durability to this tool item.
drain_durability(amount) |  | Remove durability from this tool item.
Remove durability from this tool item.
use_capsule(entity, target_position) | → array[LuaEntity] | Use the capsule item with the entity as the source, targeting the given position.
Use the capsule item with the entity as the source, targeting the given position.
can_set_stack(stack?) | → boolean | Would a call to LuaItemStack::set_stack succeed?
Would a call to LuaItemStack::set_stack succeed?
set_stack(stack?) | → boolean | Set this item stack to another item stack.
Set this item stack to another item stack.
transfer_stack(stack, amount?) | → boolean | Transfers the given item stack into this item stack.
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.
Export a supported item (blueprint, blueprint-book, deconstruction-planner, upgrade-planner, item-with-tags) to a string.
import_stack(data) | → int32 | Import a supported item (blueprint, blueprint-book, deconstruction-planner, upgrade-planner, item-with-tags) from a string.
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.
Swaps this item stack with the given item stack if allowed.
clear() |  | Clear this item stack.
Clear this item stack.
create_grid() | → LuaEquipmentGrid | Creates the equipment grid for this item if it doesn't exist and this is an item-with-entity-data that supports equipment grids.
Creates the equipment grid for this item if it doesn't exist and this is an item-with-entity-data that supports equipment grids.
spoil() |  | Spoils this item if the item can spoil.
Spoils this item if the item can spoil.
valid_for_read | :: R boolean | Is this valid for reading? [...]
Is this valid for reading? [...]
prototype | :: R LuaItemPrototype | Prototype of the item held in this stack.
Prototype of the item held in this stack.
name | :: R string | Prototype name of the item held in this stack.
Prototype name of the item held in this stack.
type | :: R string | Type of the item prototype.
Type of the item prototype.
count | :: RW uint32 | Number of items in this stack.
Number of items in this stack.
health | :: RW float | How much health the item has, as a number in range `[0, 1]`.
How much health the item has, as a number in range `[0, 1]`.
quality | :: R LuaQualityPrototype | The quality of this item.
The quality of this item.
spoil_tick | :: RW MapTick | The tick this item spoils, or `0` if it does not spoil. [...]
The tick this item spoils, or `0` if it does not spoil. [...]
spoil_percent | :: RW double | The percent spoiled this item is if it spoils. [...]
The percent spoiled this item is if it spoils. [...]
item | :: R LuaItem? | If the item has additional data, returns LuaItem pointing at the extra data, otherwise returns nil.
If the item has additional data, returns LuaItem pointing at the extra data, otherwise returns nil.
is_module | :: R boolean | If this is a module
If this is a module
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. [...]

Inherited from LuaItemCommon

get_inventory(inventory) | → LuaInventory? | Access the inner inventory of an item.
Access the inner inventory of an item.
clear_blueprint() |  | Clears this blueprint item.
Clears this blueprint item.
is_blueprint_setup() | → boolean | Is this blueprint item setup? [...]
Is this blueprint item 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 item.
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.
Sets the tags on the given blueprint entity index in this blueprint item.
get_blueprint_entity_tag(index, tag) | → AnyBasic? | Gets the given tag on the given blueprint entity index in this blueprint item.
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.
Sets the given tag on the given blueprint entity index in this blueprint item.
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 item.
Gets the number of entities in this blueprint item.
get_tag(tag_name) | → AnyBasic? | Gets the tag with the given name or returns `nil` if it doesn't exist.
Gets the tag with the given name or returns `nil` if it doesn't exist.
set_tag(tag_name, tag) |  | Sets the tag with the given name and value.
Sets the tag with the given name and value.
remove_tag(tag) | → boolean | Removes a tag with the given name.
Removes a tag with the given name.
get_entity_filter(index) | → ItemFilter? | Gets the entity filter at the given index for this deconstruction item.
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.
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.
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.
Sets the tile filter at the given index for this deconstruction item.
deconstruct_area{surface=…, force=…, area=…, skip_fog_of_war?=…, by_player?=…, super_forced?=…} |  | Deconstruct the given area with this deconstruction item.
Deconstruct the given area with this deconstruction item.
cancel_deconstruct_area{surface=…, force=…, area=…, skip_fog_of_war?=…, by_player?=…, super_forced?=…} |  | Cancel deconstruct the given area with this deconstruction item.
Cancel deconstruct the given area with this deconstruction item.
clear_deconstruction_item() |  | Clears all settings/filters on this deconstruction item resetting it to default values.
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.
Clears all settings/filters on this upgrade item 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. [...]
is_blueprint | :: R boolean | If this is a blueprint item.
If this is a blueprint item.
is_blueprint_book | :: R boolean | If this is a blueprint book item.
If this is a blueprint book item.
is_item_with_label | :: R boolean | If this is an item with label item.
If this is an item with label item.
is_item_with_inventory | :: R boolean | If this is an item with inventory item.
If this is an item with inventory item.
is_item_with_entity_data | :: R boolean | If this is an item with entity data item.
If this is an item with entity data item.
is_selection_tool | :: R boolean | If this is a selection tool item.
If this is a selection tool item.
is_item_with_tags | :: R boolean | If this is an item with tags item.
If this is an item with tags item.
is_deconstruction_item | :: R boolean | If this is a deconstruction tool item.
If this is a deconstruction tool item.
is_upgrade_item | :: R boolean | If this is a upgrade item.
If this is a upgrade item.
is_tool | :: R boolean | If this is a tool item.
If this is a tool item.
is_ammo | :: R boolean | If this is an ammo item.
If this is an ammo item.
is_armor | :: R boolean | If this is an armor item.
If this is an armor item.
is_repair_tool | :: R boolean | If this is a repair tool item.
If this is a repair tool item.
item_number | :: R uint64? | The unique identifier for this item, if any. [...]
The unique identifier for this item, if any. [...]
preview_icons | :: RW array[BlueprintSignalIcon]? | Icons of this blueprint item, blueprint book, deconstruction item or upgrade planner. [...]
Icons of this blueprint item, blueprint book, deconstruction item or upgrade planner. [...]
grid | :: R LuaEquipmentGrid? | The equipment grid of this item, if any.
The equipment grid of this item, if any.
owner_location | :: R ItemLocationData | The location of this item if it can be found.
The location of this item if it can be found.
blueprint_snap_to_grid | :: RW TilePosition? | The snapping grid size in this blueprint item. [...]
The snapping grid size in this blueprint item. [...]
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 item.
If absolute snapping is enabled on this blueprint item.
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 item.
The default icons for a blueprint item.
active_index | :: RW uint32? | The active blueprint index for this blueprint book. [...]
The active blueprint index for this blueprint book. [...]
label | :: RW string? | The current label for this item, if any.
The current label for this item, if any.
label_color | :: RW Color? | The current label color for this item, if any.
The current label color for this item, if any.
allow_manual_label_change | :: RW boolean | Whether the label for this item can be manually changed. [...]
Whether the label for this item can be manually changed. [...]
entity_label | :: RW string? | If this is an item with entity data, get the stored entity label.
If this is an item with entity data, get the stored entity label.
entity_color | :: RW Color? | If this is an item with entity data, get the stored entity color.
If this is an item with entity data, get the stored entity color.
entity_logistic_sections | :: RW LogisticSections | If this is an item with entity data, get the stored logistic filters.
If this is an item with entity data, get the stored logistic filters.
entity_request_from_buffers | :: RW boolean | If this is an item with entity data, get the stored request from buffer state.
If this is an item with entity data, get the stored request from buffer state.
entity_logistics_enabled | :: RW boolean | If this is an item with entity data, get the stored vehicle logistics enabled state.
If this is an item with entity data, get the stored vehicle logistics enabled state.
entity_enable_logistics_while_moving | :: RW boolean | If this is an item with entity data, get the stored enable logistics while moving state.
If this is an item with entity data, get the stored enable logistics while moving state.
entity_driver_is_gunner | :: RW boolean | If this is an item with entity data, get the stored driver is gunner state.
If this is an item with entity data, get the stored driver is gunner state.
entity_auto_target_without_gunner | :: RW boolean | If this is an item with entity data, get the stored auto target without gunner state.
If this is an item with entity data, get the stored auto target without gunner state.
entity_auto_target_with_gunner | :: RW boolean | If this is an item with entity data, get the stored auto target with gunner state.
If this is an item with entity data, get the stored auto target with gunner state.
tags | :: RW Tags |
custom_description | :: RW LocalisedString | The custom description this item-with-tags. [...]
The custom description this item-with-tags. [...]
entity_filter_count | :: R uint32 | The number of entity filters this deconstruction item supports.
The number of entity filters this deconstruction item supports.
entity_filters | :: RW array[ItemFilter] | The entity filters for this deconstruction item. [...]
The entity filters for this deconstruction item. [...]
tile_filter_count | :: R uint32 | The number of tile filters this deconstruction item supports.
The number of tile filters this deconstruction item supports.
tile_filters | :: RW array[TileID] | The tile filters for this deconstruction item. [...]
The tile filters for this deconstruction item. [...]
entity_filter_mode | :: RW defines.deconstruction_item.entity_filter_mode | The blacklist/whitelist entity filter mode for this deconstruction item.
The blacklist/whitelist entity filter mode for this deconstruction item.
tile_filter_mode | :: RW defines.deconstruction_item.tile_filter_mode | The blacklist/whitelist tile filter mode for this deconstruction item.
The blacklist/whitelist tile filter mode for this deconstruction item.
tile_selection_mode | :: RW defines.deconstruction_item.tile_selection_mode | The tile selection mode for this deconstruction item.
The tile selection mode for this deconstruction item.
trees_and_rocks_only | :: RW boolean | If this deconstruction item is set to allow trees and rocks only.
If this deconstruction item is set to allow trees and rocks only.
mapper_count | :: R uint32 | The current count of mappers in the upgrade item.
The current count of mappers in the upgrade item.
durability | :: RW double | Durability of the contained item. [...]
Durability of the contained item. [...]
ammo | :: RW uint32 | Number of bullets left in the magazine.
Number of bullets left in the magazine.

## Methods

### add_ammo(amount)

Add ammo to this ammo item.

#### Parameters

amount | :: float | Amount of ammo to add.
Amount of ammo to add.

Can only be used if this is AmmoItem

### drain_ammo(amount)

Remove ammo from this ammo item.

#### Parameters

amount | :: float | Amount of ammo to remove.
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.
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.
Amount of durability to remove.

Can only be used if this is ToolItem

### use_capsule(entity, target_position) → array[LuaEntity]

Use the capsule item with the entity as the source, targeting the given position.

#### Parameters

entity | :: LuaEntity | The entity to use the capsule item with.
The entity to use the capsule item with.
target_position | :: MapPosition | The position to use the capsule item with.
The position to use the capsule item with.

#### Return values

→ array[LuaEntity] | Array of the entities that were created by the capsule action.

### can_set_stack(stack?) → boolean

Would a call to LuaItemStack::set_stack succeed?

#### Parameters

stack | :: ItemStackIdentification? | Stack that would be set, possibly `nil`.
Stack that would be set, possibly `nil`.

### set_stack(stack?) → boolean

Set this item stack to another item stack.

#### Parameters

stack | :: ItemStackIdentification? | Item stack to set it to. Omitting this parameter or passing `nil` will clear this item stack, as if LuaItemStack::clear was called.
Item stack to set it to. Omitting this parameter or passing `nil` will clear this item stack, as if LuaItemStack::clear was called.

#### Return values

→ boolean | Whether the stack was set successfully. Returns `false` if this stack was not valid for write.

### transfer_stack(stack, amount?) → boolean

Transfers the given item stack into this item stack.

#### Parameters

stack | :: ItemStackIdentification |
amount | :: uint32? |

#### Return values

→ boolean | `true` if the full stack (or requested amount) was transferred.

### export_stack() → string

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

#### Return values

→ string | The exported string

### import_stack(data) → int32

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

#### Parameters

data | :: string | The string to import
The string to import

#### Return values

→ int32 | 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 values

→ boolean | Whether the 2 stacks were swapped successfully.

### clear()

Clear this item stack.

### create_grid() → LuaEquipmentGrid

Creates the equipment grid for this item if it doesn't exist and this is an item-with-entity-data that supports equipment grids.

Can only be used if this is ItemWithEntityData

### spoil()

Spoils this item if the item can spoil.

## Attributes

### valid_for_read :: Read boolean

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 :: Read LuaItemPrototype

Prototype of the item held in this stack.

### name :: Read string

Prototype name of the item held in this stack.

### type :: Read string

Type of the item prototype.

### count :: Read|Write uint32

Number of items in this stack.

### health :: Read|Write float

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

### quality :: Read LuaQualityPrototype

The quality of this item.

### spoil_tick :: Read|Write MapTick

The tick this item spoils, or `0` if it does not spoil. When writing, setting to anything < the current game tick will spoil the item instantly.

### spoil_percent :: Read|Write double

The percent spoiled this item is if it spoils. `0` in the case of the item not spoiling.

### item :: Read LuaItem?

If the item has additional data, returns LuaItem pointing at the extra data, otherwise returns nil.

### is_module :: Read boolean

If this is a module

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

- LuaBootstrap::raise_player_crafted_item()
- LuaControl::opened
- LuaControl::cursor_stack
- LuaEntity::stack
- LuaEntity::held_stack
- LuaEquipmentGrid::itemstack_owner
- LuaInventory::find_item_stack()
- LuaInventory::find_empty_stack()
- LuaItem::item_stack
- LuaItemStack::swap_stack()
- LuaPlayer::set_quick_bar_slot()
- LuaPlayer::add_to_clipboard()
- LuaPlayer::blueprint_to_setup
- LuaSurface::create_entity()
- LuaSurface::deconstruct_area()
- LuaSurface::cancel_deconstruct_area()
- LuaSurface::upgrade_area()
- LuaSurface::cancel_upgrade_area()
- DetailedItemOnLine
- ItemID
- ItemStackIdentification
- ItemWithQualityID
- on_gui_closed
- on_gui_opened
- on_player_crafted_item
- on_player_deconstructed_area
- on_player_setup_blueprint
- on_robot_built_entity
- on_space_platform_built_entity