Inventory¶
Inventory metadata helpers for inventory type registration, item lookup, data replication, persistence, access rules, and UI display.
Overview
getData(key, default)View Source
Purpose
Returns a stored inventory data value by key, or a fallback if the key is unset.
Realm
Shared
Parameters
string key The inventory data key to look up.
any default The fallback value returned when the key is not present.
Returns
any The stored value for the key, or the provided default.
Example Usage
local ownerID = inventory:getData("ownerID", 0)
print("Owner ID:", ownerID)
extend(className)View Source
Purpose
Creates or refreshes a derived inventory class in the debug registry.
Realm
Shared
Parameters
string className The registry class name used for the derived inventory table.
Returns
table The new subclass table inheriting from this inventory meta table.
Example Usage
local BagInventory = Inventory:extend("liaBagInventory")
configure(config)View Source
Purpose
Serves as an override point for configuring an inventory type before registration completes.
Realm
Shared
Parameters
table config The configuration table prepared during registration.
Example Usage
function BagInventory:configure(config)
config.data.capacity = {}
end
configure(config)View Source
Purpose
Serves as an override point for configuring an inventory type before registration completes.
Realm
Shared
Parameters
table config The configuration table prepared during registration.
Example Usage
function BagInventory:configure(config)
config.data.capacity = {}
end
addDataProxy(key, onChange)View Source
Purpose
Registers a callback that runs whenever a specific inventory data key changes.
Realm
Shared
Parameters
string key The inventory data key to watch.
function onChange The callback that receives the old and new values.
Example Usage
inventoryType:addDataProxy("locked", function(oldValue, newValue)
print("Lock state changed:", oldValue, newValue)
end)
getItemsByUniqueID(uniqueID, onlyMain)View Source
Purpose
Returns all items in this inventory whose unique ID matches the requested value.
Realm
Shared
Parameters
string uniqueID The item unique ID to search for.
boolean onlyMain optional Forwarded to the underlying item retrieval call when supported.
Returns
table A sequential table of matching item instances.
Example Usage
local ammoItems = inventory:getItemsByUniqueID("ammo_9mm")
print("Found ammo stacks:", #ammoItems)
register(typeID)View Source
Purpose
Finalizes inventory type configuration and registers the type with the inventory library.
Realm
Shared
Parameters
string typeID The unique identifier used to register this inventory type.
Example Usage
BagInventory:register("bag")
new()View Source
Purpose
Creates a new inventory instance for this registered type.
Realm
Shared
Returns
table The newly created inventory instance.
Example Usage
local inventory = inventoryType:new()
tostring()View Source
Purpose
Builds a readable localized label for this inventory instance.
Realm
Shared
Returns
string A string containing the localized class name and inventory ID.
Example Usage
print(inventory:tostring())
getType()View Source
Purpose
Returns the registered inventory type definition associated with this instance.
Realm
Shared
Returns
table|nil The inventory type table when registered.
Example Usage
local inventoryType = inventory:getType()
onDataChanged(key, oldValue, newValue)View Source
Purpose
Runs any proxy callbacks registered for a changed inventory data key.
Realm
Shared
Parameters
string key The inventory data key that changed.
any oldValue The previous value stored under the key.
any newValue The new value stored under the key.
Example Usage
inventory:onDataChanged("locked", false, true)
getItems()View Source
Purpose
Returns the internal item lookup table for this inventory.
Realm
Shared
Returns
table A table keyed by item ID containing item instances.
Example Usage
local items = inventory:getItems()
getItemsOfType(itemType)View Source
getFirstItemOfType(itemType)View Source
Purpose
Returns the first item in this inventory whose unique ID matches the requested type.
Realm
Shared
Parameters
string itemType The item unique ID to match.
Returns
table|nil The first matching item instance, if one exists.
Example Usage
local firstMedkit = inventory:getFirstItemOfType("medkit")
hasItem(itemType)View Source
Purpose
Checks whether this inventory contains at least one item of the requested type.
Realm
Shared
Parameters
string itemType The item unique ID to search for.
Returns
boolean True if at least one matching item exists, otherwise false.
Example Usage
if inventory:hasItem("lockpick") then
print("Lockpick found.")
end
getItemCount(itemType)View Source
Purpose
Counts item quantities in this inventory, optionally restricted to a specific item type.
Realm
Shared
Parameters
string itemType optional The item unique ID to count, or nil to count all item quantities.
Returns
number The total quantity of matching items.
Example Usage
local totalAmmo = inventory:getItemCount("ammo_9mm")
getID()View Source
Purpose
Returns the numeric ID assigned to this inventory instance.
Realm
Shared
Returns
number The inventory ID.
Example Usage
print("Inventory ID:", inventory:getID())
addItem(item, noReplicate)View Source
Purpose
Adds an item to this inventory, updates its persisted inventory ID, and replicates the change.
Realm
Server
Parameters
table item The item instance being added.
boolean noReplicate optional When true, skips running the `OnItemAdded` hook.
Returns
table This inventory instance for chaining.
Example Usage
inventory:addItem(itemInstance)
add(item)View Source
syncItemAdded(item)View Source
Purpose
Replicates a newly added item to all clients who can currently access this inventory.
Realm
Server
Parameters
table item The item instance to sync.
Example Usage
inventory:syncItemAdded(itemInstance)
initializeStorage(initialData)View Source
Purpose
Creates persistent database rows for a new inventory and its initial data payload.
Realm
Server
Parameters
table initialData A table of starting inventory data values. The special `char` key is stored on the inventory row.
Returns
table A deferred object that resolves with the new inventory ID.
Example Usage
inventoryType:initializeStorage({
char = character:getID(),
locked = false
})
restoreFromStorage()View Source
restoreFromStorage()View Source
removeItem(itemID, preserveItem)View Source
Purpose
Removes an item from this inventory and optionally preserves the item instance in storage.
Realm
Server
Parameters
number itemID The numeric item ID to remove.
boolean preserveItem optional When true, detaches the item from this inventory without deleting it.
Returns
table A deferred object that resolves after removal finishes.
Example Usage
inventory:removeItem(itemID, true)
remove(itemID)View Source
setData(key, value)View Source
Purpose
Sets an inventory data value, persists it when allowed, replicates it, and triggers change proxies.
Realm
Server
Parameters
Returns
table This inventory instance for chaining.
Example Usage
inventory:setData("locked", true)
canAccess(action, context)View Source
Purpose
Evaluates registered access rules for a specific inventory action and context.
Realm
Server
Parameters
string action The action being checked, such as `repl`.
table context optional Optional contextual data passed to each rule.
Returns
boolean|nil The first non-nil rule result. string|nil An optional reason returned by the matching rule.
Example Usage
local canReplicate = inventory:canAccess("repl", {
client = client
})
addAccessRule(rule, priority)View Source
Purpose
Adds an access rule to this inventory's rule list, optionally at a specific priority.
Realm
Server
Parameters
function rule The rule callback to add.
number priority optional The insert position for the rule when ordering matters.
Returns
table This inventory instance for chaining.
Example Usage
inventory:addAccessRule(function(inv, action, context)
if action == "repl" then
return context.client == inv:getOwner()
end
end)
removeAccessRule(rule)View Source
getRecipients()View Source
Purpose
Returns all connected players who currently pass this inventory's replication access rules.
Realm
Server
Returns
table A sequential table of recipient players.
Example Usage
local recipients = inventory:getRecipients()
onInstanced()View Source
onInstanced()View Source
onLoaded()View Source
onLoaded()View Source
loadItems()View Source
Purpose
Loads all persisted items belonging to this inventory and restores them into memory.
Realm
Server
Returns
table A promise-like query chain resolving to the restored item table.
Example Usage
inventory:loadItems():next(function(items)
print("Loaded items:", table.Count(items))
end)
onItemsLoaded(items)View Source
Purpose
Serves as an override point after `loadItems` restores the inventory item table.
Realm
Server
Parameters
table items The restored item table keyed by item ID.
Example Usage
function BagInventory:onItemsLoaded(items)
print("Items restored:", table.Count(items))
end
onItemsLoaded(items)View Source
Purpose
Serves as an override point after `loadItems` restores the inventory item table.
Realm
Server
Parameters
table items The restored item table keyed by item ID.
Example Usage
function BagInventory:onItemsLoaded(items)
print("Items restored:", table.Count(items))
end
instance(initialData)View Source
Purpose
Creates and persists a new instance of this inventory type using initial data.
Realm
Server
Parameters
table initialData The initial data table used during inventory instancing.
Returns
table The instanced inventory object or deferred result provided by the inventory library.
Example Usage
inventoryType:instance({
char = character:getID()
})
syncData(key, recipients)View Source
Purpose
Replicates a single inventory data key to clients unless replication is disabled for that key.
Realm
Server
Parameters
string key The inventory data key to replicate.
table recipients optional Optional recipient players. Defaults to current access recipients.
Example Usage
inventory:syncData("locked")
sync(recipients)View Source
Purpose
Replicates the full inventory state and all contained items to clients.
Realm
Server
Parameters
table recipients optional Optional recipient players. Defaults to current access recipients.
Example Usage
inventory:sync()
delete()View Source
destroy()View Source
show(parent)View Source
Purpose
Opens this inventory in the client inventory UI.
Realm
Client
Parameters
Panel parent optional The parent panel used when creating the inventory view.
Returns
Panel|table The UI panel or value returned by the inventory display helper.
Example Usage
inventory:show(parentPanel)