Special Slots

Special Slots Events API

The Special Slots API allows developers to register custom events for special inventory slots (tool, armour, drug, radio, backpack, identification, phone, tablet, key, wallet).

Available Slots

Available slots are configured via the inventory:specialslots convar in your server.cfg. By default, they include:

Slot	Description
tool	Tools
armour	Protective vests
drug	Substances / medications
radio	Communication radios
backpack	Backpacks
identification	Identity documents
phone	Mobile phones
tablet	Electronic tablets
key	Keys
wallet	Wallets

---

Registering Events

Use the RegisterSpecialSlotEvent export to register a slot with its events:

exports.lvs_inventory:RegisterSpecialSlotEvent('tool', {
    onEquip = function(slotData)
        print('Tool equipped')
    end,

    onUnequip = function(slotData)
        print('Tool unequipped')
    end,

    onTick = function(slotData)
        -- Logic that runs while the item is equipped
    end,

    tickRate = 1000 -- (optional) Interval in ms. Default: 100
})

---

Available Events

onEquip

Triggered when an item is placed in the special slot.

Parameters:

Parameter	Type	Description
slotData	table	Data of the equipped item (name, count, metadata, etc.)

Example:

onEquip = function(slotData)
    print('Item equipped:', slotData.name)
    print('Count:', slotData.count)
    print('Metadata:', json.encode(slotData.metadata))
end

onUnequip

Triggered when an item is removed from the special slot.

Parameters:

Parameter	Type	Description
slotData	table	Data of the item that was unequipped

Example:

onUnequip = function(slotData)
    if slotData then
        print('Item unequipped:', slotData.name)
    else
        print('Slot cleared without previous data')
    end
end

onTick

Executed periodically while the item remains in the special slot.

Parameters:

Parameter	Type	Description
slotData	table	Updated data of the equipped item

Example:

onTick = function(slotData)
    -- Check if a tool has durability
    if slotData.metadata.durability then
        if slotData.metadata.durability <= 0 then
            -- Notify the player
            exports['ox_lib']:notify({
                title = 'Broken tool',
                description = 'Your tool has worn out completely',
                type = 'warning'
            })
        end
    end
end

Tick Rate Configuration

You can configure the frequency of onTick execution using the tickRate property in milliseconds:

exports.lvs_inventory:RegisterSpecialSlotEvent('phone', {
    onTick = function(slotData)
        -- Runs every 5 seconds
        checkPhoneSignal(slotData.metadata.number)
    end,
    
    tickRate = 5000 -- 5 seconds
})

If tickRate is not specified, the default value is 100ms.

Performance Note: Very low values (such as 1ms) can impact server performance. Use the highest value that is functional for your use case.

---

Complete Examples

Tool with Durability

exports.lvs_inventory:RegisterSpecialSlotEvent('tool', {
    onEquip = function(slotData)
        exports['ox_lib']:notify({
            title = 'Tool equipped',
            description = string.format('%s ready to use', slotData.label),
            type = 'success'
        })
    end,

    onUnequip = function(slotData)
        exports['ox_lib']:notify({
            title = 'Tool stored',
            description = string.format('%s stored away', slotData.label),
            type = 'info'
        })
    end,

    onTick = function(slotData)
        -- Reduce durability over time
        if slotData.metadata.durability and slotData.metadata.durability > 0 then
            -- Wear logic here...
        end
    end,

    tickRate = 1000 -- Every second
})

Radio with Channel Verification

exports.lvs_inventory:RegisterSpecialSlotEvent('radio', {
    onEquip = function(slotData)
        local channel = slotData.metadata.channel or 1
        SetRadioChannel(channel)
        exports['ox_lib']:notify({
            title = 'Radio turned on',
            description = string.format('Channel: %d', channel),
            type = 'success'
        })
    end,

    onUnequip = function(slotData)
        SetRadioChannel(0) -- Turn off radio
        exports['ox_lib']:notify({
            title = 'Radio turned off',
            type = 'info'
        })
    end,

    onTick = function(slotData)
        -- Check if there is signal on the current channel
        local channel = slotData.metadata.channel or 1
        if not HasRadioSignal(channel) then
            -- No signal...
        end
    end,

    tickRate = 2000 -- Every 2 seconds
})

Phone with State Updates

local phoneActive = false

exports.lvs_inventory:RegisterSpecialSlotEvent('phone', {
    onEquip = function(slotData)
        phoneActive = true
        local number = slotData.metadata.number or 'Unknown'
        exports['ox_lib']:notify({
            title = 'Phone started',
            description = string.format('Number: %s', number),
            type = 'success'
        })
        OpenPhoneUI()
    end,

    onUnequip = function(slotData)
        phoneActive = false
        ClosePhoneUI()
        exports['ox_lib']:notify({
            title = 'Phone turned off',
            type = 'info'
        })
    end,

    onTick = function(slotData)
        if phoneActive then
            -- Check for pending notifications
            CheckPendingNotifications()
        end
    end,

    tickRate = 3000 -- Every 3 seconds
})

Manual Event Triggering

You can manually trigger events using the TriggerSpecialSlotEvent export:

local success, result = exports.lvs_inventory:TriggerSpecialSlotEvent('tool', 'onEquip', mySlotData)

if not success then
    print('Error executing event:', result)
end

Parameters:

Parameter	Type	Description
slotName	string	Name of the slot (tool, radio, etc.)
eventType	string	Event type (onEquip, onUnequip, onTick)
...	any	Additional arguments for the callback

Returns:

Value	Type	Description
success	boolean	Whether the callback executed without errors
result/error	any	Callback result or error message

Important Notes

Slot Data (slotData)

The slotData parameter contains the equipped item's information and is automatically updated. Its general structure includes:

{
    name = "lvs_wrench",         -- Item name
    label = "Wrench",            -- Display label
    count = 1,                   -- Quantity
    weight = 500,                -- Weight in grams
    slot = 16,                   -- Slot number
    metadata = {                 -- Custom metadata
        durability = 85,
        description = "A robust tool"
        -- ...your own metadata
    }
}

Avoid Heavy Operations in onTick

If you need to perform expensive operations inside onTick, consider using Citizen.CreateThread to avoid blocking the cycle:

onTick = function(slotData)
    if not processing then
        processing = true
        Citizen.CreateThread(function()
            -- Heavy operation here
            processData(slotData)
            processing = false
        end)
    end
end