Item
Comprehensive item registration, instantiation, and management system for the Lilia framework.
Overview
lia.item.get(identifier)
Purpose
Retrieves an item definition (base or regular item) by its unique identifier.
When Called
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)
Purpose
Retrieves an instanced item by its ID and determines its current location.
When Called
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)
Purpose
Retrieves an instanced item directly by its ID without location information.
When Called
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)
Purpose
Retrieves the data table of an instanced item by its ID.
When Called
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)
Purpose
Loads and registers an item from a file path by extracting the unique ID and registering it.
When Called
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/food.lua", nil, true)
lia.item.isItem(object)
Purpose
Checks if an object is a valid Lilia item instance.
When Called
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)
Purpose
Retrieves an inventory instance by its ID.
When Called
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)
Purpose
Adds a new item rarity tier with an associated color for visual identification.
When Called
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)
Purpose
Registers an item definition with the Lilia item system, setting up inheritance and default functions.
When Called
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)
Purpose
Queues an item for deferred registration and returns a placeholder that can access the item once registered.
When Called
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)
Purpose
Queues property overrides for an item that will be applied when the item is initialized.
When Called
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)
Purpose
Loads all items from a directory structure, organizing base items and regular items.
When Called
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)
Purpose
Creates a new item instance from an item definition with a specific ID.
When Called
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)
Purpose
Registers a new inventory type with specified dimensions.
When Called
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)
Purpose
Creates a new inventory instance for a character and syncs it with the appropriate player.
When Called
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)
Purpose
Creates a new inventory instance with specified dimensions and registers it.
When Called
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)
Purpose
Adds custom override data for weapon items during auto-generation.
When Called
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)
Purpose
Adds a weapon class to the blacklist to prevent it from being auto-generated as an item.
When Called
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)
Purpose
Sets data on an item instance by its ID and synchronizes the changes.
When Called
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)
Purpose
Creates a new item instance in the database and returns the created item.
When Called
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)
Purpose
Deletes an item instance by its ID from memory and/or database.
When Called
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)
Purpose
Loads item instances from the database by their IDs and recreates them in memory.
When Called
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)
Purpose
Creates and spawns an item entity in the world at the specified position.
When Called
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)
Purpose
Restores an inventory from the database and sets its dimensions.
When Called
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)
lia.item.saveWeaponOverrides(invID, w, h, callback)
Purpose
Restores an inventory from the database and sets its dimensions.
When Called
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)
lia.item.loadWeaponOverrides(invID, w, h, callback)
Purpose
Restores an inventory from the database and sets its dimensions.
When Called
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)