Item Meta
Item management system for the Lilia framework.
Overview
The item meta table provides comprehensive functionality for managing item data, properties, and operations in the Lilia framework. It handles item creation, data persistence, inventory management, stacking, rotation, and item-specific operations. The meta table operates on both server and client sides, with the server managing item storage and validation while the client provides item data access and display. It includes integration with the inventory system for item storage, database system for item persistence, and rendering system for item display. The meta table ensures proper item data synchronization, quantity management, rotation handling, and comprehensive item lifecycle management from creation to destruction.
isRotated()
Reports whether the item is stored in a rotated state.
Use when calculating grid dimensions or rendering the item icon.
Returns:
boolean True if the item is rotated.Example Usage:
if item:isRotated() then swapDims() end
getWidth()
Returns the item's width considering rotation and defaults.
Use when placing the item into a grid inventory.
Returns:
number Width in grid cells.Example Usage:
local w = item:getWidth()
getHeight()
Returns the item's height considering rotation and defaults.
Use when calculating how much vertical space an item needs.
Returns:
number Height in grid cells.Example Usage:
local h = item:getHeight()
getQuantity()
Returns the current stack quantity for this item.
Use when showing stack counts or validating transfers.
Returns:
number Quantity within the stack.Example Usage:
local count = item:getQuantity()
tostring()
Builds a readable string identifier for the item.
Use for logging, debugging, or console output.
Returns:
string Formatted identifier including uniqueID and item id.Example Usage:
print(item:tostring())
getID()
Retrieves the numeric identifier for this item instance.
Use when persisting, networking, or comparing items.
Returns:
number Unique item ID.Example Usage:
local id = item:getID()
getModel()
Returns the model path assigned to this item.
Use when spawning an entity or rendering the item icon.
Returns:
string Model file path.Example Usage:
local mdl = item:getModel()
getSkin()
Returns the skin index assigned to this item.
Use when spawning the entity or applying cosmetics.
Returns:
number|nil Skin index or nil when not set.Example Usage:
local skin = item:getSkin()
getBodygroups()
Provides the bodygroup configuration for the item model.
Use when spawning or rendering to ensure correct bodygroups.
Returns:
table Key-value pairs of bodygroup indexes to values.Example Usage:
local groups = item:getBodygroups()
getPrice()
Calculates the current sale price for the item.
Use when selling, buying, or displaying item cost.
Returns:
number Price value, possibly adjusted by calcPrice.Example Usage:
local cost = item:getPrice()
call(method, client, entity)
Invokes an item method while temporarily setting context.
Use when you need to call an item function with player/entity context.
Parameters:
string method Name of the item method to invoke.Player client optional Player to treat as the caller.
Entity entity optional Entity representing the item.
Returns:
any Return values from the invoked method.Example Usage:
item:call("onUse", ply, ent)
getOwner()
Attempts to find the player that currently owns this item.
Use when routing notifications or networking to the item owner.
Returns:
Player|nil Owning player if found.Example Usage:
local owner = item:getOwner()
getData(key, default)
Reads a stored data value from the item or its entity.
Use for custom item metadata such as durability or rotation.
Parameters:
string key Data key to read.any default Value to return when the key is missing.
Returns:
any Stored value or default.Example Usage:
local durability = item:getData("durability", 100)
getAllData()
Returns a merged table of all item data, including entity netvars.
Use when syncing the entire data payload to clients.
Returns:
table Combined data table.Example Usage:
local data = item:getAllData()
hook(name, func)
Registers a pre-run hook for an item interaction.
Use when adding custom behavior before an action executes.
Parameters:
string name Hook name to bind.function func Callback to execute.
Example Usage:
item:hook("use", function(itm) end)
postHook(name, func)
Registers a post-run hook for an item interaction.
Use when you need to react after an action completes.
Parameters:
string name Hook name to bind.function func Callback to execute with results.
Example Usage:
item:postHook("use", function(itm, result) end)
onRegistered()
Performs setup tasks after an item definition is registered.
Automatically invoked once the item type is loaded.
Example Usage:
item:onRegistered()
print(detail)
Prints a concise or detailed identifier for the item.
Use during debugging or admin commands.
Parameters:
boolean detail Include owner and grid info when true.Example Usage:
item:print(true)
printData()
Outputs item metadata and all stored data fields.
Use for diagnostics to inspect an item's state.
Example Usage:
item:printData()
getName()
Returns the display name of the item.
Use for UI labels, tooltips, and logs.
Returns:
string Item name.Example Usage:
local name = item:getName()
getDesc()
Returns the description text for the item.
Use in tooltips or inventory details.
Returns:
string Item description.Example Usage:
local desc = item:getDesc()
removeFromInventory(preserveItem)
Removes the item from its current inventory instance.
Use when dropping, deleting, or transferring the item out.
Parameters:
boolean preserveItem When true, keeps the instance for later use.Returns:
Promise Deferred resolution for removal completion.Example Usage:
item:removeFromInventory():next(function() end)
delete()
Deletes the item record from storage after destroying it in-game.
Use when an item should be permanently removed.
Returns:
Promise Resolves after the database delete and callbacks run.Example Usage:
item:delete()
remove()
Removes the world entity, inventory reference, and database entry.
Use when the item is consumed or otherwise removed entirely.
Returns:
Promise Resolves once removal and deletion complete.Example Usage:
item:remove()
destroy()
Broadcasts item deletion to clients and frees the instance.
Use internally before removing an item from memory.
Example Usage:
item:destroy()
onDisposed()
Hook called after an item is destroyed; intended for overrides.
Automatically triggered when the item instance is disposed.
Example Usage:
function ITEM:onDisposed() end
onDisposed()
Hook called after an item is destroyed; intended for overrides.
Automatically triggered when the item instance is disposed.
Example Usage:
function ITEM:onDisposed() end
getEntity()
Finds the world entity representing this item instance.
Use when needing the spawned entity from the item data.
Returns:
Entity|nil Spawned item entity if present.Example Usage:
local ent = item:getEntity()
spawn(position, angles)
Spawns a world entity for this item at the given position and angle.
Use when dropping an item into the world.
Parameters:
Vector|table|Entity position Where to spawn, or the player dropping the item.Angle|Vector|table angles optional Orientation for the spawned entity.
Returns:
Entity|nil Spawned entity on success.Example Usage:
local ent = item:spawn(ply, Angle(0, 0, 0))
transfer(newInventory, bBypass)
Moves the item into another inventory if access rules allow.
Use when transferring items between containers or players.
Parameters:
Inventory newInventory Destination inventory.boolean bBypass Skip access checks when true.
Returns:
boolean True if the transfer was initiated.Example Usage:
item:transfer(otherInv)
onInstanced()
Hook called when a new item instance is created.
Automatically invoked after instancing; override to customize.
Example Usage:
function ITEM:onInstanced() end
onInstanced()
Hook called when a new item instance is created.
Automatically invoked after instancing; override to customize.
Example Usage:
function ITEM:onInstanced() end
onSync(recipient)
Hook called after the item data is synchronized to clients.
Triggered by sync calls; override for custom behavior.
Parameters:
Player recipient optional The player who received the sync, or nil for broadcast.Example Usage:
function ITEM:onSync(ply) end
onSync(recipient)
Hook called after the item data is synchronized to clients.
Triggered by sync calls; override for custom behavior.
Parameters:
Player recipient optional The player who received the sync, or nil for broadcast.Example Usage:
function ITEM:onSync(ply) end
onRemoved()
Hook called after the item has been removed from the world/inventory.
Automatically invoked once deletion finishes.
Example Usage:
function ITEM:onRemoved() end
onRemoved()
Hook called after the item has been removed from the world/inventory.
Automatically invoked once deletion finishes.
Example Usage:
function ITEM:onRemoved() end
onRestored()
Hook called after an item is restored from persistence.
Automatically invoked after loading an item from the database.
Example Usage:
function ITEM:onRestored() end
onRestored()
Hook called after an item is restored from persistence.
Automatically invoked after loading an item from the database.
Example Usage:
function ITEM:onRestored() end
sync(recipient)
Sends this item instance to a recipient or all clients for syncing.
Use after creating or updating an item instance.
Parameters:
Player recipient optional Specific player to sync; broadcasts when nil.Example Usage:
item:sync(ply)
setData(key, value, receivers, noSave, noCheckEntity)
Sets a custom data value on the item, networking and saving as needed.
Use when updating item metadata that clients or persistence require.
Parameters:
string key Data key to set.any value Value to store.
Player|table receivers optional Targets to send the update to; defaults to owner.
boolean noSave Skip database write when true.
boolean noCheckEntity Skip updating the world entity netvar when true.
Example Usage:
item:setData("durability", 80, item:getOwner())
addQuantity(quantity, receivers, noCheckEntity)
Increases the item quantity by the given amount.
Use for stacking items or consuming partial quantities.
Parameters:
number quantity Amount to add (can be negative).Player|table receivers optional Targets to notify; defaults to owner.
boolean noCheckEntity Skip updating the entity netvar when true.
Example Usage:
item:addQuantity(-1, ply)
setQuantity(quantity, receivers, noCheckEntity)
Sets the item quantity, updating entities, clients, and storage.
Use after splitting stacks or consuming items.
Parameters:
number quantity New stack amount.Player|table receivers optional Targets to notify; defaults to owner.
boolean noCheckEntity Skip updating the world entity netvar when true.
Example Usage:
item:setQuantity(5, ply)
interact(action, client, entity, data)
Handles an item interaction action, running hooks and callbacks.
Use when a player selects an action from an item's context menu.
Parameters:
string action Action identifier from the item's functions table.Player client Player performing the action.
Entity entity optional World entity representing the item, if any.
any data Additional data for multi-option actions.
Returns:
boolean True if the action was processed; false otherwise.Example Usage:
item:interact("use", ply, ent)
getCategory()
Returns the item's localized category label.
Use when grouping or displaying items by category.
Returns:
string Localized category name, or "misc" if undefined.Example Usage:
local category = item:getCategory()