Server Exports

Call these exports from server scripts.

local inventory = exports['tss-inventory']

Arguments and returns

• playerSource: player server ID.
• inventoryId: inventory ID, such as player_ABC123.
• target: player server ID or inventory ID.
• itemId / slot: an item stack's ID, not a grid position.
• ?: optional argument.
• Weights use grams.
• Grid coordinates start at 1.

Most changes return true or false, errorMessage.

Creation generally returns true, inventory or false, errorMessage.

Getters return copies. Load the character before calling player inventory exports.

Find inventories

Create and open inventories

Container options include:

{
    inventoryId = 'business_storage',
    label = 'Storage',
    size = { x = 8, y = 6 },
    metadata = {},
    playerSource = playerSource,
}

Additional options include owner, coords, whitelist, blacklist and maxWeight.

owner is a character ID. playerSource can resolve the owner through the bridge.

Coordinates alone do not create a target or ped. Authorise access in the calling script before opening custom storage.

local created, container = inventory:CreateContainer('stash', {
    inventoryId = 'business_storage',
    label = 'Storage',
    size = { x = 8, y = 6 },
    playerSource = playerSource,
})

if created then
    inventory:OpenInventory(playerSource, container.id)
end

DeleteContainer excludes player inventories, shops, drops and extra slots.

Temporary loot

local created, container = inventory:CreateContainer('loot', {
    label = 'Loot',
    size = { x = 8 },

    items = {
        plastic = {
            amount = { min = 1, max = 5 },
            chance = 100,
        },

        bandage = {
            amount = 2,
            chance = 30,
        },
    },

    maxItems = { min = 1, max = 2 },
    deleteOnEmpty = true,
    playerSource = playerSource,
})

if created then
    inventory:OpenInventory(playerSource, container.id)
end

• Omit inventoryId to generate a unique ID.
• amount accepts a number or {min, max}.
• chance is a percentage.
• maxItems caps selected item types, not total item quantity.
• Chances are independent; a roll may contain fewer types than the cap.
• An empty roll can return false, 'Loot roll produced no items'.
• Omit size.y to calculate the required rows.
• Existing IDs are not rerolled.
• Loot contents never save to the database.
• deleteOnEmpty = true removes the container after its last item is taken.

For item-backed loot, deleteOnEmpty also removes the linked item when emptied. Already-opened loot items do not reroll after a restart.

Change inventories

Resizing fails if the contents cannot fit.

Player and extra-slot ownership cannot be reassigned.

Do not manually change container link fields such as containerId or containerItem.

Check and find items

inventory:HasItem(playerSource, 'bandage', 2)

inventory:HasItems(playerSource, {
    bandage = 2,
    water_bottle = 1,
})

Player HasItem/HasItems checks include the main inventory and enabled extra slots. They do not search nested containers.

Pass a specific inventory ID to check only that inventory.

Item getters provide slot and info as equivalents of id and metadata.

Add, remove and move items

Automatic placement:

inventory:AddItem(playerSource, 'water_bottle', 2, false, {
    quality = 100,
})

Remove by name:

inventory:RemoveItem(playerSource, 'water_bottle', 1, false)

Use an inventory ID and request an item notification:

inventory:AddItem(inventoryId, 'bandage', 1, {}, true)
inventory:RemoveItem(inventoryId, itemId, 1, true)

For inventory-ID forms, notification accepts:

• true to notify the owning player for their own or extra inventory.
• A player server ID to notify that player.
• false or omission for no notification.

A supplied slot must be an existing matching stack. It is not an empty grid cell.

For RemoveItemsByName, a table filter matches supplied metadata fields. A string filter matches metadata.type.

For GetItemCount, exactMetadata must match the complete metadata object.

Using info or metadata as the SetItemData key replaces all metadata.

Labels

inventory:SetItemLabel(inventoryId, itemId, "Jack's Box")
inventory:SetInventoryLabel(inventoryId, "Jack's Storage")

Custom labels are stored in metadata.label and persist when moved or saved.

Labels must be nonempty text up to 100 bytes. Pass false to remove a custom label.

An item ID identifies a stack. Split a stack first to rename just one unit.

A container item's label and its inventory window title are separate.

Usable items

Callbacks receive (playerSource, item, inventoryId).

inventory:CreateUsableItem('bandage', function(playerSource, item, inventoryId)
    if not inventory:RemoveItem(inventoryId, item.id, 1) then
        return
    end

    -- Apply the effect here.
end)

Callbacks do not consume items automatically.

With Config.UseItemsFromContainers = true, use the callback's inventory ID to remove the selected item from its carried container.

Start registering scripts after the inventory, and restart them after restarting it.

A framework function forwarding registrations should pass GetInvokingResource() as ownerResource.

Weight and slots

Multi-cell items occupy multiple cells.

Dynamic container weight includes carried contents where applicable.

Shops

CreateShop accepts:

{
    name = 'trade_counter',
    label = 'Trade Counter',
    coords = vector4(24.47, -1346.62, 28.50, 266.0),
    size = { x = 8 },

    items = {
        {
            name = 'plastic',
            buyPrice = 5,
            sellPrice = 2,
            amount = 100,
        },
    },
}

Coordinates are required. Product names must be unique.

Products support buyPrice, sellPrice, buy, sell, amount and metadata. Legacy price, count and info are also accepted.

Shop height is calculated automatically, with a minimum of two rows. Use amount = false for unlimited stock.

World drops

CreateDrop requires coordinates and an item list:

inventory:CreateDrop({
    coords = { x = 24.47, y = -1346.62, z = 28.5 },

    items = {
        {
            name = 'bandage',
            amount = 2,
            metadata = {},
        },
    },
})

Optional fields include size, label, metadata and bucket.

World drops never save to the database.

When world drops are disabled, DropItem deletes the items instead.

Extra inventories

Definitions accept label, size, metadata, whitelist, blacklist and maxWeight.

inventory:CreateExtraInventory(playerSource, 'wallet_slot', {
    label = 'Wallet',
    size = { x = 1, y = 1 },
    whitelist = { 'wallet' },
})

Use the returned inventory ID with normal item exports.

Slot names allow 1–64 letters, numbers, underscores or hyphens. Each character can have up to 32 definitions.

Window settings

Settings use:

{
    x = 100,
    y = 100,
    dock = false,
    minimised = false,
    active = true,
}

Dock positions:

• left-top
• left-bottom
• right-top
• right-bottom
• top-left
• top-right
• bottom-left
• bottom-right

Item notifications

inventory:ItemBox(playerSource, 'bandage', 'added', 1)
inventory:ItemBox(playerSource, 'bandage', 'removed', 1)

Notifications do not add or remove items.

Players control their visibility, duration and position through /inventorysettings.

Weapons

Requires Config.EnableWeaponSystem = true.

Use UseItem to equip or toggle a carried weapon.

Loaded ammunition is stored in metadata.ammo. Installed attachments are stored in metadata.attachments.

Clothing

These exports are registered when Config.EnableClothingSystem = true.

local clothing = inventory:GetEquippedClothing(playerSource)

local success, errorMessage = inventory:EquipClothing(
    playerSource,
    inventoryId,
    itemId
)

local success, errorMessage = inventory:UnequipClothing(
    playerSource,
    'top'
)

clothing.inventory.items contains worn items. clothing.slots lists equipment slots.

Replaced or unequipped clothing returns to the main inventory. Changes fail if the returned item cannot fit.

Cash items

With Config.MoneyAsItem = true, carried cash items synchronise with the player's cash account.

This includes enabled extra slots and linked nested containers.

Moving cash within carried storage does not change the balance. Moving cash or a funded container outside carried storage debits it; moving it back credits it.

Use one cash operation in payment scripts. Synchronisation handles the matching account or item change.

Cash edits to offline player inventories are refused.

Unsupported QB calls

Use GetPlayerInventory instead of LoadInventory.

TSS saves changes automatically, so SaveInventory is not required.

SetInventory, RemoveInventory, OpenInventoryById and QB hook/listener exports are not provided.