LuaItemStack

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.

Parent

• LuaItemCommon

Attributes

valid_for_read

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

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

Prototype of the item held in this stack.

name

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

Prototype name of the item held in this stack.

type

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

Type of the item prototype.

count

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

Number of items in this stack.

health

• Read: float
• Write: float
• Optional: false

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

quality

• Read: LuaQualityPrototype
• Write: unknown
• Optional: false

The quality of this item.

spoil_tick

• Read: MapTick
• Write: MapTick
• Optional: false

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

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

item

• Read: LuaItem
• Write: unknown
• Optional: true

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

is_module

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

If this is a module

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

add_ammo

LuaItemStack.add_ammo(amount: float)

Call As

itemStack.add_ammo(amount)

Call Convention

• takes_table: false
• table_optional: false

Add ammo to this ammo item.

Parameters

• amount: float — Amount of ammo to add.

drain_ammo

LuaItemStack.drain_ammo(amount: float)

Call As

itemStack.drain_ammo(amount)

Call Convention

• takes_table: false
• table_optional: false

Remove ammo from this ammo item.

Parameters

• amount: float — Amount of ammo to remove.

add_durability

LuaItemStack.add_durability(amount: double)

Call As

itemStack.add_durability(amount)

Call Convention

• takes_table: false
• table_optional: false

Add durability to this tool item.

Parameters

• amount: double — Amount of durability to add.

drain_durability

LuaItemStack.drain_durability(amount: double)

Call As

itemStack.drain_durability(amount)

Call Convention

• takes_table: false
• table_optional: false

Remove durability from this tool item.

Parameters

• amount: double — Amount of durability to remove.

use_capsule

LuaItemStack.use_capsule(entity: LuaEntity, target_position: MapPosition) -> Array<LuaEntity>

Call As

itemStack.use_capsule(entity, target_position)

Call Convention

• takes_table: false
• table_optional: false

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.
• target_position: MapPosition — The position to use the capsule item with.

Returns

• Array<LuaEntity> — Array of the entities that were created by the capsule action.

can_set_stack

LuaItemStack.can_set_stack(stack?: ItemStackIdentification) -> boolean

Call As

itemStack.can_set_stack()

Call Convention

• takes_table: false
• table_optional: false

Would a call to LuaItemStack::set_stack succeed?

Parameters

• stack?: ItemStackIdentification — Stack that would be set, possibly nil.

Returns

• boolean

set_stack

LuaItemStack.set_stack(stack?: ItemStackIdentification) -> boolean

Call As

itemStack.set_stack()

Call Convention

• takes_table: false
• table_optional: false

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.

Returns

• boolean — Whether the stack was set successfully. Returns false if this stack was not valid for write.

transfer_stack

LuaItemStack.transfer_stack(stack: ItemStackIdentification, amount?: uint32) -> boolean

Call As

itemStack.transfer_stack(stack, amount)

Call Convention

• takes_table: false
• table_optional: false

Transfers the given item stack into this item stack.

Parameters

• stack: ItemStackIdentification
• amount?: uint32

Returns

• boolean — true if the full stack (or requested amount) was transferred.

export_stack

LuaItemStack.export_stack() -> string

Call As

itemStack.export_stack()

Call Convention

• takes_table: false
• table_optional: false

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

Returns

• string — The exported string

import_stack

LuaItemStack.import_stack(data: string) -> int32

Call As

itemStack.import_stack(data)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

• data: string — The string to import

Returns

• int32 — 0 if the import succeeded with no errors. -1 if the import succeeded with errors. 1 if the import failed.

swap_stack

LuaItemStack.swap_stack(stack: LuaItemStack) -> boolean

Call As

itemStack.swap_stack(stack)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

• stack: LuaItemStack

Returns

• boolean — Whether the 2 stacks were swapped successfully.

clear

LuaItemStack.clear()

Call As

itemStack.clear()

Call Convention

• takes_table: false
• table_optional: false

Clear this item stack.

create_grid

LuaItemStack.create_grid() -> LuaEquipmentGrid

Call As

itemStack.create_grid()

Call Convention

• takes_table: false
• table_optional: false

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

Returns

• LuaEquipmentGrid

spoil

LuaItemStack.spoil()

Call As

itemStack.spoil()

Call Convention

• takes_table: false
• table_optional: false

Spoils this item if the item can spoil.