Skip to content

ax.inventory

Inventory management system for creating, storing, and retrieving inventory data.

Documented functions: 15  ·  Realm: server, shared

Functions

ax.inventory:CanAccess(inventory, client)

Whether client may modify (not merely view/receive sync for) inventory, per the

core's one built-in rule (an owner-character may modify their own inventories) plus

the inventory type's own CanAccess rule (distance, locks, faction/rank, ...).

Called by ax.item:Transfer on both transfer endpoints. Receiver/sync visibility is

a separate concept and does not go through this.

Realm: shared

Parameters

Name Type Description
inventory table -
client Player -

Returns

  • boolean

Source: gamemode/framework/libraries/sh_inventory.lua:133

ax.inventory:Create(data, callback)

Creates a new inventory in the database and returns the inventory object via callback.

Back-compat: called with no typeID/owner (or data at all), this creates

exactly the weight-limited, ownerless inventory ax.inventory:Create has always

created. typeID/owner/instance data are additive - existing callers are

unaffected.

Realm: server

Parameters

Name Type Description
data table Optional data table. Recognised keys: maxWeight, typeID (defaults to SCHEMA.defaultInventoryType, itself "weight" unless the schema sets it - see ax.inventory:GetDefaultType), owner (a character/item/entity object - resolved via ax.inventory:ResolveOwner, never pass a raw owner_kind string), data (instance data - grid size, slot set - stored on the inventory, see GetData).
callback function\|nil Optional callback function called with the created inventory or false on failure.

Source: gamemode/framework/libraries/sh_inventory.lua:310

ax.inventory:CreateTemporary(data, callback)

Creates a temporary in-memory inventory instance (no database persistence).

Realm: server

Parameters

Name Type Description
data table Optional data table. Recognised keys: id, maxWeight, typeID (defaults to "weight"), owner (resolved via ax.inventory:ResolveOwner), data (instance data).
callback function\|nil Optional callback function called with the created inventory.

Source: gamemode/framework/libraries/sh_inventory.lua:239

ax.inventory:GetDefaultType()

Returns the inventory type (and its instance data) new inventories are created with when

ax.inventory:Create/CreateTemporary is called without an explicit typeID - e.g. a

character's primary inventory (vars.inventory, created via `ax.inventory:Create({ owner =

character })). ReadsSCHEMA.defaultInventoryType/SCHEMA.defaultInventoryData` - declare

these once in schema/boot.lua, the same convention as SCHEMA.name/SCHEMA.author - falling

back to "weight"/{} if the schema never sets them, so schemas that never opt in see zero

behaviour change.

Realm: shared

Returns

  • string: typeID
  • table: data Instance data (e.g. { width = 8, height = 6 }), may include maxWeight. Falls back to "weight" with a warning if SCHEMA.defaultInventoryType names a type that was never registered via ax.inventory:RegisterType (e.g. a typo, or the registering file hasn't loaded yet) - never silently creates inventories of a type that doesn't exist.

Usage

-- schema/boot.lua

SCHEMA.defaultInventoryType = "character_grid"

SCHEMA.defaultInventoryData = { width = 8, height = 6 }

Source: gamemode/framework/libraries/sh_inventory.lua:218

ax.inventory:ItemOwnsInventory(itemID)

Whether itemID owns an inventory (e.g. a bag/container item) - i.e. some

inventory instance has ownerKind == "item" and ownerID == itemID. Used by

ax.item:Transfer to enforce the depth-1 nesting rule: a bag can never end up

inside another inventory that is itself nested inside an item.

O(1) via itemOwnerIndex instead of scanning every live inventory - this is

called on every Transfer into an item-owned inventory, so its cost must not

scale with how many inventories exist on the server.

Realm: shared

Parameters

Name Type Description
itemID number -

Returns

  • boolean

Source: gamemode/framework/libraries/sh_inventory.lua:171

ax.inventory:RegisterOwnerResolver(def)

Registers an owner resolver.

Realm: shared

Parameters

Name Type Description
def table { kind = string, checkOwner = function(owner) -> boolean, getOwner = function(owner) -> number, resolveOwner = function(ownerID) -> any }. kind is the owner_kind string this resolver produces (e.g. "character", "item", "entity"); checkOwner recognises whether a value is this kind of owner; getOwner extracts the stable id to persist as owner_id. For entity owners this must be a persistent id (survives a restart), never Entity:EntIndex(). resolveOwner is the inverse - given that id, returns the live owner object again (or nil if it isn't loaded) - it powers inventory:GetOwner(). Optional: omitting it just means GetOwner() can't resolve that kind back to an object.

Source: gamemode/framework/libraries/sh_inventory.lua:41

ax.inventory:ResolveOwner(owner)

Resolves an owner object to its (ownerKind, ownerID) pair via the registered

resolvers. Passing nil is valid and yields nil, nil (an ownerless/legacy

inventory - back-compat for code that never had an owner concept).

Realm: shared

Parameters

Name Type Description
owner any A character, item, entity, or anything a registered resolver recognises.

Returns

  • string|nil: ownerKind
  • number|nil: ownerID

Usage

local kind, id = ax.inventory:ResolveOwner(character) -- "character", character:GetID()

Source: gamemode/framework/libraries/sh_inventory.lua:76

ax.inventory:ResolveOwnerObject(ownerKind, ownerID)

Resolves an (ownerKind, ownerID) pair back to the live owner object, via the

resolveOwner callback of the resolver registered for ownerKind - the inverse of

ResolveOwner. Returns nil if ownerKind is nil, unregistered, or its resolver didn't

provide a resolveOwner callback (e.g. some "entity" resolvers, where the owner may

no longer exist in the world).

Realm: shared

Parameters

Name Type Description
ownerKind string\|nil -
ownerID number\|nil -

Returns

  • any|nil: The owner object, or nil if it can't be resolved.

Source: gamemode/framework/libraries/sh_inventory.lua:59

ax.inventory:Restore(client, callback)

Restores all inventories associated with the client's characters from the database.

Realm: server

Parameters

Name Type Description
client Player The player whose inventories should be restored.

Usage

ax.inventory:Restore(client)

Source: gamemode/framework/libraries/sh_inventory.lua:669

ax.inventory:RestoreOwner(owner, callback)

Restores every inventory owned by owner from the database, items included. A

character has as many owned inventories as it was created with (main grid,

equipment, ...) - this is how they're all found again on load, regardless of how

many there are or what types they are.

Realm: server

Parameters

Name Type Description
owner any A character/item/entity object - resolved via ax.inventory:ResolveOwner.
callback function\|nil Called with an array of restored inventories (possibly empty).

Source: gamemode/framework/libraries/sh_inventory.lua:365

ax.inventory:RestoreRow(row, callback)

Restores a single ax_inventories row (plus its items) into a live inventory

instance. Shared by RestoreOwner/Restore so the row-to-instance shape

(type/owner/data columns, item placement columns) is defined once.

Realm: server

Parameters

Name Type Description
row table A row from ax_inventories (as returned by the mysql library).
callback function Called with the restored inventory instance, or false if the item fetch failed - always called exactly once so callers that count down across multiple rows (e.g. RestoreOwner) can rely on it, success or failure.

Source: gamemode/framework/libraries/sh_inventory.lua:465

ax.inventory:RestoreRows(rows, callback)

Batch-restores multiple ax_inventories rows (plus their items) using a single

WhereIn items query instead of one items query per row. Used by Restore to

load every inventory owned by any of a client's characters without the query

count scaling with the number of inventories found.

Realm: server

Parameters

Name Type Description
rows table Array of ax_inventories rows (as returned by the mysql library).
callback function\|nil Called once with an array of restored inventory instances (order not guaranteed to match rows). Already-live instances are resolved instantly and included without issuing any query for them.

Source: gamemode/framework/libraries/sh_inventory.lua:505

ax.inventory:Sync(inventory)

Synchronizes the specified inventory with all clients.

Realm: server

Parameters

Name Type Description
inventory table\|number The inventory table or inventory ID to sync.

Usage

ax.inventory:Sync(inventory)

Source: gamemode/framework/libraries/sh_inventory.lua:615

ax.inventory:GetType(inventory)

Returns the registered type definition for an inventory instance.

Inventories created before the type registry existed (or by code that never set

typeID) default to "weight" for back-compat - the same weight-limited-list

behaviour ax.inventory has always had.

Realm: shared

Parameters

Name Type Description
inventory table The inventory instance

Returns

  • table|nil: The type definition, or nil if the inventory's typeID is set but unregistered

Source: gamemode/framework/libraries/sh_inventory_types.lua:45

ax.inventory:RegisterType(id, data)

Registers an inventory type definition.

A type defines how items are addressed within an inventory (grid x,y, named

slotID, or no addressing at all) plus optional access rules and a UI renderer

id. Concrete types register themselves from their own schema/module, reusing the

shared ax.inventory.gridBehavior/ax.inventory.slotBehavior primitives as-is or

merged with their own CanReceiveItem/CanRemoveItem rules.

Realm: shared

Parameters

Name Type Description
id string Unique type identifier (e.g. "weight", "bag", "equipment")
data table Type definition. Recognised keys: GetWidth, GetHeight, GetItemAt, CanItemFit, FindEmptySlot (grid-capable types only), CanReceiveItem, CanRemoveItem. Addressing is optional - a type with none of these keys is a non-addressed type (e.g. the default weight type below), and placement validation is simply skipped for it.

Source: gamemode/framework/libraries/sh_inventory_types.lua:34