Item Library
Comprehensive item registration, instantiation, and management system for the Lilia framework.
Overview
The item library provides comprehensive functionality for managing items in the Lilia framework. It handles item registration, instantiation, inventory management, and item operations such as dropping, taking, rotating, and transferring items between players. The library operates on both server and client sides, with server-side functions handling database operations, item spawning, and data persistence, while client-side functions manage item interactions and UI operations. It includes automatic weapon and ammunition generation from Garry's Mod weapon lists, inventory type registration, and item entity management. The library ensures proper item lifecycle management from creation to deletion, with support for custom item functions, hooks, and data persistence.
lia.item.get(identifier)
Retrieves an item definition (base or regular item) by its unique identifier.
Called when needing to access item definitions for registration, validation, or manipulation.
Parameters:
string identifier The unique identifier of the item to retrieve.Returns:
table or nil The item definition table if found, nil if not found.Example Usage:
local weaponItem = lia.item.get("weapon_pistol")
if weaponItem then
print("Found weapon:", weaponItem.name)
end
lia.item.getItemByID(itemID)
Retrieves an instanced item by its ID and determines its current location.
Called when needing to access specific item instances, typically for manipulation or inspection.
Parameters:
number itemID The unique ID of the instanced item to retrieve.Returns:
table or nil, string A table containing the item and its location ("inventory", "world", or "unknown"), or nil and an error message if not found.Example Usage:
local itemData, errorMsg = lia.item.getItemByID(123)
if itemData then
print("Item found at:", itemData.location)
-- Use itemData.item for item operations
else
print("Error:", errorMsg)
end
lia.item.getInstancedItemByID(itemID)
Retrieves an instanced item directly by its ID without location information.
Called when needing to access item instances for direct manipulation without location context.
Parameters:
number itemID The unique ID of the instanced item to retrieve.Returns:
table or nil, string The item instance if found, or nil and an error message if not found.Example Usage:
local item, errorMsg = lia.item.getInstancedItemByID(123)
if item then
item:setData("customValue", "example")
else
print("Error:", errorMsg)
end
lia.item.getItemDataByID(itemID)
Retrieves the data table of an instanced item by its ID.
Called when needing to access or inspect the custom data stored on an item instance.
Parameters:
number itemID The unique ID of the instanced item to retrieve data from.Returns:
table or nil, string The item's data table if found, or nil and an error message if not found.Example Usage:
local data, errorMsg = lia.item.getItemDataByID(123)
if data then
print("Item durability:", data.durability or "N/A")
else
print("Error:", errorMsg)
end
lia.item.load(path, baseID, isBaseItem)
Loads and registers an item from a file path by extracting the unique ID and registering it.
Called during item loading process to register items from files in the items directory.
Parameters:
string path The file path of the item to load.string, optional baseID The base item ID to inherit from.
boolean, optional isBaseItem Whether this is a base item definition.
Example Usage:
-- Load a regular item
lia.item.load("lilia/gamemode/items/food_apple.lua")
-- Load a base item
lia.item.load("lilia/gamemode/items/base/sh_food.lua", nil, true)
lia.item.isItem(object)
Checks if an object is a valid Lilia item instance.
Called to validate that an object is an item before performing item-specific operations.
Parameters:
any object The object to check if it's an item.Returns:
boolean True if the object is a valid item, false otherwise.Example Usage:
local someObject = getSomeObject()
if lia.item.isItem(someObject) then
someObject:setData("used", true)
else
print("Object is not an item")
end
lia.item.getInv(invID)
Retrieves an inventory instance by its ID.
Called when needing to access inventory objects for item operations or inspection.
Parameters:
number invID The unique ID of the inventory to retrieve.Returns:
table or nil The inventory instance if found, nil if not found.Example Usage:
local inventory = lia.item.getInv(5)
if inventory then
print("Inventory size:", inventory:getWidth(), "x", inventory:getHeight())
end
lia.item.addRarities(name, color)
Adds a new item rarity tier with an associated color for visual identification.
Called during item system initialization to define available rarity levels for items.
Parameters:
string name The name of the rarity tier (e.g., "Common", "Rare", "Legendary").Color color The color associated with this rarity tier.
Example Usage:
lia.item.addRarities("Mythical", Color(255, 0, 255))
lia.item.addRarities("Divine", Color(255, 215, 0))
lia.item.register(uniqueID, baseID, isBaseItem, path, luaGenerated)
Registers an item definition with the Lilia item system, setting up inheritance and default functions.
Called during item loading to register item definitions, either from files or programmatically generated.
Parameters:
string uniqueID The unique identifier for the item.string, optional baseID The base item ID to inherit from (defaults to lia.meta.item).
boolean, optional isBaseItem Whether this is a base item definition.
string, optional path The file path for loading the item (used for shared loading).
boolean, optional luaGenerated Whether the item is generated programmatically rather than loaded from a file.
Returns:
table The registered item definition table.Example Usage:
-- Register a base item
lia.item.register("base_weapon", nil, true, "path/to/base_weapon.lua")
-- Register a regular item
lia.item.register("weapon_pistol", "base_weapon", false, "path/to/weapon_pistol.lua")
lia.item.registerItem(id, base, properties)
Queues an item for deferred registration and returns a placeholder that can access the item once registered.
Called during item system initialization to register items that will be created later, such as auto-generated weapons or ammunition items.
Parameters:
string id The unique identifier for the item to register.string, optional base The base item ID to inherit from.
table, optional properties A table of properties to apply to the item when it is registered.
Returns:
table A placeholder object that can access the actual item properties once registration is complete.Example Usage:
-- Queue a weapon item for registration
local weaponPlaceholder = lia.item.registerItem("weapon_pistol", "base_weapons", {
name = "Custom Pistol",
width = 2,
height = 1
})
-- The actual item will be registered when InitializedModules hook runs
lia.item.overrideItem(uniqueID, overrides)
Queues property overrides for an item that will be applied when the item is initialized.
Called during item system setup to modify item properties before they are finalized.
Parameters:
string uniqueID The unique ID of the item to override.table overrides A table of properties to override on the item.
Example Usage:
lia.item.overrideItem("weapon_pistol", {
name = "Custom Pistol",
width = 2,
height = 1,
price = 500
})
lia.item.loadFromDir(directory)
Loads all items from a directory structure, organizing base items and regular items.
Called during gamemode initialization to load all item definitions from the items directory.
Parameters:
string directory The directory path containing the item files to load.Example Usage:
-- Load all items from the gamemode's items directory
lia.item.loadFromDir("lilia/gamemode/items")
lia.item.new(uniqueID, id)
Creates a new item instance from an item definition with a specific ID.
Called when instantiating items from the database or creating new items programmatically.
Parameters:
string uniqueID The unique ID of the item definition to instantiate.number id The unique instance ID for this item.
Returns:
table The newly created item instance.Example Usage:
-- Create a new pistol item instance
local pistol = lia.item.new("weapon_pistol", 123)
pistol:setData("durability", 100)
lia.item.registerInv(invType, w, h)
Registers a new inventory type with specified dimensions.
Called during inventory system initialization to define different inventory types.
Parameters:
string invType The unique type identifier for this inventory.number w The width of the inventory in grid units.
number h The height of the inventory in grid units.
Example Usage:
-- Register a backpack inventory type
lia.item.registerInv("backpack", 4, 6)
-- Register a safe inventory type
lia.item.registerInv("safe", 8, 8)
lia.item.newInv(owner, invType, callback)
Creates a new inventory instance for a character and syncs it with the appropriate player.
Called when creating new inventories for characters, such as during character creation or item operations.
Parameters:
number owner The character ID that owns this inventory.string invType The type of inventory to create.
function, optional callback Function called when the inventory is created and ready.
Example Usage:
-- Create a backpack inventory for character ID 5
lia.item.newInv(5, "backpack", function(inventory)
print("Backpack created with ID:", inventory:getID())
end)
lia.item.createInv(w, h, id)
Creates a new inventory instance with specified dimensions and registers it.
Called when creating inventories programmatically, such as for containers or special storage.
Parameters:
number w The width of the inventory in grid units.number h The height of the inventory in grid units.
number id The unique ID for this inventory instance.
Returns:
table The created inventory instance.Example Usage:
-- Create a 4x6 container inventory
local container = lia.item.createInv(4, 6, 1001)
print("Container created with ID:", container.id)
lia.item.addWeaponOverride(className, data)
Adds custom override data for weapon items during auto-generation.
Called during weapon item generation to customize properties of specific weapons.
Parameters:
string className The weapon class name to override.table data The override data containing weapon properties.
Example Usage:
lia.item.addWeaponOverride("weapon_pistol", {
name = "Custom Pistol",
width = 2,
height = 1,
price = 500,
model = "models/weapons/custom_pistol.mdl"
})
lia.item.addWeaponToBlacklist(className)
Adds a weapon class to the blacklist to prevent it from being auto-generated as an item.
Called during weapon generation setup to exclude certain weapons from item creation.
Parameters:
string className The weapon class name to blacklist.Example Usage:
-- Prevent admin tools from being generated as items
lia.item.addWeaponToBlacklist("weapon_physgun")
lia.item.addWeaponToBlacklist("gmod_tool")
lia.item.setItemDataByID(itemID, key, value, receivers, noSave, noCheckEntity)
Sets data on an item instance by its ID and synchronizes the changes.
Called when needing to modify item data server-side and sync to clients.
Parameters:
number itemID The unique ID of the item instance.string key The data key to set.
any value The value to set for the key.
table, optional receivers Specific players to sync the data to.
boolean, optional noSave Whether to skip saving to database.
boolean, optional noCheckEntity Whether to skip entity validation.
Returns:
boolean, string True if successful, false and error message if failed.Example Usage:
local success, errorMsg = lia.item.setItemDataByID(123, "durability", 75)
if success then
print("Item durability updated")
else
print("Error:", errorMsg)
end
lia.item.instance(index, uniqueID, itemData, x, y, callback)
Creates a new item instance in the database and returns the created item.
Called when creating new items that need to be persisted to the database.
Parameters:
number|string index The inventory ID or unique ID if first parameter is string.string|table uniqueID The item definition unique ID or item data if index is string.
table, optional itemData The item data to set on creation.
number, optional x The X position in inventory.
number, optional y The Y position in inventory.
function, optional callback Function called when item is created.
Returns:
table A deferred promise that resolves with the created item.Example Usage:
-- Create a pistol in inventory 5 at position 1,1
lia.item.instance(5, "weapon_pistol", {}, 1, 1):next(function(item)
print("Created item with ID:", item:getID())
end)
lia.item.deleteByID(id)
Deletes an item instance by its ID from memory and/or database.
Called when permanently removing items from the game world.
Parameters:
number id The unique ID of the item to delete.Example Usage:
-- Delete item with ID 123
lia.item.deleteByID(123)
lia.item.loadItemByID(itemIndex)
Loads item instances from the database by their IDs and recreates them in memory.
Called during server startup or when needing to restore items from the database.
Parameters:
number|table itemIndex Single item ID or array of item IDs to load.Example Usage:
-- Load a single item
lia.item.loadItemByID(123)
-- Load multiple items
lia.item.loadItemByID({123, 456, 789})
lia.item.spawn(uniqueID, position, callback, angles, data)
Creates and spawns an item entity in the world at the specified position.
Called when dropping items or creating item entities in the game world.
Parameters:
string uniqueID The unique ID of the item to spawn.Vector position The position to spawn the item at.
function, optional callback Function called when item is spawned.
Angle, optional angles The angles to set on the spawned item.
table, optional data The item data to set on creation.
Returns:
table or nil A deferred promise that resolves with the spawned item, or nil if synchronous.Example Usage:
-- Spawn a pistol at a position
lia.item.spawn("weapon_pistol", Vector(0, 0, 0), function(item)
print("Spawned item:", item:getName())
end)
lia.item.restoreInv(invID, w, h, callback)
Restores an inventory from the database and sets its dimensions.
Called when loading saved inventories from the database.
Parameters:
number invID The unique ID of the inventory to restore.number w The width of the inventory.
number h The height of the inventory.
function, optional callback Function called when inventory is restored.
Example Usage:
-- Restore a 4x6 inventory
lia.item.restoreInv(5, 4, 6, function(inventory)
print("Restored inventory with", inventory:getItemCount(), "items")
end)