Skip to content

meta/sh_inventory

Source: gamemode/framework/meta/sh_inventory.lua

Returns a human-readable string representation of the inventory.

Documented functions: 20

Functions

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

inventory:GetOwner()

Returns the character that owns this inventory.

Searches all loaded character instances in ax.character.instances for one whose vars.inventory matches this inventory's ID. Returns the first match, or nil if no character claims this inventory (e.g. unassigned or temporary inventories).

Realm: shared

Returns

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

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.

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.

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)

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

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.

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.

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.

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.