Inventory

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)

Purpose

Retrieves a stored data value on the inventory.

When Called

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)

Purpose

Creates a subclass of Inventory with its own metatable.

When Called

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

Purpose

Sets up inventory defaults; meant to be overridden.

When Called

Invoked during type registration to configure behavior.

Example Usage

  function Inventory:configure() self.config.size = {4,4} end

---

configure()

Purpose

Sets up inventory defaults; meant to be overridden.

When Called

Invoked during type registration to configure behavior.

Example Usage

  function Inventory:configure() self.config.size = {4,4} end

---

addDataProxy(key, onChange)

Purpose

Registers a proxy callback for a specific data key.

When Called

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)

Purpose

Returns all items in the inventory matching a uniqueID.

When Called

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)

Purpose

Registers this inventory type with the system.

When Called

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

Purpose

Creates a new instance of this inventory type.

When Called

Use when a character or container needs a fresh inventory.

Returns

table Deferred inventory instance creation.

Example Usage

  local inv = Inventory:new()

---

tostring()

Purpose

Formats the inventory as a readable string with its ID.

When Called

Use for logging or debugging output.

Returns

string Localized class name and ID.

Example Usage

  print(inv:tostring())

---

getType()

Purpose

Returns the inventory type definition table.

When Called

Use when accessing type-level configuration.

Returns

table Registered inventory type data.

Example Usage

  local typeData = inv:getType()

---

onDataChanged(key, oldValue, newValue)

Purpose

Fires proxy callbacks when a tracked data value changes.

When Called

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

Purpose

Returns the table of item instances in this inventory.

When Called

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)

Purpose

Collects items of a given type from the inventory.

When Called

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)

Purpose

Returns the first item matching a uniqueID.

When Called

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)

Purpose

Checks whether the inventory contains an item type.

When Called

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)

Purpose

Counts items, optionally filtering by uniqueID.

When Called

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

Purpose

Returns the numeric identifier for this inventory.

When Called

Use when networking, saving, or comparing inventories.

Returns

number Inventory ID.

Example Usage

  local id = inv:getID()

---

addItem(item, noReplicate)

Purpose

Inserts an item into this inventory and persists its invID.

When Called

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)

Purpose

Alias to addItem for convenience.

When Called

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)

Purpose

Notifies clients about an item newly added to this inventory.

When Called

Invoked after addItem to replicate state.

Parameters

Item item Item instance already inserted.

Example Usage

  inv:syncItemAdded(item)

---

initializeStorage(initialData)

Purpose

Creates a database record for a new inventory and its data.

When Called

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

Purpose

Hook for restoring inventory data from storage.

When Called

Override to load custom data during restoration.

Example Usage

  function Inventory:restoreFromStorage() end

---

restoreFromStorage()

Purpose

Hook for restoring inventory data from storage.

When Called

Override to load custom data during restoration.

Example Usage

  function Inventory:restoreFromStorage() end

---

removeItem(itemID, preserveItem)

Purpose

Removes an item from this inventory and updates clients/DB.

When Called

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)

Purpose

Alias for removeItem.

When Called

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)

Purpose

Updates inventory data, persists it, and notifies listeners.

When Called

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)

Purpose

Evaluates access rules for a given action context.

When Called

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)

Purpose

Inserts an access rule into the rule list.

When Called

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)

Purpose

Removes a previously added access rule.

When Called

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

Purpose

Determines which players should receive inventory replication.

When Called

Use before sending inventory data to clients.

Returns

table List of player recipients allowed by access rules.

Example Usage

  local recips = inv:getRecipients()

---

onInstanced()

Purpose

Hook called when an inventory instance is created.

When Called

Override to perform custom initialization.

Example Usage

  function Inventory:onInstanced() end

---

onInstanced()

Purpose

Hook called when an inventory instance is created.

When Called

Override to perform custom initialization.

Example Usage

  function Inventory:onInstanced() end

---

onLoaded()

Purpose

Hook called after inventory data is loaded.

When Called

Override to react once storage data is retrieved.

Example Usage

  function Inventory:onLoaded() end

---

onLoaded()

Purpose

Hook called after inventory data is loaded.

When Called

Override to react once storage data is retrieved.

Example Usage

  function Inventory:onLoaded() end

---

loadItems()

Purpose

Loads item instances from the database into this inventory.

When Called

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)

Purpose

Hook called after items are loaded into the inventory.

When Called

Override to run logic after contents are ready.

Parameters

table items Loaded items table.

Example Usage

  function Inventory:onItemsLoaded(items) end

---

onItemsLoaded(items)

Purpose

Hook called after items are loaded into the inventory.

When Called

Override to run logic after contents are ready.

Parameters

table items Loaded items table.

Example Usage

  function Inventory:onItemsLoaded(items) end

---

instance(initialData)

Purpose

Creates and registers an inventory instance with initial data.

When Called

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)

Purpose

Sends a single inventory data key to recipients.

When Called

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)

Purpose

Sends full inventory state and contained items to recipients.

When Called

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

Purpose

Deletes this inventory via the inventory manager.

When Called

Use when permanently removing an inventory record.

Example Usage

  inv:delete()

---

destroy()

Purpose

Clears inventory items, removes it from cache, and notifies clients.

When Called

Use when unloading or destroying an inventory instance.

Example Usage

  inv:destroy()

---

show(parent)

Purpose

Opens the inventory UI on the client.

When Called

Use to display this inventory to the player.

Parameters

Panel parent Optional parent panel.

Returns

Panel The created inventory panel.

Example Usage

  inv:show()

---