Item¶
Item definition, registration, instancing, inventory helper, rarity, and generated weapon/ammunition item utilities for Lilia.
Overview
lia.item.get(identifier)View Source
Purpose
Returns a registered base item or normal item definition by identifier.
Realm
Shared
Parameters
string identifier The unique ID of the item or base item to retrieve.
Returns
Item|nil The matching item definition, or nil if no registered item or base item exists for the identifier.
Example Usage
local itemDef = lia.item.get("water_bottle")
if itemDef then print(itemDef.name) end
lia.item.applyWeaponOverride(uniqueID)View Source
Purpose
Applies stored weapon override values to an already registered item definition.
Realm
Shared
Parameters
string uniqueID The unique ID or weapon class name of the generated weapon item to update.
Returns
nil This function does not return a value.
Example Usage
lia.item.addWeaponOverride("weapon_pistol", {name = "Sidearm"})
lia.item.applyWeaponOverride("weapon_pistol")
lia.item.getItemByID(itemID)View Source
Purpose
Finds an instantiated item by database ID and reports where the item currently exists.
Realm
Shared
Parameters
number itemID The database ID of the item instance to retrieve.
Returns
table|nil A table containing `item` and `location` when found, or nil when the item does not exist. string|nil An error message when the item cannot be found.
Example Usage
local result, err = lia.item.getItemByID(15)
if result then print(result.location) end
lia.item.getInstancedItemByID(itemID)View Source
Purpose
Returns an instantiated item directly from the item instance cache.
Realm
Shared
Parameters
number itemID The database ID of the item instance to retrieve.
Returns
Item|nil The item instance when it exists, or nil when it cannot be found. string|nil An error message when the item cannot be found.
Example Usage
local item, err = lia.item.getInstancedItemByID(15)
if item then print(item.uniqueID) end
lia.item.getItemDataByID(itemID)View Source
Purpose
Returns the data table stored on an instantiated item.
Realm
Shared
Parameters
number itemID The database ID of the item instance whose data should be returned.
Returns
table|nil The item data table when the item exists, or nil when it cannot be found. string|nil An error message when the item cannot be found.
Example Usage
local data = lia.item.getItemDataByID(15)
if data then print(data.x, data.y) end
lia.item.load(path, baseID, isBaseItem)View Source
Purpose
Loads an item file path by deriving its unique ID and registering it as an item or base item.
Realm
Shared
Parameters
string path The Lua file path to load.
string baseID optional The base item unique ID to inherit from, if any.
boolean isBaseItem optional Whether the file should be registered as a base item.
Returns
nil This function does not return a value.
Example Usage
lia.item.load("lilia/gamemode/items/sh_example.lua")
lia.item.load("lilia/gamemode/items/base/sh_weapons.lua", nil, true)
lia.item.isItem(object)View Source
lia.item.getInv(invID)View Source
Purpose
Returns a registered inventory instance by inventory ID.
Realm
Shared
Parameters
number invID The inventory ID to retrieve.
Returns
Inventory|nil The inventory instance, or nil if no inventory is loaded for the ID.
Example Usage
local inventory = lia.item.getInv(item.invID)
if inventory then print(inventory:getID()) end
lia.item.addRarities(name, color)View Source
lia.item.register(uniqueID, baseID, isBaseItem, path, luaGenerated)View Source
Purpose
Registers an item definition or base item and prepares inherited hooks, functions, localization, and overrides.
Realm
Shared
Parameters
string uniqueID The unique ID to register.
string baseID optional The base item unique ID to inherit from.
boolean isBaseItem optional Whether the registration target is a base item.
string path optional The Lua file path to include for the item definition.
boolean luaGenerated optional Whether the item is being generated from Lua data instead of loaded from a file.
Returns
Item The registered item definition.
Example Usage
local itemDef = lia.item.register("example", "base_entities", false, nil, true)
itemDef.name = "Example Item"
lia.item.localizeDefinition(itemDef)View Source
Purpose
Resolves localization tokens on an item definition and its item function names or tips.
Realm
Shared
Parameters
Item|table itemDef The item definition to localize.
Returns
nil This function does not return a value.
Example Usage
local itemDef = lia.item.get("water_bottle")
lia.item.localizeDefinition(itemDef)
lia.item.registerItem(id, base, properties)View Source
Purpose
Queues a Lua-generated item registration to be finalized after modules initialize.
Realm
Shared
Parameters
string id The unique ID of the item to register.
string base optional The base item unique ID to inherit from.
table properties optional Properties to copy onto the registered item definition.
Returns
table A placeholder item table that proxies to the actual registered item once it exists.
Example Usage
lia.item.registerItem("example_entity", "base_entities", {
name = "Example Entity",
entityid = "example_entity"
})
lia.item.overrideItem(uniqueID, overrides)View Source
Purpose
Queues overrides for an item definition to be applied after modules initialize.
Realm
Shared
Parameters
string uniqueID The unique ID of the item to override.
table overrides The fields, functions, hooks, or post hooks to merge into the item definition.
Returns
nil This function does not return a value.
Example Usage
lia.item.overrideItem("water_bottle", {
name = "Clean Water"
})
lia.item.loadFromDir(directory)View Source
Purpose
Loads base item files, category item files, and direct item files from an item directory.
Realm
Shared
Parameters
string directory The Lua directory containing item files and optional base subdirectory.
Returns
nil This function does not return a value.
Example Usage
lia.item.loadFromDir("lilia/gamemode/items")
lia.item.new(uniqueID, id)View Source
Purpose
Creates or returns an item instance for a registered item definition and database ID.
Realm
Shared
Parameters
string uniqueID The unique ID of the registered item definition.
number|string id The item database ID, converted to a number when possible.
Returns
Item The item instance for the provided unique ID and ID.
Example Usage
local item = lia.item.new("water_bottle", 15)
print(item:getID())
lia.item.registerInv(invType, w, h)View Source
Purpose
Registers a grid inventory type with fixed width and height accessors.
Realm
Shared
Parameters
string invType The inventory type name to register.
number w The inventory width.
number h The inventory height.
Returns
nil This function does not return a value.
Example Usage
lia.item.registerInv("small_bag", 4, 4)
lia.item.newInv(owner, invType, callback)View Source
Purpose
Creates a new inventory instance for a character owner and optionally syncs it to the owning player.
Realm
Shared
Parameters
number owner optional The character ID that owns the inventory.
string invType The inventory type to instantiate.
function callback optional Called with the created inventory after it is available.
Returns
nil This function does not return a value.
Example Usage
lia.item.newInv(charID, "grid", function(inventory)
print(inventory:getID())
end)
lia.item.createInv(w, h, id)View Source
Purpose
Creates a grid inventory instance immediately using the provided dimensions and ID.
Realm
Shared
Parameters
number w The inventory width.
number h The inventory height.
number id The inventory ID to assign to the new instance.
Returns
Inventory The created grid inventory instance.
Example Usage
local inventory = lia.item.createInv(4, 4, 1001)
lia.item.addWeaponOverride(className, data)View Source
Purpose
Stores item definition override data for a generated weapon item class.
Realm
Shared
Parameters
string className The weapon class or generated item unique ID to override.
table data The override fields to apply to the generated item definition.
Returns
nil This function does not return a value.
Example Usage
lia.item.addWeaponOverride("weapon_pistol", {
width = 1,
height = 1
})
lia.item.addWeaponToBlacklist(className)View Source
lia.item.applyRuntimeOverridePath(wepTable, dotPath, value)View Source
Purpose
Applies a value to a nested field on a weapon table using a dot-separated path.
Realm
Shared
Parameters
table wepTable The weapon table to modify.
string dotPath The dot-separated nested field path to write.
any value The value to assign at the destination path.
Returns
boolean True when the value was applied, otherwise false.
Example Usage
local ok = lia.item.applyRuntimeOverridePath(SWEP, "Primary.Damage", 35)
lia.item.getRuntimeValue(wepTable, dotPath)View Source
Purpose
Reads a nested value from a weapon table using a dot-separated path.
Realm
Shared
Parameters
table wepTable The weapon table to read from.
string dotPath The dot-separated nested field path to read.
Returns
any|nil The nested value when the path exists, or nil when it cannot be resolved.
Example Usage
local damage = lia.item.getRuntimeValue(SWEP, "Primary.Damage")
lia.item.setItemDataByID(itemID, key, value, receivers, noSave, noCheckEntity)View Source
Purpose
Sets a data key on an instantiated item by database ID.
Realm
Server
Parameters
number itemID The database ID of the item instance to update.
string key The data key to set.
any value The value to store.
Player|table receivers optional Optional networking recipients for the data update.
boolean noSave optional Whether to skip saving the data change.
boolean noCheckEntity optional Whether to skip entity validity checks during the update.
Returns
boolean True when the data was set, or false when the item was not found. string|nil An error message when the item cannot be found.
Example Usage
local ok, err = lia.item.setItemDataByID(15, "uses", 2)
lia.item.instance(index, uniqueID, itemData, x, y, callback)View Source
Purpose
Creates a persistent item database record and item instance.
Realm
Server
Parameters
number|string index optional The inventory ID for the new item, or the unique ID when using the shorthand overload.
string|table uniqueID optional The item unique ID, or item data when using the shorthand overload.
table itemData optional Initial data to store on the item.
number x optional The item inventory X position.
number y optional The item inventory Y position.
function callback optional Called with the created item after the database insert completes.
Returns
deferred A deferred object that resolves with the created item or rejects with an error message.
Example Usage
lia.item.instance(invID, "water_bottle", {}, 1, 1, function(item)
print(item:getID())
end)
lia.item.deleteByID(id)View Source
lia.item.loadItemByID(itemIndex)View Source
Purpose
Loads one or more items from the database into the item instance cache.
Realm
Server
Parameters
number|table itemIndex A single item ID or a table of item IDs to restore.
Returns
nil This function does not return a value.
Example Usage
lia.item.loadItemByID(15)
lia.item.loadItemByID({15, 16, 17})
lia.item.spawn(uniqueID, position, callback, angles, data)View Source
Purpose
Creates an item instance and spawns it into the world.
Realm
Server
Parameters
string uniqueID The unique ID of the item definition to spawn.
Vector position The world position where the item should be spawned.
function|Angle callback optional Called with the spawned item, or used as angles when no callback is provided.
Angle|table angles optional The spawn angles, or item data when passed through the angle overload.
table data optional Initial data to store on the spawned item.
Returns
deferred|nil A deferred object when no callback function is supplied, otherwise nil.
Example Usage
lia.item.spawn("water_bottle", client:GetPos(), function(item)
if item then print(item:getID()) end
end)
lia.item.restoreInv(invID, w, h, callback)View Source
Purpose
Loads an inventory by ID, restores its dimensions, and optionally passes it to a callback.
Realm
Server
Parameters
number invID The inventory ID to load.
number w The restored inventory width.
number h The restored inventory height.
function callback optional Called with the restored inventory when it is available.
Returns
nil This function does not return a value.
Example Usage
lia.item.restoreInv(invID, 6, 4, function(inventory)
inventory:sync(client)
end)
lia.item.loadWeaponOverrides()View Source
Purpose
Loads saved generated weapon item override data and applies it to registered item definitions.
Realm
Server
Returns
nil This function does not return a value.
Example Usage
lia.item.loadWeaponOverrides()
lia.item.loadWeaponRuntimeOverrides()View Source
Purpose
Loads saved runtime weapon stat overrides and applies them to stored weapon tables.
Realm
Server
Returns
nil This function does not return a value.
Example Usage
lia.item.loadWeaponRuntimeOverrides()
Hooks
Library-specific hooks documented for this library.
CanPlayerModifyConfig(client)View Source
Purpose
Controls whether the local player can see the generated weapon item configuration page.
Realm
Client
Parameters
Player client The player opening the configuration interface.
Returns
boolean|nil Return false to hide the configuration page. Return nil or true to allow it.
GetWeaponName(weaponTable)View Source
Purpose
Allows modules to provide a display name for automatically generated weapon items.
Realm
Shared
Parameters
table weaponTable The weapon table being converted into an item definition.
Returns
string|nil Return a string to override the generated item name, or nil to use the default name source.
HandleItemTransferRequest(client, itemID, x, y, targetInvID)View Source
Purpose
Handles the actual transfer when a player gives an item forward to another player.
Realm
Server
Parameters
Player client The player initiating the transfer.
number itemID The database ID of the item being transferred.
number x optional The destination inventory X position, if one is specified.
number y optional The destination inventory Y position, if one is specified.
number targetInvID The inventory ID receiving the item.
Returns
deferred|nil Return a deferred transfer result to continue the give-forward flow, or nil to stop handling.
InitializedItems()View Source
ItemDefaultFunctions(functions)View Source
Purpose
Allows modules to inspect or modify the default item action table during item registration.
Realm
Shared
Parameters
table functions The mutable table of item action definitions.
OnItemCreated(item)View Source
Purpose
Runs after an item instance table is created from a registered item definition.
Realm
Shared
Parameters
Item item The newly created item instance.
OnItemOverridden(itemDef, overrides)View Source
OnItemRegistered(itemDef)View Source
Purpose
Runs after an item definition or base item has been registered and localized.
Realm
Shared
Parameters
Item itemDef The registered item definition table.