Installation

Requirements

Required

• ox_lib — Utility library used for lib.notify and other helpers (GitHub (opens in a new tab))

Optional (Auto-detected)

• Framework — ESX (es_extended), QB-Core (qb-core), or QBox (qbx_core). If none are present the resource runs standalone.
• Inventory — ox_inventory, qs-inventory, codem-inventory, origen_inventory, tgiann-inventory, ps-inventory, qb-inventory, or ESX legacy.
• Notify — ox_lib, okokNotify, qbx_core, qb-core, es_extended, or a native fallback.

Installation Steps

Step 1: Download the Resource

Clone or download legends_cases from GitHub:

cd resources
git clone https://github.com/LegendsDevFiveM/legends_cases.git

Or grab the latest release ZIP from the GitHub releases (opens in a new tab) page.

Step 2: Extract to Resources

Place the legends_cases folder into your server's resources directory.

resources/
└── legends_cases/
    ├── fxmanifest.lua
    ├── config.lua
    ├── bridge/
    │   ├── init.lua
    │   ├── framework.lua
    │   ├── inventory.lua
    │   ├── notify.lua
    │   └── usable.lua
    ├── client/
    │   └── main.lua
    ├── server/
    │   └── main.lua
    ├── shared/
    │   └── rarities.lua
    ├── locales/
    │   └── en.lua
    └── web/
        ├── src/
        └── dist/
            ├── index.html
            ├── assets/
            └── sounds/

Step 3: Add to Server Config

Add the following to your server.cfg:

# Required
ensure ox_lib

# Then the cases resource
ensure legends_cases

Step 4: Register Case Items in Your Inventory

Each case is an item in your inventory. The way you wire it up depends on which inventory you run.

ox_inventory

In ox_inventory/data/items.lua add the case item with the legends_cases.openCase client export:

['starter_case'] = {
    label = 'Starter Case',
    weight = 100,
    stack = true,
    close = true,
    description = 'Open this case for a chance at rare items.',
    client = {
        export = 'legends_cases.openCase',
    },
},

qb-inventory

In qb-core/shared/items.lua add the case as a usable item — no extra client wiring is needed because legends_cases registers it via QBCore.Functions.CreateUseableItem:

['starter_case'] = {
    name = 'starter_case',
    label = 'Starter Case',
    weight = 100,
    type = 'item',
    image = 'starter_case.png',
    unique = false,
    useable = true,
    shouldClose = true,
    combinable = nil,
    description = 'Open this case for a chance at rare items.'
},

ESX legacy / qs-inventory / codem-inventory / origen / tgiann / ps-inventory

Add the item to your inventory's items file with useable = true (or the equivalent flag for that inventory). legends_cases registers each case as usable through the bridge automatically.

Step 5: Define Cases in config.lua

Add a case definition to Config.Cases for every case item you registered above:

Config.Cases = {
    ['starter_case'] = {
        label = 'Starter Case',
        items = {
            { item = 'bandage',        count = 5, chance = 35.0, rarity = 'milspec'    },
            { item = 'lockpick',       count = 2, chance = 25.0, rarity = 'milspec'    },
            { item = 'radio',          count = 1, chance = 18.0, rarity = 'restricted' },
            { item = 'phone',          count = 1, chance =  6.0, rarity = 'classified' },
            { item = 'WEAPON_STUNGUN', count = 1, chance =  3.0, rarity = 'covert'     },
            { item = 'WEAPON_PISTOL',  count = 1, chance =  0.9, rarity = 'gold'       },
        },
    },
}

See Adding a Case for the full cookbook (multiple cases, custom rarities, weighted balancing).

Step 6: Restart and Test

ensure legends_cases

Then in-game (as an admin):

/giveitem [your_id] starter_case 1

Open your inventory, use the case, and the roulette wheel should appear and spin.

Verification

After installation:

1. Use a case item — the roulette wheel UI should appear with screen-blur fade-in.
2. The reel should spin for ~6.5 seconds and stop on a winning slot with rarity-tiered color.
3. The reward modal should show, then the item should land in your inventory (or drop on the ground if your inventory is full).
4. Try using a second case item within 1.5 seconds of the first — the cooldown notification should block it.
5. Check the server console — any registration errors will surface there.

Building the UI from source (Optional)

You don't need to do this to run the resource. The pre-built bundle in web/dist/ is ready to ship. Only build from source if you want to fork the front-end:

cd resources/legends_cases/web
npm install
npm run build

This rewrites web/dist/. Restart legends_cases to pick up the new bundle.

Need help? Join our Discord (opens in a new tab) and open a support ticket!