Inventory Meta
Inventory management system for the Lilia framework.
Overview
The inventory meta table provides comprehensive functionality for managing inventory data, item storage, and inventory operations in the Lilia framework. It handles inventory creation, item management, data persistence, capacity management, and inventory-specific operations. The meta table operates on both server and client sides, with the server managing inventory storage and validation while the client provides inventory data access and display. It includes integration with the item system for item storage, database system for inventory persistence, character system for character inventories, and network system for inventory synchronization. The meta table ensures proper inventory data synchronization, item capacity management, item validation, and comprehensive inventory lifecycle management from creation to deletion.
getData(key, default)
Retrieves a stored data value on the inventory.
Use whenever reading custom inventory metadata.
Parameters:
string key Data key to read.any default Value returned when the key is missing.
Returns:
any Stored value or the provided default.Example Usage:
local owner = inv:getData("char")
extend(className)
Creates a subclass of Inventory with its own metatable.
Use when defining a new inventory type.
Parameters:
string className Registry name for the new subclass.Returns:
table Newly created subclass table.Example Usage:
local Backpack = Inventory:extend("liaBackpack")
configure()
Sets up inventory defaults; meant to be overridden.
Invoked during type registration to configure behavior.
Example Usage:
function Inventory:configure() self.config.size = {4,4} end
configure()
Sets up inventory defaults; meant to be overridden.
Invoked during type registration to configure behavior.
Example Usage:
function Inventory:configure() self.config.size = {4,4} end
addDataProxy(key, onChange)
Registers a proxy callback for a specific data key.
Use when you need to react to data changes.
Parameters:
string key Data key to watch.function onChange Callback receiving old and new values.
Example Usage:
inv:addDataProxy("locked", function(o,n) end)
getItemsByUniqueID(uniqueID, onlyMain)
Returns all items in the inventory matching a uniqueID.
Use when finding all copies of a specific item type.
Parameters:
string uniqueID Item unique identifier.boolean onlyMain Restrict search to main inventory when true.
Returns:
table Array of matching item instances.Example Usage:
local meds = inv:getItemsByUniqueID("medkit")
register(typeID)
Registers this inventory type with the system.
Invoke once per subclass to set type ID and defaults.
Parameters:
string typeID Unique identifier for this inventory type.Example Usage:
Inventory:register("bag")
new()
Creates a new instance of this inventory type.
Use when a character or container needs a fresh inventory.
Returns:
table Deferred inventory instance creation.Example Usage:
local inv = Inventory:new()
tostring()
Formats the inventory as a readable string with its ID.
Use for logging or debugging output.
Returns:
string Localized class name and ID.Example Usage:
print(inv:tostring())
getType()
Returns the inventory type definition table.
Use when accessing type-level configuration.
Returns:
table Registered inventory type data.Example Usage:
local typeData = inv:getType()
onDataChanged(key, oldValue, newValue)
Fires proxy callbacks when a tracked data value changes.
Internally after setData updates.
Parameters:
string key Data key that changed.any oldValue Previous value.
any newValue New value.
Example Usage:
inv:onDataChanged("locked", false, true)
getItems()
Returns the table of item instances in this inventory.
Use when iterating all items.
Returns:
table Item instances keyed by item ID.Example Usage:
for id, itm in pairs(inv:getItems()) do end
getItemsOfType(itemType)
Collects items of a given type from the inventory.
Use when filtering for a specific item uniqueID.
Parameters:
string itemType Unique item identifier to match.Returns:
table Array of matching items.Example Usage:
local foods = inv:getItemsOfType("food")
getFirstItemOfType(itemType)
Returns the first item matching a uniqueID.
Use when only one instance of a type is needed.
Parameters:
string itemType Unique item identifier to find.Returns:
table|nil Item instance or nil if none found.Example Usage:
local gun = inv:getFirstItemOfType("pistol")
hasItem(itemType)
Checks whether the inventory contains an item type.
Use before consuming or requiring an item.
Parameters:
string itemType Unique item identifier to check.Returns:
boolean True if at least one matching item exists.Example Usage:
if inv:hasItem("keycard") then unlock() end
getItemCount(itemType)
Counts items, optionally filtering by uniqueID.
Use for capacity checks or UI badge counts.
Parameters:
string itemType optional Unique ID to filter by; nil counts all.Returns:
number Total quantity of matching items.Example Usage:
local ammoCount = inv:getItemCount("ammo")
getID()
Returns the numeric identifier for this inventory.
Use when networking, saving, or comparing inventories.
Returns:
number Inventory ID.Example Usage:
local id = inv:getID()
addItem(item, noReplicate)
Inserts an item into this inventory and persists its invID.
Use when adding an item to the inventory on the server.
Parameters:
Item item Item instance to add.boolean noReplicate Skip replication hooks when true.
Returns:
Inventory The inventory for chaining.Example Usage:
inv:addItem(item)
add(item)
Alias to addItem for convenience.
Use wherever you would call addItem.
Parameters:
Item item Item instance to add.Returns:
Inventory The inventory for chaining.Example Usage:
inv:add(item)
syncItemAdded(item)
Notifies clients about an item newly added to this inventory.
Invoked after addItem to replicate state.
Parameters:
Item item Item instance already inserted.Example Usage:
inv:syncItemAdded(item)
initializeStorage(initialData)
Creates a database record for a new inventory and its data.
Use during initial inventory creation.
Parameters:
table initialData Key/value pairs to seed invdata rows; may include char.Returns:
Promise Resolves with new inventory ID.Example Usage:
inv:initializeStorage({char = charID})
restoreFromStorage()
Hook for restoring inventory data from storage.
Override to load custom data during restoration.
Example Usage:
function Inventory:restoreFromStorage() end
restoreFromStorage()
Hook for restoring inventory data from storage.
Override to load custom data during restoration.
Example Usage:
function Inventory:restoreFromStorage() end
removeItem(itemID, preserveItem)
Removes an item from this inventory and updates clients/DB.
Use when deleting or moving items out of the inventory.
Parameters:
number itemID ID of the item to remove.boolean preserveItem Keep the instance and DB row when true.
Returns:
Promise Resolves after removal finishes.Example Usage:
inv:removeItem(itemID)
remove(itemID)
Alias for removeItem.
Use interchangeably with removeItem.
Parameters:
number itemID ID of the item to remove.Returns:
Promise Resolves after removal.Example Usage:
inv:remove(id)
setData(key, value)
Updates inventory data, persists it, and notifies listeners.
Use to change stored metadata such as character assignment.
Parameters:
string key Data key to set.any value New value or nil to delete.
Returns:
Inventory The inventory for chaining.Example Usage:
inv:setData("locked", true)
canAccess(action, context)
Evaluates access rules for a given action context.
Use before allowing inventory interactions.
Parameters:
string action Action name (e.g., "repl", "transfer").table context Additional data such as client.
Returns:
boolean|nil, string|nil Decision and optional reason if a rule handled it.Example Usage:
local ok = inv:canAccess("repl", {client = ply})
addAccessRule(rule, priority)
Inserts an access rule into the rule list.
Use when configuring permissions for this inventory type.
Parameters:
function rule Function returning decision and reason.number priority optional Optional insert position.
Returns:
Inventory The inventory for chaining.Example Usage:
inv:addAccessRule(myRule, 1)
removeAccessRule(rule)
Removes a previously added access rule.
Use when unregistering dynamic permission logic.
Parameters:
function rule The rule function to remove.Returns:
Inventory The inventory for chaining.Example Usage:
inv:removeAccessRule(myRule)
getRecipients()
Determines which players should receive inventory replication.
Use before sending inventory data to clients.
Returns:
table List of player recipients allowed by access rules.Example Usage:
local recips = inv:getRecipients()
onInstanced()
Hook called when an inventory instance is created.
Override to perform custom initialization.
Example Usage:
function Inventory:onInstanced() end
onInstanced()
Hook called when an inventory instance is created.
Override to perform custom initialization.
Example Usage:
function Inventory:onInstanced() end
onLoaded()
Hook called after inventory data is loaded.
Override to react once storage data is retrieved.
Example Usage:
function Inventory:onLoaded() end
onLoaded()
Hook called after inventory data is loaded.
Override to react once storage data is retrieved.
Example Usage:
function Inventory:onLoaded() end
loadItems()
Loads item instances from the database into this inventory.
Use during inventory initialization to restore contents.
Returns:
Promise Resolves with the loaded items table.Example Usage:
inv:loadItems():next(function(items) end)
onItemsLoaded(items)
Hook called after items are loaded into the inventory.
Override to run logic after contents are ready.
Parameters:
table items Loaded items table.Example Usage:
function Inventory:onItemsLoaded(items) end
onItemsLoaded(items)
Hook called after items are loaded into the inventory.
Override to run logic after contents are ready.
Parameters:
table items Loaded items table.Example Usage:
function Inventory:onItemsLoaded(items) end
instance(initialData)
Creates and registers an inventory instance with initial data.
Use to instantiate a server-side inventory of this type.
Parameters:
table initialData Data used during creation (e.g., char assignment).Returns:
Promise Resolves with the new inventory instance.Example Usage:
Inventory:instance({char = charID})
syncData(key, recipients)
Sends a single inventory data key to recipients.
Use after setData to replicate a specific field.
Parameters:
string key Data key to send.Player|table recipients optional Targets to notify; defaults to recipients with access.
Example Usage:
inv:syncData("locked")
sync(recipients)
Sends full inventory state and contained items to recipients.
Use when initializing or resyncing an inventory for clients.
Parameters:
Player|table recipients optional Targets to receive the update; defaults to access list.Example Usage:
inv:sync(ply)
delete()
Deletes this inventory via the inventory manager.
Use when permanently removing an inventory record.
Example Usage:
inv:delete()
destroy()
Clears inventory items, removes it from cache, and notifies clients.
Use when unloading or destroying an inventory instance.
Example Usage:
inv:destroy()
show(parent)
Opens the inventory UI on the client.
Use to display this inventory to the player.
Parameters:
Panel parent Optional parent panel.Returns:
Panel The created inventory panel.Example Usage:
inv:show()