Skip to content

tes3itemStack⚓︎

Item stack represents all copies of an item with the same id inside an inventory. This complex container holds a relationship between an item, and zero or more associated item datas. The itemStack.variables is a list of different itemData for each item in the stack, not a single itemData. Not every item in the stack needs to have associated itemData. The game adds itemData to items on equipping with the exception of thrown weapons and ammo.

For example, you might have five journeyman lockpicks:

  • 3 new ones (25 uses)
  • 1 with 23 uses
  • 1 with 18 uses

In this example, all of these lockpicks are represented by a single tes3itemStack object. The stack.count is 5. The #stack.variables is 2, since there are only 2 used lockpicks, with each having different itemData. The count of new lockpicks is equal to stack.count - #stack.variables.

Example: In the iterItems() function we can see that the an item stack can consist of items with itemData and items without it 
--- This is a generic iterator function that is used
--- to loop over all the items in an inventory
---@param ref tes3reference
---@return fun(): tes3item, integer, tes3itemData|nil
local function iterItems(ref)
    local function iterator()
        for _, stack in pairs(ref.object.inventory) do
            ---@cast stack tes3itemStack
            local item = stack.object

            -- Account for restocking items,
            -- since their count is negative
            local count = math.abs(stack.count)

            -- first yield stacks with custom data
            if stack.variables then
                for _, data in pairs(stack.variables) do
                    if data then
                        -- Note that data.count is always 1 for items in inventories.
                        -- That field is only relevant for items in the game world, which
                        -- are stored as references. In that case tes3itemData.count field
                        -- contains the amount of items in the in-game-world stack of items.
                        coroutine.yield(item, data.count, data)
                        count = count - data.count
                    end
                end
            end
            -- then yield all the remaining copies
            if count > 0 then
                coroutine.yield(item, count)
            end
        end
    end
    return coroutine.wrap(iterator)
end

for item, count, itemData in iterItems(tes3.player) do
    debug.log(item)
    debug.log(count)
    debug.log(itemData)
end

Properties⚓︎

count⚓︎

The total number of items in the stack.

Returns:

  • result (integer)

object⚓︎

Read-only. The core game object that the stack represents. Leveled items can only appear in inventories of base actors (tes3container, tes3creature, tes3npc) while corresponding actor instances always have leveled lists resolved.

Returns:

variables⚓︎

A collection of variables that are associated with the stack's object, or nil if there aren't any.

Returns: