LootboxExports
Server Exports
Last updated on
registerLootbox
Register a new lootbox at runtime from another resource.
exports.sleepless_lootbox:registerLootbox(name, data)Parameters
| Parameter | Type | Description |
|---|---|---|
name | string | Unique identifier for the lootbox (typically the item name) |
data | table | Lootbox configuration data |
Data Structure
| Property | Type | Required | Description |
|---|---|---|---|
label | string | Yes | Display name shown in UI |
description | string | No | Description shown in UI |
image | string | No | Custom image URL for the lootbox |
registerItem | boolean | No | Auto-register as usable item (default: true) |
items | table | Yes | Array of weighted loot items |
rarityThresholds | table | No | Override global rarity weight thresholds for this lootbox |
Returns
| Type | Description |
|---|---|
boolean | true if registration was successful, false if lootbox already exists or has no items |
Example
exports.sleepless_lootbox:registerLootbox('mystery_box', {
label = 'Mystery Box',
description = 'Who knows what\'s inside?',
registerItem = true,
items = {
{ 50, { name = 'bread', amount = 5 } },
{ 30, { name = 'water', amount = 3 } },
{ 15, { name = 'bandage', amount = 2 } },
{ 5, { name = 'medkit', amount = 1, rarity = 'rare' } },
},
})Wrap your registerLootbox call in a SetTimeout or wait for the resource to be fully loaded to ensure the export is available.
unregisterLootbox
Remove a previously registered lootbox.
exports.sleepless_lootbox:unregisterLootbox(name)Parameters
| Parameter | Type | Description |
|---|---|---|
name | string | The lootbox identifier to remove |
Example
exports.sleepless_lootbox:unregisterLootbox('mystery_box')getLootbox
Get the configuration data for a specific lootbox.
local data = exports.sleepless_lootbox:getLootbox(name)Parameters
| Parameter | Type | Description |
|---|---|---|
name | string | The lootbox identifier |
Returns
| Type | Description |
|---|---|
table|nil | Lootbox data or nil if not found |
Example
local gunCase = exports.sleepless_lootbox:getLootbox('gun_case')
if gunCase then
print('Found lootbox:', gunCase.label)
endgetAllLootboxes
Get all registered lootboxes.
local lootboxes = exports.sleepless_lootbox:getAllLootboxes()Returns
| Type | Description |
|---|---|
table | Table of all lootbox configurations keyed by name |
Example
local allBoxes = exports.sleepless_lootbox:getAllLootboxes()
for name, data in pairs(allBoxes) do
print(name, data.label)
endopen
Open a lootbox for a player, triggering the roll animation and giving the reward.
exports.sleepless_lootbox:open(source, caseName, skipItemRemoval)Parameters
| Parameter | Type | Description |
|---|---|---|
source | number | Player server ID |
caseName | string | The lootbox identifier to open |
skipItemRemoval | boolean | If true, the lootbox item won't be removed from inventory |
Returns
| Type | Description |
|---|---|
boolean | true if the lootbox was opened successfully, false otherwise |
Set skipItemRemoval to true if you handle item removal yourself (e.g., via ox_target or custom triggers).
Example: Custom Trigger
RegisterNetEvent('myresource:openCase', function(caseName)
local src = source
-- Remove the item manually first
exports.ox_inventory:RemoveItem(src, caseName, 1)
-- Open with skipItemRemoval = true
exports.sleepless_lootbox:open(src, caseName, true)
end)Example: Standard Usage
-- Let sleepless_lootbox handle item removal
exports.sleepless_lootbox:open(source, 'gun_case', false)getPreview
Get preview data for a lootbox, including all items with their calculated drop chances.
local preview = exports.sleepless_lootbox:getPreview(caseName)Parameters
| Parameter | Type | Description |
|---|---|---|
caseName | string | The lootbox identifier |
Returns
| Type | Description |
|---|---|
RollItem[]|nil | Array of items with calculated chances, or nil if lootbox not found |
Example
local items = exports.sleepless_lootbox:getPreview('gun_case')
if items then
for _, item in ipairs(items) do
print(item.name, item.chance .. '%', item.rarity)
end
endregisterRewardHook
Register a custom reward handler for a specific reward type. This allows external resources to handle non-item rewards like vehicles, bank deposits, or any custom reward logic.
exports.sleepless_lootbox:registerRewardHook(rewardType, hook)Parameters
| Parameter | Type | Description |
|---|---|---|
rewardType | string | The reward type to handle (e.g., 'vehicle', 'bank') |
hook | function | Handler function that receives (source, reward, caseName) |
Hook Function
The hook function receives three parameters:
| Parameter | Type | Description |
|---|---|---|
source | number | Player server ID |
reward | RollItem | The reward data including rewardType and rewardData |
caseName | string | The lootbox identifier |
Hook Return Value
| Return | Behavior |
|---|---|
true | Reward was handled by the hook, skip default item logic |
false or nil | Hook did not handle the reward, fall back to default item logic |
If a reward has a rewardType set but no hook is registered for it, the system will log a warning and fall back to default item behavior to prevent reward loss.
Example: Vehicle Reward Hook
-- Register a handler for 'vehicle' reward types
exports.sleepless_lootbox:registerRewardHook('vehicle', function(source, reward, caseName)
local data = reward.rewardData
-- data contains whatever you put in rewardData in your config
-- e.g., { model = 'adder', garage = 'legion' }
-- Example with qbx_vehicles
local success = exports.qbx_vehicles:CreatePlayerVehicle({
source = source,
model = data.model,
garage = data.garage or 'legion',
})
if success then
-- Notify the player
TriggerClientEvent('ox_lib:notify', source, {
title = 'Vehicle Won!',
description = 'Your ' .. reward.label .. ' has been added to your garage',
type = 'success',
})
return true -- We handled this reward
end
return false -- Something went wrong, fall back to default behavior
end)Example: Bank Money Hook
-- Register a handler for 'bank' reward types
exports.sleepless_lootbox:registerRewardHook('bank', function(source, reward, caseName)
local data = reward.rewardData
-- data contains: { amount = 50000 }
-- Example with QBCore
local Player = exports.qbx_core:GetPlayer(source)
if Player then
Player.Functions.AddMoney('bank', data.amount, 'lootbox-reward')
return true
end
return false
end)removeRewardHook
Remove a previously registered reward hook.
exports.sleepless_lootbox:removeRewardHook(rewardType)Parameters
| Parameter | Type | Description |
|---|---|---|
rewardType | string | The reward type to remove the handler for |
Example
-- Remove the vehicle hook (e.g., when your resource stops)
exports.sleepless_lootbox:removeRewardHook('vehicle')If you register hooks from another resource, consider removing them in that resource's onResourceStop handler to prevent errors if the resource restarts.