Skip to content

Inventory Meta

All documented inventory metatable methods discovered across framework and module source files.

Documented methods: 30  ·  Realm: server, shared

Methods

inventory:__tostring()

Returns a human-readable string representation of the inventory.

Format: "Inventory [id]". Useful for debug output and logging.

Realm: shared

Returns

  • string: A formatted string identifying this inventory.

Source: gamemode/framework/meta/sh_inventory.lua:19

inventory:AddItem(class, data, callback)

Adds a new item of the given class to this inventory and persists it to the database.

Validates that class exists in ax.item.stored and passes CanStoreItem before proceeding. For temporary or no-save inventories (self.isTemporary or self.noSave), the item is created in memory only with a negative auto-decrementing ID and is never written to the database. For persistent inventories, an INSERT query is issued to ax_items; the callback is invoked with the new item instance once the query completes. On success, broadcasts "inventory.item.add" to all receivers.

Returns false and a reason string on validation failure.

Realm: server

Parameters

Name Type Description
class string The item class name to instantiate (must exist in ax.item.stored).
data table\|nil Initial item data to store in itemObject.data. Defaults to {}.
callback function\|nil Called as callback(itemObject) after the item is created.

Returns

  • boolean|nil: False on validation failure; nil on async DB path (result via callback).
  • string|nil: A human-readable reason string when returning false.

Source: gamemode/framework/meta/sh_inventory.lua:500

inventory:AddReceiver(receiver)

Registers a player (or table of players) to receive network updates for this inventory.

When receiver is a table, iterates it in reverse order and adds each player individually, validating each entry via ax.util:IsValidPlayer. When receiver is a single player, it is resolved through ax.util:FindPlayer first. Duplicate entries are silently rejected (idempotent). On the server, broadcasts an "inventory.receiver.add" net message to all current receivers after each addition.

Returns false if the receiver is already registered, invalid, or cannot be resolved.

Realm: shared

Parameters

Name Type Description
receiver Player\|table A player entity or an array of player entities to add.

Returns

  • boolean: True on success, false if the receiver was already present or invalid.

Source: gamemode/framework/meta/sh_inventory.lua:363

inventory:CanItemFit(...)

Returns whether an item can occupy the given position/slot, per the inventory's type.

Grid-addressed types expect (x, y, w, h, ignoreItem); slot-addressed types expect (slotID, ignoreItem).

Realm: shared

Returns

  • boolean

Source: gamemode/framework/meta/sh_inventory.lua:149

inventory:CanStoreItem(itemClass)

Returns whether an item of the given class can be stored in this inventory.

Performs three checks in order:

  1. Validates that itemClass is registered in ax.item.stored.
  2. Checks weight capacity if itemData.weight is set (delegates to CanStoreWeight).
  3. Calls itemData:CanAddToInventory(self) if defined — returning false from that hook blocks storage regardless of weight.

Returns true on success, or false and a descriptive reason string on failure.

Called automatically by AddItem before any database operations.

Realm: shared

Parameters

Name Type Description
itemClass string The item class name to test (must exist in ax.item.stored).

Returns

  • boolean: True if the item can be stored, false otherwise.
  • string|nil: A human-readable reason string when returning false.

Source: gamemode/framework/meta/sh_inventory.lua:473

inventory:CanStoreWeight(weight)

Returns whether the given weight can be added without exceeding capacity.

Computes GetWeight() + weight and compares it against GetMaxWeight(). Returns true when the addition fits, or false and an error string when it would overflow.

Use this before manually adjusting weights; CanStoreItem already calls this internally when an item has a weight field.

Realm: shared

Parameters

Name Type Description
weight number The additional weight to test against remaining capacity.

Returns

  • boolean: True if the weight fits, false otherwise.
  • string|nil: A human-readable reason string when returning false.

Source: gamemode/framework/meta/sh_inventory.lua:451

inventory:FindEmptySlot(w, h, ignoreItem)

Finds the first free (x, y) that fits an item of the given size. Grid-addressed types only.

Realm: shared

Parameters

Name Type Description
w number -
h number -
ignoreItem table\|nil -

Returns

  • number|nil,: number|nil

Source: gamemode/framework/meta/sh_inventory.lua:162

inventory:GetData(key, default)

Returns an instance data value (e.g. grid size, slot set), or default if unset.

Instance data holds per-inventory parameters that vary within a single type (grid width/height, valid slot set) - see ax.inventory:RegisterType.

Realm: shared

Parameters

Name Type Description
key string The data key to read.
default any Fallback value when the key is unset.

Returns

  • any

Source: gamemode/framework/meta/sh_inventory.lua:94

inventory:GetHeight()

Returns the inventory's grid height, if its type supports coordinate addressing - nil otherwise.

Realm: shared

Returns

  • number|nil

Source: gamemode/framework/meta/sh_inventory.lua:127

inventory:GetID()

Returns the unique ID of this inventory.

This is the primary key from the ax_inventories table (or a negative temporary ID for in-memory-only inventories).

Realm: shared

Returns

  • number: The inventory's numeric ID.

Source: gamemode/framework/meta/sh_inventory.lua:62

inventory:GetItemAt(...)

Returns the item occupying a given position, per the inventory's type.

Addressing scheme depends on the type: grid-addressed types read this as (x, y), slot-addressed types read it as (slotID). Passed through as-is so either shape works through the same method name.

Realm: shared

Returns

  • table|nil

Source: gamemode/framework/meta/sh_inventory.lua:138

inventory:GetItemByID(itemID)

Returns the item instance with the given ID, or nil if not found.

Performs a linear search through self.items. For large inventories, consider caching the result. Returns nil when no item with that ID exists.

Realm: shared

Parameters

Name Type Description
itemID number The numeric item ID to look up.

Returns

  • table|nil: The item instance, or nil if not found.

Source: gamemode/framework/meta/sh_inventory.lua:225

inventory:GetItemCount(itemID)

Counts items in the inventory matching an ID or class name.

When itemID is a number, counts items whose key matches that ID (0 or 1).

When itemID is a string, counts all items whose class field matches it (useful for stackable or multi-instance items sharing the same class).

Realm: shared

Parameters

Name Type Description
itemID number\|string The item ID (number) or class name (string) to count.

Returns

  • number: The number of matching items.

Source: gamemode/framework/meta/sh_inventory.lua:241

inventory:GetItems()

Returns the items table for this inventory.

The returned table is keyed by item ID (number) and valued by item instance tables. Returns an empty table when the inventory has no items loaded.

Realm: shared

Returns

  • table: The { [itemID] = itemObject } items table.

Source: gamemode/framework/meta/sh_inventory.lua:173

inventory:GetItemsByBase(baseName, includeInactive)

Returns all items in the inventory that match a given base class name.

Checks each item's registered class entry in ax.item.stored for either a base field or class field matching baseName. When includeInactive is explicitly false, items with data.inactive == true are excluded.

Returns an empty table when no matches are found or baseName is invalid.

Realm: shared

Parameters

Name Type Description
baseName string The base class name to filter by.
includeInactive boolean\|nil When false, inactive items are excluded. Defaults to including all items regardless of active state.

Returns

  • table: An ordered array of matching item instances.

Source: gamemode/framework/meta/sh_inventory.lua:184

inventory:GetMaxWeight()

Returns the maximum weight capacity of this inventory.

This is the value set when the inventory was created or loaded.

Items cannot be added when GetWeight() + item.weight > GetMaxWeight().

Realm: shared

Returns

  • number: The maximum weight this inventory can hold.

Source: gamemode/framework/meta/sh_inventory.lua:28

inventory:GetOwner()

Returns the object that owns this inventory - a character, item, or entity, depending on

GetOwnerKind().

Resolves ownerKind/ownerID (set for any inventory created with owner = ..., e.g.

character_grid/character_equipment, a bag item's inventory) via

ax.inventory:ResolveOwnerObject, which dispatches to the resolveOwner callback of

whichever resolver registered that kind (see ax.inventory:RegisterOwnerResolver). Falls

back to searching for a character whose legacy vars.inventory matches this inventory's ID,

for inventories created before ownership columns existed. Returns nil if no owner can be

resolved (e.g. unassigned/temporary inventories, or an owner kind with no resolveOwner

callback registered, e.g. some "entity" resolvers).

Realm: shared

Returns

  • table|nil: The owner object, or nil if not found.

Source: gamemode/framework/meta/sh_inventory.lua:274

inventory:GetOwnerID()

Returns the owner id of this inventory. Meaning depends on GetOwnerKind().

Realm: shared

Returns

  • number|nil

Source: gamemode/framework/meta/sh_inventory.lua:84

inventory:GetOwnerKind()

Returns the owner kind of this inventory ("character" / "entity" / "item"), or nil if unset (e.g. legacy weight inventories created before ownership columns existed).

Realm: shared

Returns

  • string|nil

Source: gamemode/framework/meta/sh_inventory.lua:77

inventory:GetReceivers()

Returns the list of players who receive inventory network updates.

Receivers are players who should be notified of item additions, removals, and data changes (e.g. the character owner and any observers). Returns an empty table when no receivers have been registered.

Realm: shared

Returns

  • table: An ordered array of player entities.

Source: gamemode/framework/meta/sh_inventory.lua:258

inventory:GetTypeID()

Returns this inventory's registered type id.

Inventories with no typeID set default to "weight" (see ax.inventory:GetType), matching pre-registry behaviour.

Realm: shared

Returns

  • string: The type id.

Source: gamemode/framework/meta/sh_inventory.lua:70

inventory:GetWeight()

Calculates and returns the total weight of all items currently in the inventory.

Iterates self.items and sums the weight of each item by calling item:GetWeight() if it exists, otherwise reading item.weight directly.

Only positive weight values are counted; items with no weight or negative weight contribute 0. Returns 0 for an empty inventory.

Realm: shared

Returns

  • number: The total weight of all items in the inventory.

Source: gamemode/framework/meta/sh_inventory.lua:37

inventory:GetWidth()

Returns the inventory's grid width, if its type supports coordinate addressing - nil otherwise.

Realm: shared

Returns

  • number|nil

Source: gamemode/framework/meta/sh_inventory.lua:117

inventory:HasItem(identifier)

Returns the first item matching the given ID or class name, or false if none found.

Accepts either a numeric item ID (matches the inventory key directly) or a string class name (matches item.class on each entry). Returns the item instance table on success so callers can immediately act on it without a second lookup. Returns false when no item matches, making it safe to use in boolean conditions.

Realm: shared

Parameters

Name Type Description
identifier number\|string The item ID (number) or class name (string) to find.

Returns

  • table|false: The matching item instance, or false if not found.

Usage

if ( inventory:HasItem("weapon_pistol") ) then ... end

local item = inventory:HasItem(42)

Source: gamemode/framework/meta/sh_inventory.lua:296

inventory:HasItemOfBase(baseName)

Returns the first item whose class matches the given base name, or false if none found.

Checks each item's registered class entry in ax.item.stored for either a base field or class field equal to baseName. Unlike GetItemsByBase, this stops at the first match and is intended for simple existence checks rather than collecting all matches. Returns false immediately when baseName is empty or non-string.

Realm: shared

Parameters

Name Type Description
baseName string The base class name to check against.

Returns

  • table|false: The first matching item instance, or false if none found.

Usage

if ( inventory:HasItemOfBase("base_weapon") ) then ... end

Source: gamemode/framework/meta/sh_inventory.lua:314

inventory:IsReceiver(client)

Returns whether the given player is registered as a receiver for this inventory.

If self.receivers has not been initialised, it is created and the owning character's player is automatically added as the first receiver before the check runs. This lazy-init behaviour ensures that the owner always receives updates even if AddReceiver was never called explicitly. Returns true if client is found in the receivers list, false otherwise.

Realm: shared

Parameters

Name Type Description
client Player The player entity to test.

Returns

  • boolean: True if client is in the receiver list.

Source: gamemode/framework/meta/sh_inventory.lua:335

inventory:RemoveItem(itemID)

Removes an item from this inventory by ID or class name and deletes it from the database.

When itemID is a string class name, the first matching item's numeric ID is resolved before removal. For temporary or no-save inventories (or items flagged as such), the item is removed from self.items and ax.item.instances immediately with no database call. For persistent items, a DELETE query is issued to ax_items and, on success, broadcasts "inventory.item.remove" to all receivers and removes the item from in-memory tables. Returns false when no matching item is found.

Realm: server

Parameters

Name Type Description
itemID number\|string The numeric item ID or string class name to remove.

Returns

  • boolean: True on success (or async DB path), false if the item was not found.

Source: gamemode/framework/meta/sh_inventory.lua:613

inventory:RemoveReceiver(receiver)

Removes a single player from the inventory's receiver list.

Searches the receivers array for receiver and removes it. On the server, broadcasts an "inventory.receiver.remove" net message to all remaining receivers before removing the entry. Returns false if the receivers list is empty or receiver is not found; returns true on successful removal.

Realm: shared

Parameters

Name Type Description
receiver Player The player entity to remove from the receiver list.

Returns

  • boolean: True on successful removal, false if not found.

Source: gamemode/framework/meta/sh_inventory.lua:407

inventory:RemoveReceivers()

Removes all players from the inventory's receiver list.

On the server, broadcasts an "inventory.receiver.remove" net message for each current receiver before clearing the list. After the call self.receivers is reset to an empty table. Returns false immediately if the list is already empty; returns true after a successful clear.

Realm: shared

Returns

  • boolean: True after clearing, false if the list was already empty.

Source: gamemode/framework/meta/sh_inventory.lua:430

inventory:SetData(key, value)

Sets an instance data value. Not persisted automatically - callers that need

durability write the inventory row back to the database.

Realm: shared

Parameters

Name Type Description
key string -
value any -

Source: gamemode/framework/meta/sh_inventory.lua:108