Cases
This is a step-by-step installation guide, configuration preview, and full explanation of all settings for legends_cases.
If you lack programming experience, ensure you read each step thoroughly without skipping, as all documentation is essential!
Before submitting a support ticket or following the guides in this documentation, please make sure that you are running the latest version of the resource.
What is legends_cases?
legends_cases is an open-source FiveM case opener with a CS-style React roulette wheel NUI. Players use a case item from their inventory, the wheel spins for a configurable duration, and a weighted random reward is delivered. The resource ships pre-built — no npm install step is required to run — and includes six rarity tiers (Mil-Spec, Restricted, Classified, Covert, Gold, plus a custom slot), per-player cooldowns, pending-state protection, and inventory overflow handling that drops items to the ground rather than losing them.
The bridge auto-detects QBox, QB-Core, ESX, or standalone, and works with eight inventory systems out of the box.
Key Features
- CS-Style Roulette Wheel NUI — React-powered spinning reel with rarity-tier color coding; 6.5-second configurable spin (timing, reel length, and reveal delay all tunable)
- Weighted Loot Distribution — Chance values are weights, not percentages, so loot tables can be balanced freely without forcing the math to sum to 100
- Six Rarity Tiers — Mil-Spec, Restricted, Classified, Covert, Gold, plus a custom slot — each with its own color treatment on the reel and reveal modal
- Multi-Framework Out of the Box — Auto-detects QBox (
qbx_core), QB-Core (qb-core), ESX (es_extended), or standalone — no code changes required - Eight Inventory Integrations — ox_inventory (via export callback), qs-inventory, codem-inventory, origen_inventory, tgiann-inventory, ps-inventory, qb-inventory, ESX legacy
- Inventory Overflow Handling — Items drop to the ground if a player's inventory is full, so rewards are never silently lost
- Per-Player Rate Limiting — 1500 ms open cooldown plus a pending-state lock blocks spam-opens, double redemptions, and exploit timing
- Pre-Built UI, Zero Build Step — The React/Vite bundle ships in
web/dist/; only rebuild if you want to fork the front-end - Localizable — All player-facing text lives in
locales/*.lua; ships with English, easy to add more languages - Lightweight — ~3,300 LOC total, ox_lib is the only utility dependency
Default Rarity Tiers
| Tier | Rarity | Typical Use |
|---|---|---|
| 1 | Mil-Spec | Common consumables, low-value items |
| 2 | Restricted | Mid-tier consumables, basic tools |
| 3 | Classified | High-tier consumables, premium tools |
| 4 | Covert | Rare items, low-end weapons |
| 5 | Gold | Highest tier — top weapons, vehicles, premium gear |
| — | Custom | Reserved slot for server-specific styling (e.g., "Knife", "Foil", "Anniversary") |
Rarity colors and labels are defined in shared/rarities.lua and can be edited freely — the reel UI pulls them at runtime.
QBox Inventory Caveat
QBox is expected to use ox_inventory. Other inventories (qs-inventory, codem-inventory) work on QBox only if their exports don't depend on a qb-core player object. qb-inventory does not work on QBox.
Need help? Join our Discord (opens in a new tab) for support!
FAQ
Which frameworks and inventory systems does Legends Cases support?
Frameworks: ESX (es_extended), QB-Core (qb-core), QBox (qbx_core), and standalone — auto-detected at startup. Inventory: ox_inventory, qs-inventory, codem-inventory, origen_inventory, tgiann-inventory, ps-inventory, qb-inventory, and ESX legacy. Notify: ox_lib, okokNotify, qbx_core, qb-core, es_extended, plus a native fallback. QBox is expected to use ox_inventory; other inventories work on QBox only if their exports don't depend on a qb-core player object.
How do chance values work — are they percentages or weights?
They are weights, not percentages. Chance values do NOT need to sum to 100. A reel slot with chance = 50.0 is twice as likely as one with chance = 25.0, regardless of the total. This makes balancing easy because you can tweak any single item without recalculating every other entry.
What happens if a player's inventory is full when they win an item?
The item drops to the ground at the player's feet rather than disappearing. They get a notification (locale string inventory_full_drop) so they know to pick it up. Rewards are never silently lost — the case is consumed, the loot is dropped, the player retrieves it.
Does the resource require a build step?
No. The pre-built React/Vite bundle ships in web/dist/, so you can drop the resource into resources/, ensure it in server.cfg, restart, and play. The build step (cd web && npm install && npm run build) is only needed if you want to fork the front-end source under web/src/.
How does the cooldown and pending-state lock work?
Two layers. First, Config.OpenCooldown (default 1500 ms) blocks the same player from opening another case within that window — anti-spam. Second, the server tracks a per-player pending state — if a player already has a roulette spinning they cannot start another until the current reward is delivered. Together these prevent both flood opens and timing-based double redemptions.
Can I add custom rarity tiers or change the colors?
Yes. Edit shared/rarities.lua to rename tiers, add new ones, or swap the per-tier colors. The roulette reel and reveal modal pick up the changes automatically. The default tiers (milspec, restricted, classified, covert, gold) follow the CS-style color palette but nothing in the code is hardcoded to those names.