Inventory Library
Comprehensive inventory system management with multiple storage types for the Lilia framework.
Overview
The inventory library provides comprehensive functionality for managing inventory systems in the Lilia framework. It handles inventory type registration, instance creation, storage management, and database persistence. The library operates on both server and client sides, with the server managing inventory data persistence, loading, and storage registration, while the client handles inventory panel display and user interaction. It supports multiple inventory types, storage containers, vehicle trunks, and character-based inventory management. The library ensures proper data validation, caching, and cleanup for optimal performance.
lia.inventory.newType(typeID, invTypeStruct)
Registers a new inventory type with the specified ID and structure.
Called during gamemode initialization or when defining custom inventory types that extend the base inventory system.
Parameters:
string typeID Unique identifier for the inventory type.table invTypeStruct Table containing the inventory type definition with required fields like className, config, and methods.
Example Usage:
lia.inventory.newType("grid", {
className = "GridInv",
config = {w = 10, h = 10},
add = function(self, item) end,
remove = function(self, item) end,
sync = function(self, client) end
})
lia.inventory.new(typeID)
Creates a new inventory instance of the specified type.
Called when instantiating inventories during loading, character creation, or when creating new storage containers.
Parameters:
string typeID The inventory type identifier that was previously registered with newType.Returns:
table A new inventory instance with items table and copied config from the type definition.Example Usage:
local myInventory = lia.inventory.new("grid")
-- Creates a new grid-based inventory instance
lia.inventory.loadByID(id, noCache)
Loads an inventory instance by its ID, checking cache first and falling back to storage loading.
Called when accessing inventories by ID, typically during character loading, item operations, or storage access.
Parameters:
number id The unique inventory ID to load.boolean noCache Optional flag to bypass cache and force loading from storage.
Returns:
Deferred A deferred object that resolves to the loaded inventory instance, or rejects if loading fails.Example Usage:
lia.inventory.loadByID(123):next(function(inventory)
print("Loaded inventory:", inventory.id)
end)
lia.inventory.loadFromDefaultStorage(id, noCache)
Loads an inventory from the default database storage, including associated data and items.
Called by loadByID when no custom storage loader is found, or when directly loading from database storage.
Parameters:
number id The inventory ID to load from database storage.boolean noCache Optional flag to bypass cache and force fresh loading.
Returns:
Deferred A deferred object that resolves to the fully loaded inventory instance with data and items.Example Usage:
lia.inventory.loadFromDefaultStorage(456, true):next(function(inventory)
-- Inventory loaded with fresh data, bypassing cache
end)
lia.inventory.instance(typeID, initialData)
Creates a new inventory instance with persistent storage initialization.
Called when creating new inventories that need database persistence, such as character inventories or storage containers.
Parameters:
string typeID The inventory type identifier.table initialData Optional initial data to store with the inventory instance.
Returns:
Deferred A deferred object that resolves to the created inventory instance after storage initialization.Example Usage:
lia.inventory.instance("grid", {char = 1}):next(function(inventory)
-- New inventory created and stored in database
end)
lia.inventory.loadAllFromCharID(charID)
Loads all inventories associated with a specific character ID.
Called during character loading to restore all inventory data for a character.
Parameters:
number|string charID The character ID to load inventories for (will be converted to number).Returns:
Deferred A deferred object that resolves to an array of loaded inventory instances.Example Usage:
lia.inventory.loadAllFromCharID(42):next(function(inventories)
for _, inv in ipairs(inventories) do
print("Loaded inventory:", inv.id)
end
end)
lia.inventory.deleteByID(id)
Permanently deletes an inventory and all its associated data from the database.
Called when removing inventories, such as during character deletion or storage cleanup.
Parameters:
number id The inventory ID to delete.Example Usage:
lia.inventory.deleteByID(123)
-- Inventory 123 and all its data/items are permanently removed
lia.inventory.cleanUpForCharacter(character)
Destroys all inventories associated with a character during cleanup.
Called during character deletion or when cleaning up character data to prevent memory leaks.
Parameters:
table character The character object whose inventories should be destroyed.Example Usage:
lia.inventory.cleanUpForCharacter(player:getChar())
-- All inventories for this character are destroyed
lia.inventory.checkOverflow(inv, character, oldW, oldH)
Checks for items that no longer fit in an inventory after resizing and moves them to overflow storage.
Called when inventory dimensions change (like when upgrading inventory size) to handle items that no longer fit.
Parameters:
table inv The inventory instance to check for overflow.table character The character object to store overflow items on.
number oldW The previous width of the inventory.
number oldH The previous height of the inventory.
Returns:
boolean True if overflow items were found and moved, false otherwise.Example Usage:
if lia.inventory.checkOverflow(inventory, player:getChar(), 5, 5) then
-- Items were moved to overflow storage
end
lia.inventory.registerStorage(model, data)
Registers a storage container configuration for entities with the specified model.
Called during gamemode initialization to define storage containers like lockers, crates, or other inventory-holding entities.
Parameters:
string model The model path of the entity that will have storage capability.table data Configuration table containing name, invType, invData, and other storage properties.
Returns:
table The registered storage data table.Example Usage:
lia.inventory.registerStorage("models/props_c17/lockers001a.mdl", {
name = "Locker",
invType = "grid",
invData = {w = 4, h = 6}
})
lia.inventory.getStorage(model)
Retrieves the storage configuration for a specific model.
Called when checking if an entity model has storage capabilities or retrieving storage properties.
Parameters:
string model The model path to look up storage configuration for.Returns:
table|nil The storage configuration table if found, nil otherwise.Example Usage:
local storage = lia.inventory.getStorage("models/props_c17/lockers001a.mdl")
if storage then
print("Storage name:", storage.name)
end
lia.inventory.registerTrunk(vehicleClass, data)
Registers a vehicle trunk configuration for vehicles with the specified class.
Called during gamemode initialization to define vehicle trunk storage capabilities.
Parameters:
string vehicleClass The vehicle class name that will have trunk capability.table data Configuration table containing name, invType, invData, and trunk-specific properties.
Returns:
table The registered trunk data table with trunk flags set.Example Usage:
lia.inventory.registerTrunk("vehicle_class", {
name = "Car Trunk",
invType = "grid",
invData = {w = 8, h = 4}
})
lia.inventory.getTrunk(vehicleClass)
Retrieves the trunk configuration for a specific vehicle class.
Called when checking if a vehicle class has trunk capabilities or retrieving trunk properties.
Parameters:
string vehicleClass The vehicle class name to look up trunk configuration for.Returns:
table|nil The trunk configuration table if found and it's a trunk, nil otherwise.Example Usage:
local trunk = lia.inventory.getTrunk("vehicle_class")
if trunk then
print("Trunk capacity:", trunk.invData.w, "x", trunk.invData.h)
end
lia.inventory.getAllTrunks()
Retrieves all registered trunk configurations.
Called when listing all available vehicle trunk types or for administrative purposes.
Returns:
table A table containing all registered trunk configurations keyed by vehicle class.Example Usage:
local trunks = lia.inventory.getAllTrunks()
for class, config in pairs(trunks) do
print("Trunk for", class, ":", config.name)
end
lia.inventory.getAllStorage(includeTrunks)
Retrieves all registered storage configurations, optionally excluding trunks.
Called when listing all available storage types or for administrative purposes.
Parameters:
boolean includeTrunks Optional flag to include (true) or exclude (false) trunk configurations. Defaults to true.Returns:
table A table containing all registered storage configurations, optionally filtered.Example Usage:
-- Get all storage including trunks
local allStorage = lia.inventory.getAllStorage(true)
-- Get only non-trunk storage
local storageOnly = lia.inventory.getAllStorage(false)
lia.inventory.show(inventory, parent)
Creates and displays an inventory panel for the specified inventory.
Called when opening inventory interfaces, such as character inventories, storage containers, or other inventory UIs.
Parameters:
table inventory The inventory instance to display in the panel.Panel parent Optional parent panel for the inventory panel.
Returns:
Panel The created inventory panel instance.Example Usage:
local panel = lia.inventory.show(myInventory)
-- Opens the inventory UI for myInventory
lia.inventory.showDual(inventory1, inventory2, parent)
Creates and displays two inventory panels side by side for dual inventory interactions.
Called when opening dual inventory interfaces, such as trading, transferring items between inventories, or accessing storage.
Parameters:
table inventory1 The first inventory instance to display.table inventory2 The second inventory instance to display.
Panel parent Optional parent panel for the inventory panels.
Returns:
table An array containing both created inventory panel instances {panel1, panel2}.Example Usage:
local panels = lia.inventory.showDual(playerInv, storageInv)
-- Opens dual inventory UI for trading between player and storage