Skip to content

tes3inventory⚓︎

An inventory composes of an iterator, and flags caching the state of the inventory.

Note

Base actor objects can have leveled items in their inventory.

Properties⚓︎

flags⚓︎

Read-only. Raw bit-based flags.

Returns:

  • result (number)

items⚓︎

Read-only. Direct acces to the container that holds the inventory's items.

Returns:

Example: An example implementation of a generic iteration function for looping over all the items in an inventory using coroutine API from the Lua standard library. 
--- This is a generic iterator function that is used
--- to loop over all the items in an inventory
---@param actor tes3actor
---@return fun(): tes3item, integer, tes3itemData|nil
local function iterItems(actor)
    local function iterator()
        for _, stack in pairs(actor.inventory) do
            local item = stack.object
            -- Skip uncarryable lights. They are hidden from the interface. A MWSE mod
            -- could make the player glow from transferring such lights, which the player
            -- can't remove. Some creatures like atronaches have uncarryable lights
            -- in their inventory to make them glow that are not supposed to be looted.
            if item.canCarry == false then
                goto continue
            end

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

            -- First yield stacks with custom data
            for _, data in pairs(stack.variables or {}) do
                coroutine.yield(item, data.count, data)
                count = count - data.count
            end

            -- Then yield all the remaining copies
            if count > 0 then
                coroutine.yield(item, count)
            end

            :: continue ::
        end
    end
    return coroutine.wrap(iterator)
end

local player = tes3.player.object --[[@as tes3actor]]
for item, count, itemData in iterItems(player) do
    debug.log(item)
    debug.log(count)
    debug.log(itemData)
end

Methods⚓︎

addItem⚓︎

Adds an item into the inventory directly. This should not be used, in favor of the tes3.addItem() function.

myObject:addItem({ mobile = ..., item = ..., itemData = ..., count = ... })

Parameters:

  • params (table)
    • mobile (tes3mobileActor, tes3reference, string): Optional. The mobile actor whose stats will be updated.
    • item (tes3item, tes3leveledItem): The item or leveled item to add. If adding a leveled item to an inventory of a cloned object (such as tes3containerInstance), the leveled list will be resolved. Otherwise the leveled item record is added to the inventory directly.
    • itemData (tes3itemData): Optional. Any associated item data to add.
    • count (number): Default: 1. The number of items to add.

calculateWeight⚓︎

Calculates the weight of all items in the container.

local result = myObject:calculateWeight()

Returns:

  • result (number)

contains⚓︎

Checks to see if the inventory contains an item.

local result = myObject:contains(item, itemData)

Parameters:

  • item (tes3item, string): The item to check for.
  • itemData (tes3itemData): Optional. If provided, it will check for the specific data as well.

Returns:

  • result (boolean)

dropItem⚓︎

Checks to see if the inventory contains an item. This should not be used, instead use the tes3.dropItem() function.

myObject:dropItem(mobile, item, itemData, count, position, orientation, ignoreItemData)

Parameters:

  • mobile (tes3mobileActor, tes3reference, string): The mobile actor whose stats will be updated.
  • item (tes3item, string): The item to drop.
  • itemData (tes3itemData): If provided, it will check for the specific data to drop it.
  • count (number): The number of items to drop.
  • position (tes3vector3): A vector determining placement location.
  • orientation (tes3vector3): A vector determining placement rotation.
  • ignoreItemData (boolean)

findItemStack⚓︎

Searches for an item stack in the inventory.

local result = myObject:findItemStack(item, itemData)

Parameters:

  • item (tes3item, string): The item to search for.
  • itemData (tes3itemData): Optional. If provided, it will check for the specific data as well.

Returns:

getItemCount⚓︎

Checks to get the number of items in the given inventory.

local count = myObject:getItemCount(item)

Parameters:

  • item (tes3item, string): The item to check for.

Returns:

  • count (number): The number of the given item in the inventory.

removeItem⚓︎

Removes an item from the inventory directly. This should not be used, in favor of the tes3.removeItem() function.

myObject:removeItem({ mobile = ..., item = ..., itemData = ..., count = ..., deleteItemData = ... })

Parameters:

  • params (table)
    • mobile (tes3mobileActor, tes3reference, string): Optional. The mobile actor whose stats will be updated.
    • item (tes3item): The item to add.
    • itemData (tes3itemData): Optional. Any associated item data to add.
    • count (number): Default: 1. The number of items to add.
    • deleteItemData (boolean): Default: false. If set, the itemData will be deleted after being removed.

resolveLeveledItems⚓︎

Resolves all contained leveled lists and adds the randomized items to the inventory. This should generally not be called directly.

myObject:resolveLeveledItems(mobile)

Parameters:

  • mobile (tes3mobileActor): Optional. The mobile actor whose stats will be updated.

updateInternalLight⚓︎

Re-evaluates whether the inventory contains a non-carriable internal light item and applies it to the given mobile actor if no active Light magic effect is present. This is useful when implementing custom light spells that can produce negative magnitudes or otherwise need vanilla-style fallback handling.

myObject:updateInternalLight(mobile)

Parameters:

  • mobile (tes3mobileActor): The mobile actor whose internal light state should be refreshed.