Skip to content

meta/sh_item

Source: gamemode/framework/meta/sh_item.lua

Returns a human-readable string representation of the item.

Documented functions: 20

Functions

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.

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

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.

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.

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.

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.

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.

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.

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.

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)

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.

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.

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.

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.

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.

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.

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

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.

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.

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, calls ax.inventory:Sync to push the change to all receivers of the owning inventory.

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.