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

# Factorio Runtime Docs Version 2.0.77

# LuaItem - Runtime Docs

## Class LuaItem extends LuaItemCommon

A reference to an item with data. In contrast to LuaItemStack, this is binding to a specific item data even if it would move between entities or inventories.

Inherits from LuaItemCommon

## Members

type | :: R string | Type of the item prototype
Type of the item prototype
name | :: R string | Name of the item prototype
Name of the item prototype
prototype | :: R LuaItemPrototype | Item prototype of this item
Item prototype of this item
quality | :: R LuaQualityPrototype | The quality of this item.
The quality of this item.
item_stack | :: R LuaItemStack? | Object representing the item stack this item is located in right now. [...]
Object representing the item stack this item is located in right now. [...]
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.

## Attributes

### type :: Read string

Type of the item prototype

### name :: Read string

Name of the item prototype

### prototype :: Read LuaItemPrototype

Item prototype of this item

### quality :: Read LuaQualityPrototype

The quality of this item.

### item_stack :: Read LuaItemStack?

Object representing the item stack this item is located in right now. If its not possible to locate the item stack holding this item, a nil will be returned

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

- LuaItemStack::item
- ItemID
- RegistrationTarget