Skip to content

Inventory Meta

Inventories hold items for characters or in-world containers.

This document lists methods for managing and syncing these item stores.


Overview

Inventory-meta functions handle transactions, capacity checks, retrieval by slot or ID, and persistent data storage.

Inventories keep items in a grid layout and may belong to characters or world containers.

The helpers also manage network updates so clients remain in sync with server-side changes.


getData

Purpose

Returns a stored data value for this inventory.

Parameters

  • key (string): Data field key.

  • default (any): Value to return when the key is absent.

Realm

Shared

Returns

  • any: Stored value or default.

Example Usage

-- Read how many times the container was opened
local opens = inv:getData("openCount", 0)

extend

Purpose

Creates a subclass of the inventory meta table with a new class name.

Parameters

  • className (string): Name of the subclass meta table.

Realm

Shared

Returns

  • table: The newly derived inventory table.

Example Usage

-- Define a subclass for weapon crates and register it
local WeaponInv = inv:extend("WeaponInventory")

function WeaponInv:configure()
    self:addAccessRule(function(_, action, ctx)
        if action == "add" then
            return ctx.item.isWeapon == true
        end
    end)
end

WeaponInv:register("weapon_inv")

configure

Purpose

Stub for inventory configuration; meant to be overridden.

Parameters

  • None

Realm

Shared

Returns

  • nil: This function does not return a value.

Example Usage

-- Called from a subclass to register custom access rules
function WeaponInv:configure()
    self:addAccessRule(function(_, action, ctx)
        if action == "add" then
            return ctx.item.isWeapon
        end
    end)
end

addDataProxy

Purpose

Adds a proxy function that is called when a data field changes.

Parameters

  • key (string): Data field to watch.

  • onChange (function): Callback receiving old and new values.

Realm

Shared

Returns

  • nil: This function does not return a value.

Example Usage

-- Track changes to the "locked" data field
inv:addDataProxy("locked", function(old, new)
    print("Locked state changed", old, new)
    hook.Run("ChestLocked", inv, new)
end)

getItemsByUniqueID

Purpose

Returns all items in the inventory matching the given unique ID.

Parameters

  • uniqueID (string): Item unique identifier.

  • onlyMain (boolean): Search only the main item list.

Realm

Shared

Returns

  • table: Table of matching item objects.

Example Usage

-- Use each ammo box found in the main list
for _, box in ipairs(inv:getItemsByUniqueID("ammo_box", true)) do
    box:use()
end

register

Purpose

Registers this inventory type with the lia.inventory system.

Parameters

  • typeID (string): Unique identifier for this inventory type.

Realm

Shared

Returns

  • nil: This function does not return a value.

Example Usage

-- Register and then immediately create the inventory type
WeaponInv:register("weapon_inv")
local chestInv = WeaponInv:new()

new

Purpose

Creates a new inventory of this type.

Parameters

  • None

Realm

Shared

Returns

  • table: New inventory instance.

Example Usage

-- Create an inventory and attach it to a spawned chest entity
local chest = ents.Create("prop_physics")
chest:SetModel("models/props_junk/wood_crate001a.mdl")
chest:Spawn()

chest.inv = WeaponInv:new()

tostring

Purpose

Returns a printable representation of this inventory.

Parameters

  • None

Realm

Shared

Returns

  • string: Formatted as "ClassName[id]".

Example Usage

-- Print the identifier when debugging
print("Inventory: " .. inv:tostring())

getType

Purpose

Retrieves the inventory type table from lia.inventory.

Parameters

  • None

Realm

Shared

Returns

  • table: Inventory type definition.

Example Usage

-- Read slot data from the type definition
local def = inv:getType()

onDataChanged

Purpose

Called when an inventory data field changes and executes any registered proxy callbacks.

Parameters

  • key (string): Data field key.

  • oldValue (any): Previous value.

  • newValue (any): Updated value.

Realm

Shared

Returns

  • nil: This function does not return a value.

Example Usage

function WeaponInv:onDataChanged(key, old, new)
    print(key .. " changed from", old, "to", new)
end

getItems

Purpose

Returns all items stored in this inventory.

Parameters

  • None

Realm

Shared

Returns

  • table: Item instance table indexed by itemID.

Example Usage

-- Sum the weight of all items
local totalWeight = 0

for _, itm in pairs(inv:getItems()) do
    totalWeight = totalWeight + itm.weight
end

print("Weight:", totalWeight)

getItemsOfType

Purpose

Collects all items that match the given unique ID.

Parameters

  • itemType (string): Item unique identifier.

Realm

Shared

Returns

  • table: Array of matching items.

Example Usage

-- List all medkits currently in the inventory
local kits = inv:getItemsOfType("medkit")

getFirstItemOfType

Purpose

Retrieves the first item matching the given unique ID.

Parameters

  • itemType (string): Item unique identifier.

Realm

Shared

Returns

  • Item|nil: The first matching item or nil.

Example Usage

-- Grab the first pistol found in the inventory
local pistol = inv:getFirstItemOfType("pistol")

hasItem

Purpose

Determines whether the inventory contains an item type.

Parameters

  • itemType (string): Item unique identifier.

Realm

Shared

Returns

  • boolean: True if an item is found.

Example Usage

-- See if any health potion exists
if inv:hasItem("health_potion") then
    print("You have a potion ready!")
end

getItemCount

Purpose

Counts the total quantity of a specific item type.

Parameters

  • itemType (string|nil): Item unique ID to count; counts all if nil.

Realm

Shared

Returns

  • number: Sum of quantities.

Example Usage

-- Count the total number of bullets
local ammoTotal = inv:getItemCount("bullet")
print("Ammo remaining:", ammoTotal)

getID

Purpose

Returns the unique database ID of this inventory.

Parameters

  • None

Realm

Shared

Returns

  • number: Inventory identifier.

Example Usage

-- Store the inventory ID on its container entity
entity:setNetVar("invID", inv:getID())

eq

Purpose

Compares two inventories by ID for equality.

Parameters

  • other (Inventory): Other inventory to compare.

Realm

Shared

Returns

  • boolean: True if both inventories share the same ID.

Example Usage

-- Check if two chests share the same inventory record
if inv:eq(other) then
    print("Duplicate inventory")
end

addItem

Purpose

Inserts an item instance into this inventory and persists it.

Parameters

  • item (Item): Item to add.

  • noReplicate (boolean): Skip network replication when true.

Realm

Server

Returns

  • table: The inventory instance.

Example Usage

-- Add a looted item to the inventory
if not inv:hasItem(item.uniqueID) then
    inv:addItem(item, false)
end

add

Purpose

Alias for addItem that inserts an item into the inventory.

Parameters

  • item (Item): Item to add.

Realm

Server

Returns

  • table: The inventory instance.

Example Usage

inv:add(item)

syncItemAdded

Purpose

Replicates a newly added item to all clients that can access the inventory.

Parameters

  • item (Item): Item instance that was added.

Realm

Server

Returns

  • nil: This function does not return a value.

Example Usage

inv:syncItemAdded(item)

initializeStorage

Purpose

Creates a persistent inventory record in the database using supplied initial data.

Parameters

  • initialData (table): Values to store when creating the inventory.

Realm

Server

Returns

  • Deferred: Resolves with the new inventory ID.

Example Usage

WeaponInv:initializeStorage({char = charID, locked = true}):next(function(id)
    print("Created inventory", id)
end)

restoreFromStorage

Purpose

Stub called when loading an inventory from custom storage systems.

Parameters

  • None

Realm

Server

Returns

  • nil: This function does not return a value.

Example Usage

inv:restoreFromStorage()

removeItem

Purpose

Removes an item by ID and optionally deletes it.

Parameters

  • itemID (number): Unique item identifier.

  • preserveItem (boolean): Keep item in database when true.

Realm

Server

Returns

  • Deferred: Resolves once the item removal completes.

Example Usage

-- Remove an item but keep it saved for later
inv:removeItem(itemID, true):next(function()
    print("Item stored for later")
end)

remove

Purpose

Alias for removeItem that removes an item from the inventory.

Parameters

  • itemID (number): Unique item identifier.

Realm

Server

Returns

  • Deferred: Resolves once the item is removed.

Example Usage

inv:remove(itemID):next(function()
    print("Removed from the container")
end)

setData

Purpose

Sets a data field on the inventory and replicates the change to clients.

Parameters

  • key (string): Data field name.

  • value (any): Value to store.

Realm

Server

Returns

  • table: The inventory instance.

Example Usage

inv:setData("locked", true)

canAccess

Purpose

Evaluates access rules to determine whether an action is permitted.

Parameters

  • action (string): Action identifier.

  • context (table|nil): Additional data such as the client.

Realm

Server

Returns

  • boolean|nil: True, false, or nil if undecided.

  • string|nil: Optional failure reason.

Example Usage

local allowed = inv:canAccess("take", {client = ply})

addAccessRule

Purpose

Registers a function used by canAccess to grant or deny actions.

Parameters

  • rule (function): Access rule function.

  • priority (number|nil): Insertion position for the rule.

Realm

Server

Returns

  • table: The inventory instance.

Example Usage

inv:addAccessRule(function(inv, action, ctx)
    return ctx.client:IsAdmin()
end)

removeAccessRule

Purpose

Unregisters a previously added access rule.

Parameters

  • rule (function): The rule to remove.

Realm

Server

Returns

  • table: The inventory instance.

Example Usage

inv:removeAccessRule(myRule)

getRecipients

Purpose

Returns a list of players that should receive network updates for this inventory.

Parameters

  • None

Realm

Server

Returns

  • table: Array of Player objects.

Example Usage

local receivers = inv:getRecipients()

onInstanced

Purpose

Called after a new inventory is created in the database.

Parameters

  • None

Realm

Server

Returns

  • nil: This function does not return a value.

Example Usage

function WeaponInv:onInstanced()
    print("Created inventory", self:getID())
end

onLoaded

Purpose

Called after an inventory is loaded from the database.

Parameters

  • None

Realm

Server

Returns

  • nil: This function does not return a value.

Example Usage

function WeaponInv:onLoaded()
    print("Loaded inventory", self:getID())
end

loadItems

Purpose

Loads all items belonging to this inventory from storage.

Parameters

  • None

Realm

Server

Returns

  • Deferred: Resolves with a table of loaded items.

Example Usage

inv:loadItems():next(function(items)
    print("Loaded", table.Count(items), "items")
end)

onItemsLoaded

Purpose

Hook called after loadItems finishes loading all items.

Parameters

  • items (table): Loaded items indexed by ID.

Realm

Server

Returns

  • nil: This function does not return a value.

Example Usage

function WeaponInv:onItemsLoaded(items)
    print("Ready with", #items, "items")
end

instance

Purpose

Creates and stores a new inventory instance of this type.

Parameters

  • initialData (table|nil): Data to populate the inventory with.

Realm

Server

Returns

  • Deferred: Resolves with the created inventory.

Example Usage

WeaponInv:instance({char = charID}):next(function(inv)
    -- use inventory
end)

syncData

Purpose

Sends a single data field to clients.

Parameters

  • key (string): Field to replicate.

  • recipients (table|nil): Player recipients.

Realm

Server

Returns

  • nil: This function does not return a value.

Example Usage

-- Sync the locked state to nearby players
inv:syncData("locked", recipients)

sync

Purpose

Sends the entire inventory and its items to players.

Parameters

  • recipients (table|nil): Player recipients.

Realm

Server

Returns

  • nil: This function does not return a value.

Example Usage

-- Send all items to the owner after they join
inv:sync({owner})

delete

Purpose

Removes this inventory record from the database.

Parameters

  • None

Realm

Server

Returns

  • nil: This function does not return a value.

Example Usage

-- Permanently delete a chest inventory on cleanup
inv:delete()
print("Inventory removed from database")

destroy

Purpose

Destroys all items and removes network references.

Parameters

  • None

Realm

Server

Returns

  • nil: This function does not return a value.

Example Usage

-- Clear all items when the container entity is removed
inv:destroy()
print("Inventory destroyed")

show

Purpose

Opens the inventory user interface on the client.

Parameters

  • parent (Panel|nil): Optional parent panel.

Realm

Client

Returns

  • Panel: The created inventory UI panel.

Example Usage

-- Open as a stand-alone window
inv:show()

-- Or attach to an existing panel
local ui = inv:show(parentPanel)