Custom Inventory Adapter

If your inventory is not ox_inventory, qb-inventory, or qs-inventory, fill the custom inventory adapter to normalize item operations for every Atlas resource. The shape mirrors the custom framework adapter — implement a small set of methods that return the normalized shapes, and consumers call Bridge.Inventory.* unchanged.

How it works

Select the custom inventory provider:

setr atlas:inventory "custom"

Server → editable/inventory/server.lua
Client → editable/inventory/client.lua

If your custom adapter fails to load, the bridge falls back to the _default virtual inventory so the server still boots.

Every method returns a single value — exports cross a VM boundary, so multi-return is lost.

Normalized shapes

-- a held item (one entry in an item list)
{ name = 'water', count = 3, slot = 5, metadata = {} }   -- slot/metadata only on inventories that support them

-- an item DEFINITION (not a held item)
{ name = 'water', label = 'Water', weight = 100, image = 'water.png', description = 'Refreshing.' }

Server contract

Implement these in editable/inventory/server.lua:

→ bool

required

Give the player an item. Return true on success.

→ bool

required

Take an item from the player. Return true on success.

→ bool

required

Whether the player has at least count (default 1) of the item.

→ number

required

Total quantity of the item the player holds.

→ bool

required

Whether the player can receive count of the item. Return true if your inventory has no capacity limit.

→ item[]

required

All held items as the normalized list shape.

→ itemInfo | nil

required

The item definition { name, label, weight, image, description }, or nil if unknown.

→ string

required

The inventory image URL/path for NUI rendering.

Client contract

Implement these in editable/inventory/client.lua:

→ item[]

required

The local player’s held items.

→ bool

required

Whether the local player has at least count (default 1) of the item.

Usable-item registration does not live here. It is implemented on the framework adapter’s RegisterUsable method, because most frameworks own item usage — see Usable items on the custom framework page.

Worked example

A server adapter for a fictional my_inventory:

-- editable/inventory/server.lua
-- Enable with:  setr atlas:inventory "custom"

local Inv = exports['my_inventory']

local M = {}

---@return boolean
function M.AddItem(src, item, count, metadata, slot)
    return Inv:AddItem(src, item, count or 1, metadata, slot) == true
end

---@return boolean
function M.RemoveItem(src, item, count, metadata, slot)
    return Inv:RemoveItem(src, item, count or 1, metadata, slot) == true
end

---@return boolean
function M.HasItem(src, item, count)
    return (Inv:GetItemCount(src, item) or 0) >= (count or 1)
end

---@return number
function M.GetItemCount(src, item)
    return Inv:GetItemCount(src, item) or 0
end

---@return boolean
function M.CanCarry(src, item, count)
    return Inv:CanCarryItem(src, item, count or 1) == true
end

---@return table[] items { name, count, slot?, metadata? }
function M.GetItems(src)
    local out = {}
    for _, entry in pairs(Inv:GetInventory(src) or {}) do
        out[#out + 1] = { name = entry.name, count = entry.count, slot = entry.slot, metadata = entry.metadata }
    end
    return out
end

---@param item string @return table|nil { name, label, weight, image, description }
function M.GetItemInfo(item)
    local def = Inv:GetItemData(item)
    if not def then return nil end
    return {
        name = def.name, label = def.label, weight = def.weight or 0,
        image = def.image or (item .. '.png'), description = def.description or '',
    }
end

---@param item string @return string
function M.GetImagePath(item)
    return ('nui://my_inventory/images/%s.png'):format(item)
end

return M

And the client adapter:

-- editable/inventory/client.lua
-- Enable with:  setr atlas:inventory "custom"

local Inv = exports['my_inventory']

local M = {}

---@return table[] items { name, count, slot?, metadata? }
function M.GetItems()
    local out = {}
    for _, entry in pairs(Inv:GetPlayerItems() or {}) do
        out[#out + 1] = { name = entry.name, count = entry.count, slot = entry.slot, metadata = entry.metadata }
    end
    return out
end

---@return boolean
function M.HasItem(item, count)
    return (Inv:GetItemCount(item) or 0) >= (count or 1)
end

return M

Test it

Enable

Set setr atlas:inventory "custom" and setr atlas:debug "true", then restart atlasBridge.

Confirm the adapter loaded

Look for [Inventory] server adapter: custom. If you see _default, your stub errored at load.

Round-trip an item

Add an item, confirm it appears; remove it, confirm HasItem and GetItemCount reflect the change.

​How it works

​Normalized shapes

​Server contract

​Client contract

​Worked example

​Test it

How it works

Normalized shapes

Server contract

Client contract

Worked example

Test it