Skip to content

ax.inventory

Source: gamemode/framework/libraries/sh_inventory.lua

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

Documented functions: 13

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

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.

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.

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 }

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

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.

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()

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.

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)

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).

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.

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.

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)