Examples

Practical examples showing how to integrate sleepless_lootbox with other resources and systems.

Integration with ox_target

Use ox_target to let players open a lootbox by interacting with an object in the world.

-- Client side
exports.ox_target:addGlobalObject({
    {
        name = 'open_lootbox_crate',
        icon = 'fas fa-box-open',
        label = 'Open Crate',
        items = 'mystery_crate_item',
        onSelect = function(data)
            TriggerServerEvent('lootbox:openCrate')
        end,
    }
})
 
-- Server side
RegisterNetEvent('lootbox:openCrate', function()
    local src = source
    if exports.ox_inventory:RemoveItem(src, 'mystery_crate_item', 1) then
        exports.sleepless_lootbox:open(src, 'mystery_crate_item', true)
    end
end)

When handling item removal yourself, always pass skipItemRemoval = true to the open export to prevent double-removal.

Dynamic Event Rewards

Give players a random lootbox as a reward for completing an event, without requiring them to have the item in their inventory.

-- Server side: Give random lootbox as event reward
RegisterNetEvent('myevent:claimReward', function()
    local src = source
    local lootboxes = { 'gun_case', 'supply_crate', 'vip_case' }
    local randomBox = lootboxes[math.random(#lootboxes)]
 
    -- Open directly without requiring the item
    exports.sleepless_lootbox:open(src, randomBox, true)
end)

Preview Before Purchase

Show players what a lootbox contains before they decide to buy it from a shop.

-- Client side: Show preview in a shop
RegisterNetEvent('shop:previewLootbox', function(caseName)
    exports.sleepless_lootbox:preview(caseName)
end)

Register Lootboxes from Another Resource

Dynamically register a lootbox at runtime from a separate resource, for example during a server event or seasonal content.

-- Server side
    exports.sleepless_lootbox:registerLootbox('event_box', {
        label = 'Holiday Event Box',
        description = 'Limited-time holiday rewards!',
        registerItem = true,
        items = {
            { 50, { name = 'bread', amount = 10 } },
            { 30, { name = 'water', amount = 10 } },
            { 15, { name = 'medkit', amount = 3 } },
            { 4, { name = 'armour', amount = 2, rarity = 'rare' } },
            { 1, { name = 'WEAPON_PISTOL_MK2', amount = 1, rarity = 'legendary' } },
        },
    })

⚠️

Make sure sleepless_lootbox is fully started before calling registerLootbox.

Safe Open with Rolling Check

Prevent players from opening a lootbox while another roll is still in progress.

-- Client side
local function tryOpenCase(caseName)
    if exports.sleepless_lootbox:isRolling() then
        -- Notify player they need to wait
        lib.notify({
            title = 'Lootbox',
            description = 'Please wait for the current roll to finish',
            type = 'error',
        })
        return
    end
 
    TriggerServerEvent('myresource:openCase', caseName)
end

Bonus Items (Hidden Rewards)

Award additional items alongside the main reward without showing them in the UI. Useful for giving ammo with weapons.

-- In config.lua
config.lootboxes = {
    ['gun_case'] = {
        label = 'Gun Case',
        description = 'Contains various firearms with ammo',
        items = {
            { 40, {
                name = 'WEAPON_PISTOL',
                amount = 1,
                -- Bonus items are awarded but NOT shown in the UI
                bonusItems = {
                    { name = 'ammo-9', amount = 50 },
                }
            } },
            { 0.1, {
                name = 'WEAPON_CARBINERIFLE',
                amount = 1,
                bonusItems = {
                    { name = 'ammo-rifle', amount = 250 },
                    { name = 'armour', amount = 2 },
                    { name = 'money', amount = 5000 },
                }
            } },
        },
    },
}

Bonus items are given server-side when the reward is claimed. Players will see them appear in their inventory but won't see them during the roll animation.

Custom Reward Types with Hooks

Use custom reward types to handle non-item rewards like vehicles or bank deposits. Register hooks in your own resource to handle these reward types.

Vehicle Reward Hook

-- Server side
exports.sleepless_lootbox:registerRewardHook('vehicle', function(source, reward, caseName)
    local data = reward.rewardData
    
    if not data or not data.model then
        print('Vehicle reward missing model data')
        return false -- Return false to fall back to default item behavior
    end
    
    lib.notify(source, {
        title = 'Vehicle Won!',
        description = ('You won a %s! Check your garage.'):format(reward.label),
        type = 'success',
    })
    
    return true -- Fall back to default if something went wrong
end)

Bank Money Reward Hook

-- Server side
exports.sleepless_lootbox:registerRewardHook('bank', function(source, reward, caseName)
    local data = reward.rewardData
    
    if not data or not data.amount then
        return false
    end
    
    lib.notify(source, {
        title = 'Bank Deposit',
        description = ('$%s has been deposited to your bank!'):format(data.amount),
        type = 'success',
    })
    
    return true
end)

Lootbox Config with Custom Rewards

-- In config.lua
config.lootboxes = {
    ['vehicle_crate'] = {
        label = 'Vehicle Crate',
        description = 'Win a brand new vehicle!',
        items = {
            { 40, {
                name = 'vehicle_blista', -- Unique identifier (not an actual item, just for internal tracking/logging)
                label = 'Blista', -- Display label in UI (required for custom reward types)
                amount = 1,
                image = 'nui://ox_inventory/web/images/vehicle_crate.webp',
                rewardType = 'vehicle', -- Custom reward type
                rewardData = { model = 'blista', garage = 'legion' }, -- Data passed to hook
            } },
            { 0.26, {
                name = 'vehicle_adder',
                label = 'Adder',
                amount = 1,
                image = 'nui://ox_inventory/web/images/vehicle_crate.webp',
                rarity = 'legendary', -- Can still specify rarity
                rewardType = 'vehicle',
                rewardData = { model = 'adder', garage = 'legion' },
            } },
        },
    },
 
    ['vip_rewards'] = {
        label = 'VIP Rewards',
        description = 'Premium rewards including bank deposits',
        items = {
            { 50, { name = 'armour', amount = 5 } }, -- Regular item reward
            { 30, {
                name = 'bank_deposit_10k', -- Unique identifier (used for logging, not an actual item)
                label = '$10,000 Bank Deposit', -- Required: display label since this isn't a real item
                amount = 1,
                image = 'nui://ox_inventory/web/images/money.webp',
                rewardType = 'bank',
                rewardData = { amount = 10000 },
            } },
            { 1, {
                name = 'bank_deposit_100k', -- Unique identifier
                label = '$100,000 Bank Deposit', -- Display label
                amount = 1,
                image = 'nui://ox_inventory/web/images/money.webp',
                rarity = 'legendary',
                rewardType = 'bank',
                rewardData = { amount = 100000 },
            } },
        },
    },
}

⚠️

If a custom rewardType is set but no hook is registered, the system will log a warning and fall back to treating it as a regular item. This prevents rewards from being lost but may not give the intended reward.

Removing a Hook

You can remove a previously registered hook if needed:

-- Server side
exports.sleepless_lootbox:removeRewardHook('vehicle')

Client Ped Manager