Skip to content

Item Meta

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

Documented methods: 30  ·  Realm: server, shared

Methods

item:__tostring()

Returns a human-readable string representation of the item.

Format: "Item [id][name][class]". Useful for debug output and logging.

Realm: shared

Returns

  • string: A formatted string identifying this item.

Source: gamemode/framework/meta/sh_item.lua:21

item:AddAction(name, actionData)

Registers a named action on this item class.

Actions are stored globally in ax.item.actions[self.class] rather than on the instance, so they are shared across all instances of the same class. When the class has a base, the base class actions are copied first so inheritance is preserved.

Passing an empty or invalid name or non-table actionData returns immediately.

Realm: shared

Parameters

Name Type Description
name string The unique action identifier (e.g. "use", "drop", "eat").
actionData table The action definition table. Should contain at minimum a label string and an OnRun callback function.

Usage

item:AddAction("eat", { label = "Eat", OnRun = function(self) ... end })

Source: gamemode/framework/meta/sh_item.lua:405

item:ApplyAppearance(entity)

Applies this item's visual appearance to a world entity.

Sets the entity's skin, material, color, and bodygroups from the item's current values. Bodygroup IDs are resolved through ax.util:ResolveBodygroupIndex which supports both numeric indices and named string keys. Skips bodygroups whose index cannot be resolved. Returns false immediately if entity is not valid.

Realm: shared

Parameters

Name Type Description
entity Entity The entity to apply appearance properties to.

Returns

  • boolean: True on success, false if entity is not valid.

Source: gamemode/framework/meta/sh_item.lua:139

item:Call(method, client, entity, ...)

Calls a named method on this item instance with optional player and entity context.

Temporarily sets self.player and self.entity on the item table before invoking the method, then restores both values afterwards. This allows item methods to access self.player and self.entity without the caller needing to pass them as arguments.

Returns all values returned by the invoked method via unpack. Returns nothing if method is not a string or the method does not exist on this item.

Realm: shared

Parameters

Name Type Description
method string The name of the method to call on this item.
client Player\|nil The player to bind as self.player during the call. Pass nil to leave unchanged.
entity Entity\|nil The entity to bind as self.entity during the call. Pass nil to leave unchanged.
... any Additional arguments forwarded to the method.

Returns

  • any: All return values from the called method.

Source: gamemode/framework/meta/sh_item.lua:309

item:CanInteract(client, action, silent, context)

Returns whether a player is allowed to perform a named action on this item.

Runs two checks in order:

  1. Fires "CanPlayerInteractItem" hook — returning false blocks the action and optionally sends catch as an error notification to the client (unless silent).
  2. Calls actionTable:CanUse(client, self, context) if the action defines it — returning false similarly blocks the action with an optional notification.

Returns true and no second value when all checks pass.

Realm: shared

Parameters

Name Type Description
client Player The player attempting the interaction.
action string The action name to validate (must exist in self:GetActions()).
silent boolean\|nil When true, suppresses error notifications sent to client.
context any\|nil Optional context value forwarded to CanUse and the hook.

Returns

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

Source: gamemode/framework/meta/sh_item.lua:437

item:GetActions()

Returns the actions table for this item.

Delegates to ax.item:GetActionsForClass(self.class) when the item has a valid class string, which returns the merged action set (including inherited base actions).

Falls back to self.actions or an empty table when the class is unavailable.

Actions are keyed by name and each entry is a table with at minimum a label and an OnRun callback.

Realm: shared

Returns

  • table: The actions table keyed by action name.

Source: gamemode/framework/meta/sh_item.lua:390

item:GetBodygroups()

Returns the bodygroup overrides table for this item.

The table maps bodygroup IDs (string or number keys) to their desired values. The format is { ["groupID"] = groupValue } where groupID can be either the numeric bodygroup index or a named string resolved via ax.util:ResolveBodygroupIndex.

Returns an empty table when no bodygroups are defined.

Realm: shared

Returns

  • table: The bodygroups table, or {} if not set.

Source: gamemode/framework/meta/sh_item.lua:109

item:GetClass()

Returns the class name of this item.

The class name identifies which registered item definition in ax.item.stored this instance belongs to (e.g. "weapon_pistol", "food_bread").

Realm: shared

Returns

  • string: The item's class name string.

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

item:GetColor()

Returns the color applied to this item's model.

Delegates to ax.item:NormalizeColor which coerces self.color into a valid Color object. Returns white (Color(255, 255, 255, 255)) when unset.

Realm: shared

Returns

  • Color: The item's color value.

Source: gamemode/framework/meta/sh_item.lua:87

item:GetData(key, default)

Returns a value from this item's data store, with an optional fallback.

Initialises self.data to an empty table if it is not already a table. Returns default when the key is nil; returns the stored value otherwise.

Use SetData to write values that should be persisted to the database.

Realm: shared

Parameters

Name Type Description
key string The data key to retrieve.
default any The value to return when the key is not set. Defaults to nil.

Returns

  • any: The stored value, or default if the key is absent.

Usage

local isActive = item:GetData("active", false)

Source: gamemode/framework/meta/sh_item.lua:294

item:GetDescription()

Returns the description text for this item.

Falls back to "No description available." when self.description is nil.

Displayed in item tooltips and examine prompts.

Realm: shared

Returns

  • string: The item's description, or a default placeholder string.

Source: gamemode/framework/meta/sh_item.lua:54

item:GetGridX()

Grid column this item currently occupies, if placed in a grid-addressed inventory.

Set at instance/placement time (item.gridX), not persisted on the item definition itself. Nil for items not in a grid-addressed inventory.

Realm: shared

Returns

  • number|nil

Source: gamemode/framework/meta/sh_item.lua:226

item:GetGridY()

Grid row this item currently occupies. See GetGridX.

Realm: shared

Returns

  • number|nil

Source: gamemode/framework/meta/sh_item.lua:233

item:GetHeight()

Item footprint height in grid cells. See GetWidth.

Realm: shared

Returns

  • number

Source: gamemode/framework/meta/sh_item.lua:282

item:GetID()

Returns the unique numeric ID of this item instance.

This is the primary key from the ax_items table. Temporary items use negative IDs auto-decremented from -1.

Realm: shared

Returns

  • number: The item's numeric ID.

Source: gamemode/framework/meta/sh_item.lua:29

item:GetInventories()

Returns every loaded inventory owned by this item (e.g. a bag's contents) - the reverse of

GetInventoryID(), which is the inventory this item sits in. An item only has owned

inventories if something created one via ax.inventory:Create({ owner = itemInstance, ... })

(see ax.inventory:RegisterOwnerResolver's built-in "item" kind) - most items have none, so

this returns an empty table for them. Only inventories already loaded into

ax.inventory.instances are returned - call ax.inventory:RestoreOwner(itemInstance, ...)

first if this item was just loaded and its owned inventories haven't synced yet.

Realm: shared

Returns

  • table: An array of inventory instances.

Source: gamemode/framework/meta/sh_item.lua:192

item:GetInventoryByType(typeID)

Returns this item's owned inventory of the given type (e.g. "bag"), or nil if it doesn't

have one loaded. See GetInventories.

Realm: shared

Parameters

Name Type Description
typeID string The inventory type id to look for.

Returns

  • table|nil

Source: gamemode/framework/meta/sh_item.lua:212

item:GetInventoryID()

Returns the inventory ID that contains this item.

First checks self.invID (set when the item is loaded into an inventory). If that is nil, performs a linear search through all loaded inventory instances to find which one's items table contains this item ID. Returns nil when the item is not found in any loaded inventory.

Realm: shared

Returns

  • number|nil: The inventory ID, or nil if not found in any loaded inventory.

Source: gamemode/framework/meta/sh_item.lua:165

item:GetMaterial()

Returns the material override for this item's model.

Returns an empty string when self.material is not a string, which is interpreted by GMod as "no material override".

Realm: shared

Returns

  • string: The material path, or "" if not set.

Source: gamemode/framework/meta/sh_item.lua:95

item:GetModel()

Returns the world model path for this item.

Used when spawning the item as a world entity or displaying it in a 3D panel.

Falls back to the wooden crate model when self.model is unset.

Realm: shared

Returns

  • string: The model path string.

Source: gamemode/framework/meta/sh_item.lua:71

item:GetName()

Returns the display name of this item.

Falls back to "Unknown" when self.name is nil or not set. This is the value shown in inventory UIs and item tooltips.

Realm: shared

Returns

  • string: The item's display name, or "Unknown" if unset.

Source: gamemode/framework/meta/sh_item.lua:45

item:GetSkin()

Returns the skin index for this item's model.

Clamps the value to 0 or above via math.max and coerces it to a non-negative integer via math.floor. Falls back to 0 when self.skin is unset or non-numeric.

Realm: shared

Returns

  • number: The skin index (≥ 0).

Source: gamemode/framework/meta/sh_item.lua:79

item:GetSlotID()

Named slot this item currently occupies, if placed in a slot-addressed inventory (e.g. equipment). Set at instance/placement time (item.slotID).

Realm: shared

Returns

  • string|nil

Source: gamemode/framework/meta/sh_item.lua:240

item:GetWeight()

Returns the weight of this item.

Used by inventory:GetWeight() and inventory:CanStoreWeight() for capacity checks. Falls back to 0 when no weight is defined on the item class.

Realm: shared

Returns

  • number: The item's weight, or 0 if not set.

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

item:GetWidth()

Item footprint width in grid cells. Static per item class (ITEM.width, inherited via the instance metatable), defaults to 1 for items that never declare it.

Realm: shared

Returns

  • number

Source: gamemode/framework/meta/sh_item.lua:275

item:HasAppearanceOverrides()

Returns whether this item has any non-default appearance overrides.

Checks skin (> 0), material (non-empty), color (not pure white/opaque), or any bodygroup entries. Used to decide whether ApplyAppearance needs to be called at all, avoiding unnecessary engine calls for items using default visuals.

Realm: shared

Returns

  • boolean: True if any appearance property differs from the default.

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

item:IsLocked()

Returns whether this item is locked by an in-progress transfer transaction.

Set by ax.inventory:Transfer for the duration of a single transfer to close the race

where two players act on the same item (e.g. a shared container) before the first

transfer's database write returns. Purely an in-memory flag - never persisted, never

true across a restart.

Realm: server

Returns

  • boolean

Source: gamemode/framework/meta/sh_item.lua:251

item:Lock()

Locks this item, blocking further transfers until Unlock is called.

Internal - called by ax.inventory:Transfer at the start of a transaction. Not

meant to be called directly by gameplay code.

Realm: server

Source: gamemode/framework/meta/sh_item.lua:260

item:SetData(key, value, bNoDBUpdate)

Sets a value in this item's data store and persists the change to the database.

Writes value to self.data[key]. On the server, skips persistence for temporary or no-save items (and inventories). For persistent items, issues a MySQL UPDATE to ax_items serialising the entire data table as JSON. After the write, broadcasts the single changed (key, value) pair to the owning inventory's receivers - not a full ax.inventory:Sync (this is the hottest call site of the two, since any item stat/durability/ammo change goes through here).

This function is safe to call on the client (does not issue queries client-side).

Realm: shared

Parameters

Name Type Description
key string The data key to write.
value any The value to store. Must be JSON-serialisable when persisting.
bNoDBUpdate boolean Whether to skip the database update. Defaults to false.

Source: gamemode/framework/meta/sh_item.lua:344

item:Unlock()

Unlocks this item after its in-progress transfer transaction finishes, successfully or not.

Internal - called by ax.inventory:Transfer. Not meant to be called directly by gameplay code.

Realm: server

Source: gamemode/framework/meta/sh_item.lua:268