Framework Setup

Each framework handles usable items differently. This page explains how to configure your item definitions so that lootbox cases work correctly with your framework and inventory system.

These steps are in addition to defining your lootboxes in config.lua. You must also ensure the item definitions exist in your inventory/framework so players can hold and use the items.

How It Works

When config.registerUsableItems = true (the default), sleepless_lootbox automatically registers each lootbox as a usable item through the framework bridge. However, the item must still be defined in your inventory or framework's item list — the resource can only register the use callback, not create the item definition itself.

ox_core + ox_inventory Setup

When using ox_core, usable items are handled through ox_inventory item definitions rather than the framework itself. For each lootbox case item, you need to add a server.export entry in your ox_inventory item definitions that points back to this resource.

Item Definition Format

Add your lootbox case items to ox_inventory/data/items.lua:

["gun_case"] = {
    label = "Gun Case",
    description = "Contains various firearms",
    weight = 500,
    stack = true,
    server = {
        export = "sleepless_lootbox.gun_case",
    },
},

⚠️

The server.export value must follow the format sleepless_lootbox.<item_name>, where <item_name> matches the lootbox key defined in your config.lua or registered via exports. Without this, using the item will do nothing.

How It Works (ox_core)

ox_inventory sees that the item has a server.export defined.
When a player uses the item, ox_inventory calls the matching export on sleepless_lootbox.
The ox framework bridge registers these exports automatically when config.registerUsableItems = true.
The lootbox opens for the player.

Complete Example

Here are all three default lootbox cases configured for ox_inventory:

-- ox_inventory/data/items.lua
 
["gun_case"] = {
    label = "Gun Case",
    description = "Contains various firearms",
    weight = 500,
    stack = true,
    server = {
        export = "sleepless_lootbox.gun_case",
    },
},
 
["supply_crate"] = {
    label = "Supply Crate",
    description = "Contains useful supplies and materials",
    weight = 1000,
    stack = true,
    server = {
        export = "sleepless_lootbox.supply_crate",
    },
},
 
["vip_case"] = {
    label = "VIP Case",
    description = "Premium rewards for VIP members",
    weight = 500,
    stack = true,
    server = {
        export = "sleepless_lootbox.vip_case",
    },
},

Don't forget to also add item definitions for any loot contents (weapons, items, etc.) that your lootboxes can reward. Those items don't need server.export — only the case items do.

Resource Order

Make sure your server.cfg starts resources in the correct order:

ensure ox_lib
ensure ox_core
ensure ox_inventory
ensure sleepless_lootbox

Reference File

The resource includes a _items.lua reference file in its root directory containing example item definitions for both ox_inventory and QBCore/Qbox. This file is not loaded at runtime — it's purely for reference. Copy the relevant entries into your framework's item configuration.

Adding Custom Lootboxes

When you register a new lootbox (either in config.lua or via the registerLootbox export), you need to add a matching item definition to your framework:

-- Add to ox_inventory/data/items.lua
["my_custom_case"] = {
    label = "My Custom Case",
    weight = 500,
    stack = true,
    server = {
        export = "sleepless_lootbox.my_custom_case",
    },
},

Troubleshooting

Item does nothing when used

ox_inventory: Verify the item definition includes server.export = "sleepless_lootbox.<item_name>" and that the item name matches your lootbox key exactly.
QBCore/Qbox: Verify the item definition has useable = true in the shared items table.
All frameworks: Ensure config.registerUsableItems = true in your config.lua.
All frameworks: Ensure sleepless_lootbox starts after your framework and inventory in server.cfg.

"No supported framework detected" warning

Check that your framework resource is started before sleepless_lootbox. The bridge auto-detects the framework by checking if the resource is started, so load order matters.

Lootbox opens but no item is given

This is likely an inventory bridge issue. Make sure the loot content items (not the case items) are also defined in your inventory system. The resource can only give items that your inventory recognizes.

Configuration Item Setup