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

📋 Purpose

Checks if the item is currently rotated in the inventory grid

⏰ When Called

When determining item dimensions or display orientation

↩️ Returns

• Boolean indicating if the item is rotated

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    if item:isRotated() then
        print("Item is rotated")
    end

📊 Medium Complexity

    local width = item:isRotated() and item:getHeight() or item:getWidth()
    local height = item:isRotated() and item:getWidth() or item:getHeight()

⚙️ High Complexity

    local function getItemDisplaySize(item)
        if item:isRotated() then
            return item:getHeight(), item:getWidth()
        else
            return item:getWidth(), item:getHeight()
        end
    end
    local displayW, displayH = getItemDisplaySize(myItem)

---

getWidth

📋 Purpose

Gets the current width of the item considering rotation

⏰ When Called

When determining item grid space requirements or display size

↩️ Returns

• Number representing the item's width in grid units

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    local width = item:getWidth()

📊 Medium Complexity

    if item:getWidth() > maxWidth then
        print("Item too wide for slot")
    end

⚙️ High Complexity

    local function canPlaceItem(inventory, item, x, y)
        local width = item:getWidth()
        local height = item:getHeight()
        return inventory:canPlaceAt(x, y, width, height)
    end
    if canPlaceItem(myInventory, myItem, 1, 1) then
        inventory:placeItem(myItem, 1, 1)
    end

---

getHeight

📋 Purpose

Gets the current height of the item considering rotation

⏰ When Called

When determining item grid space requirements or display size

↩️ Returns

• Number representing the item's height in grid units

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    local height = item:getHeight()

📊 Medium Complexity

    local totalSpace = item:getWidth() * item:getHeight()

⚙️ High Complexity

    local function calculateInventorySpace(items)
        local totalWidth = 0
        local totalHeight = 0
        for _, item in ipairs(items) do
            totalWidth = math.max(totalWidth, item:getWidth())
            totalHeight = totalHeight + item:getHeight()
        end
        return totalWidth, totalHeight
    end
    local neededW, neededH = calculateInventorySpace(selectedItems)

---

getQuantity

📋 Purpose

Gets the current quantity of the item

⏰ When Called

When checking how many of this item exist, for display or validation

↩️ Returns

• Number representing the item's current quantity

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    local count = item:getQuantity()

📊 Medium Complexity

    if item:getQuantity() >= requiredAmount then
        useItem(item)
    end

⚙️ High Complexity

    local function calculateTotalValue(items)
        local total = 0
        for _, item in ipairs(items) do
            local quantity = item:getQuantity()
            local value = item:getPrice() or 0
            total = total + (quantity * value)
        end
        return total
    end
    local inventoryValue = calculateTotalValue(playerInventory:getItems())

---

tostring

📋 Purpose

Creates a string representation of the item for debugging/logging

⏰ When Called

For logging, debugging, or console output

↩️ Returns

• String representation of the item

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    print(item:tostring())

📊 Medium Complexity

    lia.information("Processing " .. item:tostring())

⚙️ High Complexity

    local function logItemTransaction(item, action, player)
        local logEntry = string.format("[%s] %s performed %s on %s",
            os.date("%H:%M:%S"),
            player:GetName(),
            action,
            item:tostring()
        )
        file.Append("item_transactions.txt", logEntry .. "\n")
    end
    logItemTransaction(myItem, "used", player)

---

getID

📋 Purpose

Gets the unique instance ID of this item

⏰ When Called

When you need to reference this specific item instance

↩️ Returns

• Number representing the item's unique ID

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    local itemID = item:getID()

📊 Medium Complexity

    if item:getID() == targetID then
        selectItem(item)
    end

⚙️ High Complexity

    local function findItemByID(inventory, targetID)
        for _, item in pairs(inventory:getItems()) do
            if item:getID() == targetID then
                return item
            end
        end
        return nil
    end
    local foundItem = findItemByID(playerInventory, 12345)

---

getModel

📋 Purpose

Gets the model path for the item

⏰ When Called

When displaying the item or creating item entities

↩️ Returns

• String representing the item's model path

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    local model = item:getModel()

📊 Medium Complexity

    if item:getModel() then
        entity:SetModel(item:getModel())
    end

⚙️ High Complexity

    local function createItemEntity(item, position)
        local ent = ents.Create("prop_physics")
        ent:SetModel(item:getModel() or "models/error.mdl")
        ent:SetPos(position)
        ent:Spawn()
        if item:getSkin() then
            ent:SetSkin(item:getSkin())
        end
        return ent
    end
    local itemEntity = createItemEntity(myItem, Vector(0, 0, 0))

---

getSkin

📋 Purpose

Gets the skin index for the item's model

⏰ When Called

When setting up item display or entity appearance

↩️ Returns

• Number representing the skin index, or nil if none set

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    local skin = item:getSkin()

📊 Medium Complexity

    if item:getSkin() then
        entity:SetSkin(item:getSkin())
    end

⚙️ High Complexity

    local function applyItemAppearance(entity, item)
        entity:SetModel(item:getModel())
        entity:SetSkin(item:getSkin() or 0)
        for k, v in pairs(item:getBodygroups()) do
            entity:SetBodygroup(k, v)
        end
        entity:SetColor(item:getData("color", Color(255, 255, 255)))
    end
    applyItemAppearance(myEntity, myItem)

---

getBodygroups

📋 Purpose

Gets the bodygroup settings for the item's model

⏰ When Called

When setting up item display or entity appearance

↩️ Returns

• Table of bodygroup settings, empty table if none set

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    local bodygroups = item:getBodygroups()

📊 Medium Complexity

    for id, value in pairs(item:getBodygroups()) do
        entity:SetBodygroup(id, value)
    end

⚙️ High Complexity

    local function applyBodygroups(entity, bodygroups)
        for bodygroupID, bodygroupValue in pairs(bodygroups) do
            if isstring(bodygroupID) then
                -- Handle named bodygroups
                local id = entity:FindBodygroupByName(bodygroupID)
                if id ~= -1 then
                    entity:SetBodygroup(id, bodygroupValue)
                end
            else
                entity:SetBodygroup(bodygroupID, bodygroupValue)
            end
        end
    end
    applyBodygroups(myEntity, item:getBodygroups())

---

getPrice

📋 Purpose

Gets the current price of the item, potentially calculated dynamically

⏰ When Called

When selling, trading, or displaying item value

↩️ Returns

• Number representing the item's price

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    local price = item:getPrice()

📊 Medium Complexity

    if player:getMoney() >= item:getPrice() then
        player:buyItem(item)
    end

⚙️ High Complexity

    local function calculateTotalCost(items)
        local total = 0
        for _, item in ipairs(items) do
            local price = item:getPrice()
            local quantity = item:getQuantity()
            total = total + (price * quantity)
        end
        -- Apply bulk discount
        if #items > 5 then
            total = total * 0.9
        end
        return total
    end
    local cost = calculateTotalCost(selectedItems)

---

call

📋 Purpose

Calls an item method with specified player and entity context

⏰ When Called

When executing item functions that need player/entity context

⚙️ Parameters

Parameter	Type	Description
method	string	String name of the method to call
client	Player	Player entity to set as context
entity	Entity	Entity to set as context

↩️ Returns

• The return values from the called method

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    item:call("use", player)

📊 Medium Complexity

    local success = item:call("canUse", player, entity)
    if success then
        item:call("onUse", player, entity)
    end

⚙️ High Complexity

    local function executeItemAction(item, action, player, entity, ...)
        local canRun, reason = item:call("can" .. action, player, entity, ...)
        if canRun then
            local result = {item:call("on" .. action, player, entity, ...)}
            hook.Run("OnItem" .. action, item, player, entity, unpack(result))
            return true, unpack(result)
        else
            player:notifyError(reason or "Cannot perform action")
            return false
        end
    end
    local success, data = executeItemAction(myItem, "Use", player, nil, target)

---

getOwner

📋 Purpose

Gets the player who owns this item

⏰ When Called

When you need to determine item ownership or permissions

↩️ Returns

• Player entity who owns the item, or nil if not found

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    local owner = item:getOwner()

📊 Medium Complexity

    if item:getOwner() == player then
        allowModification = true
    end

⚙️ High Complexity

    local function canPlayerAccessItem(player, item)
        local owner = item:getOwner()
        if not owner then return false end
        -- Check if player is the owner
        if owner == player then return true end
        -- Check if player has admin permissions
        if player:isAdmin() then return true end
        -- Check if item is in shared inventory
        local inventory = lia.inventory.instances[item.invID]
        if inventory and inventory:getData("shared") then
            return inventory:canAccess("view", {client = player})
        end
        return false
    end
    if canPlayerAccessItem(client, myItem) then
        -- Allow access
    end

---

getData

📋 Purpose

Retrieves data from the item's data table with fallback to entity data

⏰ When Called

When accessing item-specific data or configuration

⚙️ Parameters

Parameter	Type	Description
key	string	The data key to retrieve
default	any	Optional default value if key doesn't exist

↩️ Returns

• The data value or default value if key doesn't exist

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    local durability = item:getData("durability", 100)

📊 Medium Complexity

    local color = item:getData("color", Color(255, 255, 255))
    entity:SetColor(color)

⚙️ High Complexity

    local function applyItemModifiers(entity, item)
        -- Apply durability-based modifications
        local durability = item:getData("durability", 100)
        local maxDurability = item:getData("maxDurability", 100)
        local durabilityPercent = durability / maxDurability
        -- Reduce effectiveness based on durability
        if item.damage then
            entity:SetHealth(entity:GetMaxHealth() * durabilityPercent)
        end
        -- Apply custom modifiers
        local modifiers = item:getData("modifiers", {})
        for modifierType, modifierValue in pairs(modifiers) do
            applyModifier(entity, modifierType, modifierValue * durabilityPercent)
        end
    end
    applyItemModifiers(myEntity, myItem)

---

getAllData

📋 Purpose

Gets all data associated with the item from both item and entity

⏰ When Called

When you need a complete view of all item data

↩️ Returns

• Table containing all item data

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    local allData = item:getAllData()

📊 Medium Complexity

    local data = item:getAllData()
    for key, value in pairs(data) do
        print(key .. ": " .. tostring(value))
    end

⚙️ High Complexity

    local function serializeItemForSave(item)
        local data = item:getAllData()
        -- Remove runtime-only data
        data.entity = nil
        data.player = nil
        -- Add metadata
        data.savedAt = os.time()
        data.version = "1.0"
        return util.TableToJSON(data)
    end
    local serializedData = serializeItemForSave(myItem)
    file.Write("item_backup.txt", serializedData)

---

hook

📋 Purpose

Registers a hook function to be called before item actions

⏰ When Called

During item configuration to add custom behavior

⚙️ Parameters

Parameter	Type	Description
name	string	String name of the hook (e.g., "use", "drop")
func	function	Function to call when the hook is triggered

↩️ Returns

• Nothing

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    item:hook("use", function(item)
        print("Item used!")
    end)

📊 Medium Complexity

    item:hook("drop", function(item)
        if item:getData("soulbound") then
            return false -- Prevent dropping
        end
    end)

⚙️ High Complexity

    item:hook("use", function(item)
        -- Check cooldown
        local lastUsed = item:getData("lastUsed", 0)
        local cooldown = item:getData("cooldown", 60)
        if CurTime() - lastUsed < cooldown then
            item.player:notifyError("Item is on cooldown")
            return false
        end
        -- Update last used time
        item:setData("lastUsed", CurTime())
        -- Apply custom effects
        applyItemEffect(item.player, item.uniqueID)
    end)

---

postHook

📋 Purpose

Registers a post-hook function to be called after item actions

⏰ When Called

During item configuration to add cleanup or follow-up behavior

⚙️ Parameters

Parameter	Type	Description
name	string	String name of the hook (e.g., "use", "drop")
func	function	Function to call after the hook is triggered

↩️ Returns

• Nothing

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    item:postHook("use", function(item)
        print("Item use completed")
    end)

📊 Medium Complexity

    item:postHook("drop", function(item)
        lia.log.add(item.player, "item_dropped", item:getName())
    end)

⚙️ High Complexity

    item:postHook("use", function(item, result)
        -- Log usage statistics
        local stats = lia.data.get("item_usage_stats", {})
        stats[item.uniqueID] = (stats[item.uniqueID] or 0) + 1
        lia.data.set("item_usage_stats", stats)
        -- Apply post-use effects
        if result == true and item:getData("consumable") then
            item:addQuantity(-1)
        end
        -- Trigger achievements
        if stats[item.uniqueID] >= 100 then
            item.player:unlockAchievement("frequent_user")
        end
    end)

---

onRegistered

📋 Purpose

Called when the item is registered with the system

⏰ When Called

Automatically during item registration

↩️ Returns

• Nothing

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    function ITEM:onRegistered()
        print("Item registered: " .. self.uniqueID)
    end

📊 Medium Complexity

    function ITEM:onRegistered()
        if self.model then
            util.PrecacheModel(self.model)
        end
    end

⚙️ High Complexity

    function ITEM:onRegistered()
        -- Precache model
        if self.model then
            util.PrecacheModel(self.model)
        end
        -- Register with item categories
        if self.category then
            local categories = lia.data.get("item_categories", {})
            categories[self.category] = categories[self.category] or {}
            table.insert(categories[self.category], self.uniqueID)
            lia.data.set("item_categories", categories)
        end
        -- Set up default data
        self.defaultData = self.defaultData or {}
        for key, value in pairs(self.defaultData) do
            if self:getData(key) == nil then
                self:setData(key, value)
            end
        end
    end

---

onRegistered

📋 Purpose

Called when the item is registered with the system

⏰ When Called

Automatically during item registration

↩️ Returns

• Nothing

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    function ITEM:onRegistered()
        print("Item registered: " .. self.uniqueID)
    end

📊 Medium Complexity

    function ITEM:onRegistered()
        if self.model then
            util.PrecacheModel(self.model)
        end
    end

⚙️ High Complexity

    function ITEM:onRegistered()
        -- Precache model
        if self.model then
            util.PrecacheModel(self.model)
        end
        -- Register with item categories
        if self.category then
            local categories = lia.data.get("item_categories", {})
            categories[self.category] = categories[self.category] or {}
            table.insert(categories[self.category], self.uniqueID)
            lia.data.set("item_categories", categories)
        end
        -- Set up default data
        self.defaultData = self.defaultData or {}
        for key, value in pairs(self.defaultData) do
            if self:getData(key) == nil then
                self:setData(key, value)
            end
        end
    end

---

onRegistered

📋 Purpose

Called when the item is registered with the system

⏰ When Called

Automatically during item registration

↩️ Returns

• Nothing

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    function ITEM:onRegistered()
        print("Item registered: " .. self.uniqueID)
    end

📊 Medium Complexity

    function ITEM:onRegistered()
        if self.model then
            util.PrecacheModel(self.model)
        end
    end

⚙️ High Complexity

    function ITEM:onRegistered()
        -- Precache model
        if self.model then
            util.PrecacheModel(self.model)
        end
        -- Register with item categories
        if self.category then
            local categories = lia.data.get("item_categories", {})
            categories[self.category] = categories[self.category] or {}
            table.insert(categories[self.category], self.uniqueID)
            lia.data.set("item_categories", categories)
        end
        -- Set up default data
        self.defaultData = self.defaultData or {}
        for key, value in pairs(self.defaultData) do
            if self:getData(key) == nil then
                self:setData(key, value)
            end
        end
    end

---

onRegistered

📋 Purpose

Called when the item is registered with the system

⏰ When Called

Automatically during item registration

↩️ Returns

• Nothing

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    function ITEM:onRegistered()
        print("Item registered: " .. self.uniqueID)
    end

📊 Medium Complexity

    function ITEM:onRegistered()
        if self.model then
            util.PrecacheModel(self.model)
        end
    end

⚙️ High Complexity

    function ITEM:onRegistered()
        -- Precache model
        if self.model then
            util.PrecacheModel(self.model)
        end
        -- Register with item categories
        if self.category then
            local categories = lia.data.get("item_categories", {})
            categories[self.category] = categories[self.category] or {}
            table.insert(categories[self.category], self.uniqueID)
            lia.data.set("item_categories", categories)
        end
        -- Set up default data
        self.defaultData = self.defaultData or {}
        for key, value in pairs(self.defaultData) do
            if self:getData(key) == nil then
                self:setData(key, value)
            end
        end
    end

---

print

📋 Purpose

Prints basic item information to the server console

⏰ When Called

For debugging or logging item state

⚙️ Parameters

Parameter	Type	Description
detail	boolean	Optional boolean to show detailed information

↩️ Returns

• Nothing

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    item:print()

📊 Medium Complexity

    item:print(true) -- Show detailed info

⚙️ High Complexity

    local function debugInventory(inventory)
        for _, item in pairs(inventory:getItems()) do
            item:print(true)
            print("---")
        end
    end
    debugInventory(player:getInventory())

---

printData

📋 Purpose

Prints all item data to the server console

⏰ When Called

For detailed debugging of item data

↩️ Returns

• Nothing

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    item:printData()

📊 Medium Complexity

    if item:getData("debug") then
        item:printData()
    end

⚙️ High Complexity

    local function auditItemData(item)
        item:printData()
        -- Check for invalid data
        local data = item:getAllData()
        for key, value in pairs(data) do
            if istable(value) and table.Count(value) > 100 then
                lia.log.add(nil, "large_data_warning", item:getID(), key, table.Count(value))
            end
        end
    end
    auditItemData(suspiciousItem)

---

getName

📋 Purpose

Gets the display name of the item

⏰ When Called

When displaying item names in UI or chat

↩️ Returns

• String representing the item's name

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    local name = item:getName()

📊 Medium Complexity

    chat.AddText(Color(255, 255, 255), "You received: ", item:getName())

⚙️ High Complexity

    local function formatItemName(item)
        local name = item:getName()
        local quality = item:getData("quality")
        if quality then
            local colors = {
                common     = Color(255, 255, 255),
                rare        = Color(0, 255, 255),
                epic        = Color(255, 0, 255),
                legendary   = Color(255, 165, 0)
            }
            return colors[quality], name
        end
        return Color(255, 255, 255), name
    end
    local color, displayName = formatItemName(myItem)

---

getDesc

📋 Purpose

Gets the description of the item

⏰ When Called

When displaying item details or tooltips

↩️ Returns

• String representing the item's description

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    local desc = item:getDesc()

📊 Medium Complexity

    print("Item description: " .. item:getDesc())

⚙️ High Complexity

    local function getFormattedDescription(item)
        local desc = item:getDesc()
        -- Add dynamic information
        if item:getData("durability") then
            local durability = item:getData("durability", 100)
            local maxDurability = item:getData("maxDurability", 100)
            desc = desc .. string.format("\nDurability: %d/%d", durability, maxDurability)
        end
        if item:getData("level") then
            desc = desc .. string.format("\nRequired Level: %d", item:getData("level"))
        end
        return desc
    end
    local fullDesc = getFormattedDescription(myItem)

---

removeFromInventory

📋 Purpose

Removes the item from its current inventory without deleting it

⏰ When Called

When transferring items between inventories or temporarily removing them

⚙️ Parameters

Parameter	Type	Description
preserveItem	boolean	Optional boolean to preserve item data in database

↩️ Returns

• Deferred object that resolves when removal is complete

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    item:removeFromInventory()

📊 Medium Complexity

    item:removeFromInventory(true):next(function()
        print("Item removed but preserved")
    end)

⚙️ High Complexity

    local function transferItem(item, fromInv, toInv)
        return item:removeFromInventory(true):next(function()
            return toInv:add(item)
        end):next(function()
            lia.log.add(nil, "item_transferred",
                item:getID(), fromInv:getID(), toInv:getID())
        end)
    end
    transferItem(myItem, playerInv, bankInv)

---

delete

📋 Purpose

Permanently deletes the item from the database and system

⏰ When Called

When completely removing an item from the game world

↩️ Returns

• Deferred object that resolves when deletion is complete

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    item:delete()

📊 Medium Complexity

    item:delete():next(function()
        print("Item permanently deleted")
    end)

⚙️ High Complexity

    local function safelyDeleteExpiredItems()
        local expiredItems = lia.db.select("*", "items", "expiry_date < " .. os.time())
        expiredItems:next(function(results)
            for _, row in ipairs(results.results or {}) do
                local item = lia.item.instances[tonumber(row.itemID)]
                if item then
                    -- Log deletion reason
                    lia.log.add(nil, "expired_item_deleted", row.itemID, row.uniqueID)
                    -- Delete the item
                    item:delete()
                end
            end
        end)
    end
    safelyDeleteExpiredItems()

---

remove

📋 Purpose

Completely removes the item from the world, inventory, and database

⏰ When Called

When an item is used up, destroyed, or needs to be completely eliminated

↩️ Returns

• Deferred object that resolves when removal is complete

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    item:remove()

📊 Medium Complexity

    item:remove():next(function()
        player:notify("Item consumed")
    end)

⚙️ High Complexity

    local function consumeItemWithEffects(item, player)
        -- Apply item effects before removal
        if item.onConsume then
            item:call("onConsume", player)
        end
        -- Remove the item
        return item:remove():next(function()
            -- Post-consumption effects
            if item:getData("reusable") then
                -- Create a new instance if reusable
                local newItem = lia.item.new(item.uniqueID, 1)
                player:getInventory():add(newItem)
            end
            -- Trigger achievements
            local consumedCount = player:getData("items_consumed", 0) + 1
            player:setData("items_consumed", consumedCount)
            if consumedCount >= 100 then
                player:unlockAchievement("consumptive")
            end
        end)
    end
    consumeItemWithEffects(myItem, player)

---

destroy

📋 Purpose

Destroys the item instance and notifies all clients to remove it

⏰ When Called

When an item needs to be removed from the game world immediately

↩️ Returns

• Nothing

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    item:destroy()

📊 Medium Complexity

    if item:getData("temporary") then
        item:destroy()
    end

⚙️ High Complexity

    local function destroyItemsInRadius(position, radius)
        local items = ents.FindInSphere(position, radius)
        local destroyedCount = 0
        for _, ent in ipairs(items) do
            if ent:GetClass() == "lia_item" and ent.liaItemID then
                local item = lia.item.instances[ent.liaItemID]
                if item then
                    -- Log destruction
                    lia.log.add(nil, "area_destruction", item:getID(), item:getName())
                    item:destroy()
                    destroyedCount = destroyedCount + 1
                end
            end
        end
        lia.chat.send(nil, "Destroyed " .. destroyedCount .. " items in area")
        return destroyedCount
    end
    destroyItemsInRadius(explosionPos, 500)

---

onDisposed

📋 Purpose

Called when the item is disposed/destroyed

⏰ When Called

Automatically when destroy() is called

↩️ Returns

• Nothing

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    function ITEM:onDisposed()
        -- Cleanup code here
    end

📊 Medium Complexity

    function ITEM:onDisposed()
        -- Clean up associated entities
        if self.associatedEntity then
            SafeRemoveEntity(self.associatedEntity)
        end
    end

⚙️ High Complexity

    function ITEM:onDisposed()
        -- Comprehensive cleanup
        if self.temporaryEntities then
            for _, ent in ipairs(self.temporaryEntities) do
                SafeRemoveEntity(ent)
            end
            self.temporaryEntities = nil
        end
        -- Remove from global item lists
        if self.category then
            local categoryItems = lia.data.get("category_items_" .. self.category, {})
            categoryItems[self:getID()] = nil
            lia.data.set("category_items_" .. self.category, categoryItems)
        end
        -- Log disposal
        lia.log.add(nil, "item_disposed", self:getID(), self.uniqueID)
        -- Trigger disposal hooks
        hook.Run("OnItemDisposed", self)
    end

---

onDisposed

📋 Purpose

Called when the item is disposed/destroyed

⏰ When Called

Automatically when destroy() is called

↩️ Returns

• Nothing

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    function ITEM:onDisposed()
        -- Cleanup code here
    end

📊 Medium Complexity

    function ITEM:onDisposed()
        -- Clean up associated entities
        if self.associatedEntity then
            SafeRemoveEntity(self.associatedEntity)
        end
    end

⚙️ High Complexity

    function ITEM:onDisposed()
        -- Comprehensive cleanup
        if self.temporaryEntities then
            for _, ent in ipairs(self.temporaryEntities) do
                SafeRemoveEntity(ent)
            end
            self.temporaryEntities = nil
        end
        -- Remove from global item lists
        if self.category then
            local categoryItems = lia.data.get("category_items_" .. self.category, {})
            categoryItems[self:getID()] = nil
            lia.data.set("category_items_" .. self.category, categoryItems)
        end
        -- Log disposal
        lia.log.add(nil, "item_disposed", self:getID(), self.uniqueID)
        -- Trigger disposal hooks
        hook.Run("OnItemDisposed", self)
    end

---

onDisposed

📋 Purpose

Called when the item is disposed/destroyed

⏰ When Called

Automatically when destroy() is called

↩️ Returns

• Nothing

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    function ITEM:onDisposed()
        -- Cleanup code here
    end

📊 Medium Complexity

    function ITEM:onDisposed()
        -- Clean up associated entities
        if self.associatedEntity then
            SafeRemoveEntity(self.associatedEntity)
        end
    end

⚙️ High Complexity

    function ITEM:onDisposed()
        -- Comprehensive cleanup
        if self.temporaryEntities then
            for _, ent in ipairs(self.temporaryEntities) do
                SafeRemoveEntity(ent)
            end
            self.temporaryEntities = nil
        end
        -- Remove from global item lists
        if self.category then
            local categoryItems = lia.data.get("category_items_" .. self.category, {})
            categoryItems[self:getID()] = nil
            lia.data.set("category_items_" .. self.category, categoryItems)
        end
        -- Log disposal
        lia.log.add(nil, "item_disposed", self:getID(), self.uniqueID)
        -- Trigger disposal hooks
        hook.Run("OnItemDisposed", self)
    end

---

onDisposed

📋 Purpose

Called when the item is disposed/destroyed

⏰ When Called

Automatically when destroy() is called

↩️ Returns

• Nothing

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    function ITEM:onDisposed()
        -- Cleanup code here
    end

📊 Medium Complexity

    function ITEM:onDisposed()
        -- Clean up associated entities
        if self.associatedEntity then
            SafeRemoveEntity(self.associatedEntity)
        end
    end

⚙️ High Complexity

    function ITEM:onDisposed()
        -- Comprehensive cleanup
        if self.temporaryEntities then
            for _, ent in ipairs(self.temporaryEntities) do
                SafeRemoveEntity(ent)
            end
            self.temporaryEntities = nil
        end
        -- Remove from global item lists
        if self.category then
            local categoryItems = lia.data.get("category_items_" .. self.category, {})
            categoryItems[self:getID()] = nil
            lia.data.set("category_items_" .. self.category, categoryItems)
        end
        -- Log disposal
        lia.log.add(nil, "item_disposed", self:getID(), self.uniqueID)
        -- Trigger disposal hooks
        hook.Run("OnItemDisposed", self)
    end

---

getEntity

📋 Purpose

Gets the world entity associated with this item instance

⏰ When Called

When you need to manipulate the physical item entity in the world

↩️ Returns

• Entity object if found, nil otherwise

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    local entity = item:getEntity()

📊 Medium Complexity

    local entity = item:getEntity()
    if entity then
        entity:SetPos(newPosition)
    end

⚙️ High Complexity

    local function teleportItemToPlayer(item, player)
        local entity = item:getEntity()
        if entity then
            -- Remove from inventory first
            item:removeFromInventory(true):next(function()
                -- Teleport entity to player
                entity:SetPos(player:GetPos() + Vector(0, 0, 50))
                entity:SetVelocity(Vector(0, 0, 0))
                -- Log the action
                lia.log.add(player, "item_teleported", item:getID(), item:getName())
            end)
        else
            player:notifyError("Item has no physical entity")
        end
    end
    teleportItemToPlayer(myItem, player)

---

spawn

📋 Purpose

Creates a physical entity for the item in the world

⏰ When Called

When dropping items or spawning them in the world

⚙️ Parameters

Parameter	Type	Description
position	**Vector	table
angles	Angle	Optional angles for the spawned item

↩️ Returns

• The created entity

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    item:spawn(Vector(0, 0, 0))

📊 Medium Complexity

    item:spawn(player:GetPos() + Vector(0, 0, 50), Angle(0, 0, 0))

⚙️ High Complexity

    local function dropItemWithPhysics(item, player, force)
        -- Remove from inventory
        item:removeFromInventory(true):next(function()
            -- Spawn with physics
            local entity = item:spawn(player:GetPos() + Vector(0, 50, 0))
            if entity and IsValid(entity:GetPhysicsObject()) then
                -- Apply throw force
                local phys = entity:GetPhysicsObject()
                phys:ApplyForceCenter(player:GetAimVector() * force)
                -- Add some spin
                phys:AddAngleVelocity(VectorRand() * 100)
                -- Log the drop
                lia.log.add(player, "item_dropped", item:getID(), item:getName())
            end
        end)
    end
    dropItemWithPhysics(myItem, player, 1000)

---

transfer

📋 Purpose

Transfers the item from its current inventory to a new inventory

⏰ When Called

When moving items between inventories (trading, storing, etc.)

⚙️ Parameters

Parameter	Type	Description
newInventory	Inventory	The inventory to transfer the item to
bBypass	boolean	Optional boolean to bypass access control checks

↩️ Returns

• Boolean indicating if transfer was successful

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    item:transfer(otherInventory)

📊 Medium Complexity

    if item:transfer(bankInventory) then
        player:notify("Item stored in bank")
    end

⚙️ High Complexity

    local function tradeItems(player1, player2, itemID, payment)
        local item = player1:getInventory():getItems()[itemID]
        if not item then return false, "Item not found" end
        -- Check if player2 has enough money
        if player2:getMoney() < payment then
            return false, "Insufficient funds"
        end
        -- Transfer item
        if item:transfer(player2:getInventory()) then
            -- Handle payment
            player2:addMoney(-payment)
            player1:addMoney(payment)
            -- Log the trade
            lia.log.add(nil, "item_trade",
                item:getID(), player1:GetName(), player2:GetName(), payment)
            return true
        else
            return false, "Transfer failed"
        end
    end
    local success, reason = tradeItems(seller, buyer, itemID, 500)

---

onInstanced

📋 Purpose

Called when the item instance is first created

⏰ When Called

Automatically when item instances are created

↩️ Returns

• Nothing

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    function ITEM:onInstanced()
        print("New item instance created")
    end

📊 Medium Complexity

    function ITEM:onInstanced()
        -- Set default data for new instances
        if not self:getData("created") then
            self:setData("created", os.time())
        end
    end

⚙️ High Complexity

    function ITEM:onInstanced()
        -- Initialize complex item state
        self:setData("durability", self:getData("maxDurability", 100))
        self:setData("serialNumber", string.format("SN-%06d-%04d-%03d", math.random(100000, 999999), math.random(1000, 9999), math.random(100, 999)))
        -- Register with item tracking system
        local trackingData = lia.data.get("item_tracking", {})
        trackingData[self:getID()] = {
            uniqueID = self.uniqueID,
            created  = os.time(),
            owner    = self:getOwner() and self:getOwner():GetName() or "unknown"
        }
        lia.data.set("item_tracking", trackingData)
        -- Apply category-specific initialization
        if self.category == "weapons" then
            self:setData("ammo", self:getData("maxAmmo", 30))
        elseif self.category == "armor" then
            self:setData("protection", self:getData("maxProtection", 50))
        end
    end

---

onInstanced

📋 Purpose

Called when the item instance is first created

⏰ When Called

Automatically when item instances are created

↩️ Returns

• Nothing

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    function ITEM:onInstanced()
        print("New item instance created")
    end

📊 Medium Complexity

    function ITEM:onInstanced()
        -- Set default data for new instances
        if not self:getData("created") then
            self:setData("created", os.time())
        end
    end

⚙️ High Complexity

    function ITEM:onInstanced()
        -- Initialize complex item state
        self:setData("durability", self:getData("maxDurability", 100))
        self:setData("serialNumber", string.format("SN-%06d-%04d-%03d", math.random(100000, 999999), math.random(1000, 9999), math.random(100, 999)))
        -- Register with item tracking system
        local trackingData = lia.data.get("item_tracking", {})
        trackingData[self:getID()] = {
            uniqueID = self.uniqueID,
            created  = os.time(),
            owner    = self:getOwner() and self:getOwner():GetName() or "unknown"
        }
        lia.data.set("item_tracking", trackingData)
        -- Apply category-specific initialization
        if self.category == "weapons" then
            self:setData("ammo", self:getData("maxAmmo", 30))
        elseif self.category == "armor" then
            self:setData("protection", self:getData("maxProtection", 50))
        end
    end

---

onInstanced

📋 Purpose

Called when the item instance is first created

⏰ When Called

Automatically when item instances are created

↩️ Returns

• Nothing

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    function ITEM:onInstanced()
        print("New item instance created")
    end

📊 Medium Complexity

    function ITEM:onInstanced()
        -- Set default data for new instances
        if not self:getData("created") then
            self:setData("created", os.time())
        end
    end

⚙️ High Complexity

    function ITEM:onInstanced()
        -- Initialize complex item state
        self:setData("durability", self:getData("maxDurability", 100))
        self:setData("serialNumber", string.format("SN-%06d-%04d-%03d", math.random(100000, 999999), math.random(1000, 9999), math.random(100, 999)))
        -- Register with item tracking system
        local trackingData = lia.data.get("item_tracking", {})
        trackingData[self:getID()] = {
            uniqueID = self.uniqueID,
            created  = os.time(),
            owner    = self:getOwner() and self:getOwner():GetName() or "unknown"
        }
        lia.data.set("item_tracking", trackingData)
        -- Apply category-specific initialization
        if self.category == "weapons" then
            self:setData("ammo", self:getData("maxAmmo", 30))
        elseif self.category == "armor" then
            self:setData("protection", self:getData("maxProtection", 50))
        end
    end

---

onInstanced

📋 Purpose

Called when the item instance is first created

⏰ When Called

Automatically when item instances are created

↩️ Returns

• Nothing

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    function ITEM:onInstanced()
        print("New item instance created")
    end

📊 Medium Complexity

    function ITEM:onInstanced()
        -- Set default data for new instances
        if not self:getData("created") then
            self:setData("created", os.time())
        end
    end

⚙️ High Complexity

    function ITEM:onInstanced()
        -- Initialize complex item state
        self:setData("durability", self:getData("maxDurability", 100))
        self:setData("serialNumber", string.format("SN-%06d-%04d-%03d", math.random(100000, 999999), math.random(1000, 9999), math.random(100, 999)))
        -- Register with item tracking system
        local trackingData = lia.data.get("item_tracking", {})
        trackingData[self:getID()] = {
            uniqueID = self.uniqueID,
            created  = os.time(),
            owner    = self:getOwner() and self:getOwner():GetName() or "unknown"
        }
        lia.data.set("item_tracking", trackingData)
        -- Apply category-specific initialization
        if self.category == "weapons" then
            self:setData("ammo", self:getData("maxAmmo", 30))
        elseif self.category == "armor" then
            self:setData("protection", self:getData("maxProtection", 50))
        end
    end

---

onSync

📋 Purpose

Called when the item is synchronized to clients

⏰ When Called

Automatically when item data is sent to clients

⚙️ Parameters

Parameter	Type	Description
recipient	Player	Optional specific client to sync to

↩️ Returns

• Nothing

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    function ITEM:onSync(recipient)
        -- Custom sync logic
    end

📊 Medium Complexity

    function ITEM:onSync(recipient)
        -- Send additional data to specific client
        if recipient then
            net.Start("CustomItemData")
            net.WriteType(self:getID())
            net.WriteTable(self:getAllData())
            net.Send(recipient)
        end
    end

⚙️ High Complexity

    function ITEM:onSync(recipient)
        -- Advanced sync with filtering
        local dataToSend = {}
        -- Only send sensitive data to item owner
        if recipient == self:getOwner() then
            dataToSend = self:getAllData()
        else
            -- Filter out sensitive data for other players
            for key, value in pairs(self:getAllData()) do
                if not self.sensitiveDataKeys[key] then
                    dataToSend[key] = value
                end
            end
        end
        -- Send filtered data
        net.Start("FilteredItemData")
        net.WriteType(self:getID())
        net.WriteTable(dataToSend)
        net.Send(recipient)
    end

---

onSync

📋 Purpose

Called when the item is synchronized to clients

⏰ When Called

Automatically when item data is sent to clients

⚙️ Parameters

Parameter	Type	Description
recipient	Player	Optional specific client to sync to

↩️ Returns

• Nothing

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    function ITEM:onSync(recipient)
        -- Custom sync logic
    end

📊 Medium Complexity

    function ITEM:onSync(recipient)
        -- Send additional data to specific client
        if recipient then
            net.Start("CustomItemData")
            net.WriteType(self:getID())
            net.WriteTable(self:getAllData())
            net.Send(recipient)
        end
    end

⚙️ High Complexity

    function ITEM:onSync(recipient)
        -- Advanced sync with filtering
        local dataToSend = {}
        -- Only send sensitive data to item owner
        if recipient == self:getOwner() then
            dataToSend = self:getAllData()
        else
            -- Filter out sensitive data for other players
            for key, value in pairs(self:getAllData()) do
                if not self.sensitiveDataKeys[key] then
                    dataToSend[key] = value
                end
            end
        end
        -- Send filtered data
        net.Start("FilteredItemData")
        net.WriteType(self:getID())
        net.WriteTable(dataToSend)
        net.Send(recipient)
    end

---

onSync

📋 Purpose

Called when the item is synchronized to clients

⏰ When Called

Automatically when item data is sent to clients

⚙️ Parameters

Parameter	Type	Description
recipient	Player	Optional specific client to sync to

↩️ Returns

• Nothing

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    function ITEM:onSync(recipient)
        -- Custom sync logic
    end

📊 Medium Complexity

    function ITEM:onSync(recipient)
        -- Send additional data to specific client
        if recipient then
            net.Start("CustomItemData")
            net.WriteType(self:getID())
            net.WriteTable(self:getAllData())
            net.Send(recipient)
        end
    end

⚙️ High Complexity

    function ITEM:onSync(recipient)
        -- Advanced sync with filtering
        local dataToSend = {}
        -- Only send sensitive data to item owner
        if recipient == self:getOwner() then
            dataToSend = self:getAllData()
        else
            -- Filter out sensitive data for other players
            for key, value in pairs(self:getAllData()) do
                if not self.sensitiveDataKeys[key] then
                    dataToSend[key] = value
                end
            end
        end
        -- Send filtered data
        net.Start("FilteredItemData")
        net.WriteType(self:getID())
        net.WriteTable(dataToSend)
        net.Send(recipient)
    end

---

onSync

📋 Purpose

Called when the item is synchronized to clients

⏰ When Called

Automatically when item data is sent to clients

⚙️ Parameters

Parameter	Type	Description
recipient	Player	Optional specific client to sync to

↩️ Returns

• Nothing

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    function ITEM:onSync(recipient)
        -- Custom sync logic
    end

📊 Medium Complexity

    function ITEM:onSync(recipient)
        -- Send additional data to specific client
        if recipient then
            net.Start("CustomItemData")
            net.WriteType(self:getID())
            net.WriteTable(self:getAllData())
            net.Send(recipient)
        end
    end

⚙️ High Complexity

    function ITEM:onSync(recipient)
        -- Advanced sync with filtering
        local dataToSend = {}
        -- Only send sensitive data to item owner
        if recipient == self:getOwner() then
            dataToSend = self:getAllData()
        else
            -- Filter out sensitive data for other players
            for key, value in pairs(self:getAllData()) do
                if not self.sensitiveDataKeys[key] then
                    dataToSend[key] = value
                end
            end
        end
        -- Send filtered data
        net.Start("FilteredItemData")
        net.WriteType(self:getID())
        net.WriteTable(dataToSend)
        net.Send(recipient)
    end

---

onRemoved

📋 Purpose

Called when the item is permanently removed from the system

⏰ When Called

Automatically when delete() completes

↩️ Returns

• Nothing

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    function ITEM:onRemoved()
        print("Item permanently removed")
    end

📊 Medium Complexity

    function ITEM:onRemoved()
        -- Clean up references
        lia.data.delete("item_" .. self:getID())
    end

⚙️ High Complexity

    function ITEM:onRemoved()
        -- Comprehensive cleanup
        local itemID = self:getID()
        -- Remove from tracking systems
        local trackingData = lia.data.get("item_tracking", {})
        trackingData[itemID] = nil
        lia.data.set("item_tracking", trackingData)
        -- Remove from category lists
        if self.category then
            local categoryItems = lia.data.get("category_items_" .. self.category, {})
            categoryItems[itemID] = nil
            lia.data.set("category_items_" .. self.category, categoryItems)
        end
        -- Log permanent removal
        lia.log.add(nil, "item_permanently_removed", itemID, self.uniqueID)
        -- Notify administrators of rare item removal
        if self:getData("rarity") == "legendary" then
            lia.chat.send(lia.util.getAdmins(), "Legendary item permanently removed: " .. self:getName())
        end
    end

---

onRemoved

📋 Purpose

Called when the item is permanently removed from the system

⏰ When Called

Automatically when delete() completes

↩️ Returns

• Nothing

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    function ITEM:onRemoved()
        print("Item permanently removed")
    end

📊 Medium Complexity

    function ITEM:onRemoved()
        -- Clean up references
        lia.data.delete("item_" .. self:getID())
    end

⚙️ High Complexity

    function ITEM:onRemoved()
        -- Comprehensive cleanup
        local itemID = self:getID()
        -- Remove from tracking systems
        local trackingData = lia.data.get("item_tracking", {})
        trackingData[itemID] = nil
        lia.data.set("item_tracking", trackingData)
        -- Remove from category lists
        if self.category then
            local categoryItems = lia.data.get("category_items_" .. self.category, {})
            categoryItems[itemID] = nil
            lia.data.set("category_items_" .. self.category, categoryItems)
        end
        -- Log permanent removal
        lia.log.add(nil, "item_permanently_removed", itemID, self.uniqueID)
        -- Notify administrators of rare item removal
        if self:getData("rarity") == "legendary" then
            lia.chat.send(lia.util.getAdmins(), "Legendary item permanently removed: " .. self:getName())
        end
    end

---

onRemoved

📋 Purpose

Called when the item is permanently removed from the system

⏰ When Called

Automatically when delete() completes

↩️ Returns

• Nothing

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    function ITEM:onRemoved()
        print("Item permanently removed")
    end

📊 Medium Complexity

    function ITEM:onRemoved()
        -- Clean up references
        lia.data.delete("item_" .. self:getID())
    end

⚙️ High Complexity

    function ITEM:onRemoved()
        -- Comprehensive cleanup
        local itemID = self:getID()
        -- Remove from tracking systems
        local trackingData = lia.data.get("item_tracking", {})
        trackingData[itemID] = nil
        lia.data.set("item_tracking", trackingData)
        -- Remove from category lists
        if self.category then
            local categoryItems = lia.data.get("category_items_" .. self.category, {})
            categoryItems[itemID] = nil
            lia.data.set("category_items_" .. self.category, categoryItems)
        end
        -- Log permanent removal
        lia.log.add(nil, "item_permanently_removed", itemID, self.uniqueID)
        -- Notify administrators of rare item removal
        if self:getData("rarity") == "legendary" then
            lia.chat.send(lia.util.getAdmins(), "Legendary item permanently removed: " .. self:getName())
        end
    end

---

onRemoved

📋 Purpose

Called when the item is permanently removed from the system

⏰ When Called

Automatically when delete() completes

↩️ Returns

• Nothing

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    function ITEM:onRemoved()
        print("Item permanently removed")
    end

📊 Medium Complexity

    function ITEM:onRemoved()
        -- Clean up references
        lia.data.delete("item_" .. self:getID())
    end

⚙️ High Complexity

    function ITEM:onRemoved()
        -- Comprehensive cleanup
        local itemID = self:getID()
        -- Remove from tracking systems
        local trackingData = lia.data.get("item_tracking", {})
        trackingData[itemID] = nil
        lia.data.set("item_tracking", trackingData)
        -- Remove from category lists
        if self.category then
            local categoryItems = lia.data.get("category_items_" .. self.category, {})
            categoryItems[itemID] = nil
            lia.data.set("category_items_" .. self.category, categoryItems)
        end
        -- Log permanent removal
        lia.log.add(nil, "item_permanently_removed", itemID, self.uniqueID)
        -- Notify administrators of rare item removal
        if self:getData("rarity") == "legendary" then
            lia.chat.send(lia.util.getAdmins(), "Legendary item permanently removed: " .. self:getName())
        end
    end

---

onRestored

📋 Purpose

Called when the item is loaded from the database

⏰ When Called

Automatically when item data is restored from storage

⚙️ Parameters

Parameter	Type	Description
inventory	Inventory	The inventory this item belongs to

↩️ Returns

• Nothing

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    function ITEM:onRestored(inventory)
        print("Item restored from database")
    end

📊 Medium Complexity

    function ITEM:onRestored(inventory)
        -- Validate restored data
        if self:getData("durability") and self:getData("durability") < 0 then
            self:setData("durability", 0)
        end
    end

⚙️ High Complexity

    function ITEM:onRestored(inventory)
        -- Comprehensive restoration logic
        local itemID = self:getID()
        -- Restore complex relationships
        self:restoreOwnershipLinks()
        self:restoreEnchantments()
        self:validateDataIntegrity()
        -- Update tracking systems
        local trackingData = lia.data.get("item_tracking", {})
        trackingData[itemID].restored = os.time()
        trackingData[itemID].inventory = inventory:getID()
        lia.data.set("item_tracking", trackingData)
        -- Apply restoration effects
        if self:getData("temporary") then
            local expiryTime = self:getData("expiryTime")
            if expiryTime and expiryTime < os.time() then
                -- Item has expired, schedule removal
                timer.Simple(0, function()
                    if IsValid(self) then
                        self:remove()
                        lia.log.add(nil, "expired_item_removed_on_restore", itemID)
                    end
                end)
            end
        end
        -- Trigger restoration hooks
        hook.Run("OnItemRestored", self, inventory)
    end

---

onRestored

📋 Purpose

Called when the item is loaded from the database

⏰ When Called

Automatically when item data is restored from storage

⚙️ Parameters

Parameter	Type	Description
inventory	Inventory	The inventory this item belongs to

↩️ Returns

• Nothing

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    function ITEM:onRestored(inventory)
        print("Item restored from database")
    end

📊 Medium Complexity

    function ITEM:onRestored(inventory)
        -- Validate restored data
        if self:getData("durability") and self:getData("durability") < 0 then
            self:setData("durability", 0)
        end
    end

⚙️ High Complexity

    function ITEM:onRestored(inventory)
        -- Comprehensive restoration logic
        local itemID = self:getID()
        -- Restore complex relationships
        self:restoreOwnershipLinks()
        self:restoreEnchantments()
        self:validateDataIntegrity()
        -- Update tracking systems
        local trackingData = lia.data.get("item_tracking", {})
        trackingData[itemID].restored = os.time()
        trackingData[itemID].inventory = inventory:getID()
        lia.data.set("item_tracking", trackingData)
        -- Apply restoration effects
        if self:getData("temporary") then
            local expiryTime = self:getData("expiryTime")
            if expiryTime and expiryTime < os.time() then
                -- Item has expired, schedule removal
                timer.Simple(0, function()
                    if IsValid(self) then
                        self:remove()
                        lia.log.add(nil, "expired_item_removed_on_restore", itemID)
                    end
                end)
            end
        end
        -- Trigger restoration hooks
        hook.Run("OnItemRestored", self, inventory)
    end

---

onRestored

📋 Purpose

Called when the item is loaded from the database

⏰ When Called

Automatically when item data is restored from storage

⚙️ Parameters

Parameter	Type	Description
inventory	Inventory	The inventory this item belongs to

↩️ Returns

• Nothing

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    function ITEM:onRestored(inventory)
        print("Item restored from database")
    end

📊 Medium Complexity

    function ITEM:onRestored(inventory)
        -- Validate restored data
        if self:getData("durability") and self:getData("durability") < 0 then
            self:setData("durability", 0)
        end
    end

⚙️ High Complexity

    function ITEM:onRestored(inventory)
        -- Comprehensive restoration logic
        local itemID = self:getID()
        -- Restore complex relationships
        self:restoreOwnershipLinks()
        self:restoreEnchantments()
        self:validateDataIntegrity()
        -- Update tracking systems
        local trackingData = lia.data.get("item_tracking", {})
        trackingData[itemID].restored = os.time()
        trackingData[itemID].inventory = inventory:getID()
        lia.data.set("item_tracking", trackingData)
        -- Apply restoration effects
        if self:getData("temporary") then
            local expiryTime = self:getData("expiryTime")
            if expiryTime and expiryTime < os.time() then
                -- Item has expired, schedule removal
                timer.Simple(0, function()
                    if IsValid(self) then
                        self:remove()
                        lia.log.add(nil, "expired_item_removed_on_restore", itemID)
                    end
                end)
            end
        end
        -- Trigger restoration hooks
        hook.Run("OnItemRestored", self, inventory)
    end

---

onRestored

📋 Purpose

Called when the item is loaded from the database

⏰ When Called

Automatically when item data is restored from storage

⚙️ Parameters

Parameter	Type	Description
inventory	Inventory	The inventory this item belongs to

↩️ Returns

• Nothing

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    function ITEM:onRestored(inventory)
        print("Item restored from database")
    end

📊 Medium Complexity

    function ITEM:onRestored(inventory)
        -- Validate restored data
        if self:getData("durability") and self:getData("durability") < 0 then
            self:setData("durability", 0)
        end
    end

⚙️ High Complexity

    function ITEM:onRestored(inventory)
        -- Comprehensive restoration logic
        local itemID = self:getID()
        -- Restore complex relationships
        self:restoreOwnershipLinks()
        self:restoreEnchantments()
        self:validateDataIntegrity()
        -- Update tracking systems
        local trackingData = lia.data.get("item_tracking", {})
        trackingData[itemID].restored = os.time()
        trackingData[itemID].inventory = inventory:getID()
        lia.data.set("item_tracking", trackingData)
        -- Apply restoration effects
        if self:getData("temporary") then
            local expiryTime = self:getData("expiryTime")
            if expiryTime and expiryTime < os.time() then
                -- Item has expired, schedule removal
                timer.Simple(0, function()
                    if IsValid(self) then
                        self:remove()
                        lia.log.add(nil, "expired_item_removed_on_restore", itemID)
                    end
                end)
            end
        end
        -- Trigger restoration hooks
        hook.Run("OnItemRestored", self, inventory)
    end

---

sync

📋 Purpose

Synchronizes item instance data to clients

⏰ When Called

When item data needs to be sent to clients

⚙️ Parameters

Parameter	Type	Description
recipient	Player	Optional specific client to sync to, broadcasts if nil

↩️ Returns

• Nothing

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    item:sync()

📊 Medium Complexity

    item:sync(specificPlayer)

⚙️ High Complexity

    local function syncItemToGroup(item, players)
        -- Send different data based on player permissions
        for _, player in ipairs(players) do
            if player:canAccessItem(item) then
                item:sync(player)
            else
                -- Send limited data
                net.Start("liaItemLimited")
                net.WriteUInt(item:getID(), 32)
                net.WriteString(item:getName())
                net.Send(player)
            end
        end
    end
    syncItemToGroup(myItem, nearbyPlayers)

---

setData

📋 Purpose

Sets item data and synchronizes changes to clients and database

⏰ When Called

When item data needs to be updated and persisted

⚙️ Parameters

Parameter	Type	Description
key	string	The data key to set
value	any	The value to set
receivers	table	Optional specific clients to notify
noSave	boolean	Optional boolean to skip database saving
noCheckEntity	boolean	Optional boolean to skip entity data sync

↩️ Returns

• Nothing

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    item:setData("durability", 50)

📊 Medium Complexity

    item:setData("owner", player:GetName())
    item:setData("acquired", os.time())

⚙️ High Complexity

    local function applyDamageToItem(item, damage)
        local currentDurability = item:getData("durability", 100)
        local newDurability = math.max(0, currentDurability - damage)
        -- Set durability and sync to all players
        item:setData("durability", newDurability)
        -- If item is broken, apply broken effects
        if newDurability == 0 then
            item:setData("broken", true)
            item:setData("repairCost", item:getData("baseRepairCost", 100) * 2)
            -- Notify owner
            local owner = item:getOwner()
            if owner then
                owner:notify("Your " .. item:getName() .. " has broken!")
            end
        end
        -- Log damage
        lia.log.add(nil, "item_damaged", item:getID(), damage, newDurability)
    end
    applyDamageToItem(myItem, 25)

---

addQuantity

📋 Purpose

Adds to the item's quantity and synchronizes the change

⏰ When Called

When increasing item stack size

⚙️ Parameters

Parameter	Type	Description
quantity	number	Amount to add to the quantity
receivers	table	Optional specific clients to notify
noCheckEntity	boolean	Optional boolean to skip entity sync

↩️ Returns

• Nothing

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    item:addQuantity(5)

📊 Medium Complexity

    item:addQuantity(1, player) -- Notify specific player

⚙️ High Complexity

    local function combineStacks(item1, item2)
        if item1.uniqueID == item2.uniqueID then
            local combinedQuantity = item1:getQuantity() + item2:getQuantity()
            local maxStack = item1.maxQuantity or 1
            if combinedQuantity <= maxStack then
                -- Combine into one stack
                item1:setQuantity(combinedQuantity)
                item2:remove()
                return true, "Items combined successfully"
            else
                -- Fill first stack and adjust second
                local overflow = combinedQuantity - maxStack
                item1:setQuantity(maxStack)
                item2:setQuantity(overflow)
                return true, "Items partially combined"
            end
        end
        return false, "Items cannot be combined"
    end
    local success, message = combineStacks(stack1, stack2)

---

setQuantity

📋 Purpose

Sets the item's quantity and synchronizes the change

⏰ When Called

When changing item stack size or count

⚙️ Parameters

Parameter	Type	Description
quantity	number	New quantity value
receivers	table	Optional specific clients to notify
noCheckEntity	boolean	Optional boolean to skip entity sync

↩️ Returns

• Nothing

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    item:setQuantity(10)

📊 Medium Complexity

    item:setQuantity(0) -- Remove all items from stack

⚙️ High Complexity

    local function splitStack(item, splitAmount)
        local currentQuantity = item:getQuantity()
        if splitAmount >= currentQuantity then
            return false, "Cannot split more than available"
        end
        -- Create new item instance
        local newItem = lia.item.new(item.uniqueID, 1)
        newItem:setQuantity(splitAmount)
        newItem:setData("splitFrom", item:getID())
        -- Reduce original stack
        item:setQuantity(currentQuantity - splitAmount)
        -- Add new stack to same inventory
        local inventory = lia.inventory.instances[item.invID]
        if inventory then
            inventory:add(newItem)
            return true, newItem
        end
        return false, "Failed to add split item to inventory"
    end
    local success, newStack = splitStack(myItem, 5)

---

interact

📋 Purpose

Handles player interaction with items (use, drop, etc.)

⏰ When Called

When a player attempts to interact with an item

⚙️ Parameters

Parameter	Type	Description
action	string	The interaction action (e.g., "use", "drop")
client	Player	The player performing the action
entity	Entity	Optional entity involved in the interaction
data	any	Optional additional data for the interaction

↩️ Returns

• Boolean indicating if the interaction was successful

🌐 Realm

Server

💡 Example Usage

🔰 Low Complexity

    item:interact("use", player)

📊 Medium Complexity

    item:interact("drop", player, nil, {position = dropPos})

⚙️ High Complexity

    local function handleComplexInteraction(item, action, player, entity, data)
        -- Pre-interaction validation
        if action == "use" and item:getData("cooldown") then
            local lastUsed = item:getData("lastUsed", 0)
            if CurTime() - lastUsed < item:getData("cooldown") then
                player:notifyError("Item is on cooldown")
                return false
            end
        end
        -- Perform interaction
        local success = item:interact(action, player, entity, data)
        if success then
            -- Post-interaction effects
            if action == "use" then
                item:setData("lastUsed", CurTime())
                item:setData("uses", item:getData("uses", 0) + 1)
                -- Check for breakage
                if item:getData("uses") >= item:getData("maxUses", 100) then
                    player:notify("Your " .. item:getName() .. " has broken!")
                    item:setData("broken", true)
                end
            end
            -- Log the interaction
            lia.log.add(player, "item_interaction", action, item:getID(), item:getName())
        end
        return success
    end
    local success = handleComplexInteraction(myItem, "use", player)

---

getCategory

📋 Purpose

Gets the localized category name for the item

⏰ When Called

When displaying or organizing items by category

↩️ Returns

• String representing the localized category name

🌐 Realm

Shared

💡 Example Usage

🔰 Low Complexity

    local category = item:getCategory()

📊 Medium Complexity

    if item:getCategory() == "weapons" then
        -- Handle weapon-specific logic
    end

⚙️ High Complexity

    local function organizeItemsByCategory(items)
        local categories = {}
        for _, item in ipairs(items) do
            local category = item:getCategory()
            categories[category] = categories[category] or {}
            table.insert(categories[category], item)
        end
        -- Sort categories alphabetically
        local sortedCategories = {}
        for categoryName, categoryItems in pairs(categories) do
            table.insert(sortedCategories, {
                name  = categoryName,
                items = categoryItems,
                count = #categoryItems
            })
        end
        table.sort(sortedCategories, function(a, b) return a.name < b.name end)
        return sortedCategories
    end
    local organizedItems = organizeItemsByCategory(playerInventory:getItems())

---