ORYNTDOCS
StoreSupport
Docs/Gameplay

Cases

v1.0.0Coming soon

Common, Rare, Epic, Legendary, Mythic and Godly cases with an Orynt-themed opening reel and /caseadmin reward editor. Each opening consumes one case and grants one weighted reward. No keys or vehicle rewards.

Installation

Install

  1. Keep this resource folder named orynt_cases.
  2. Register the six case items in your inventory: - ox_inventory (including ESX/Qbox with ox): paste entries from install/ox_items.lua inside the existing table in ox_inventory/data/items.lua. Keep consume = 0: the case script handles consumption after validating the opening. - QBCore with qb-inventory: merge install/qb_items.lua into qb-core/shared/items.lua. - ESX default inventory: review and run install/esx_items.sql against your ESX items table.
  3. Copy the six PNGs from install/item-images/ to your inventory image folder: e.g. ox_inventory/web/images/ or qb-inventory/html/images/. They are transparent, unbranded 100 × 100 icons.
  4. Install orynt_bridge (free, from Orynt Development). Start after ox_lib, orynt_bridge, your framework, and inventory:

cfg ensure ox_lib ensure orynt_bridge # Your framework and inventory must already be started here. ensure orynt_cases

  1. Framework admin groups work as configured in Config.AdminGroups. Alternatively:

cfg add_ace group.admin orynt_cases.admin allow

  1. Restart inventory/framework as required to load item definitions, then start the case resource. Use /caseadmin, configure each case and enable it. All six start disabled with empty reward pools, so no unwanted sample rewards enter your economy.
  2. Give yourself a case using your inventory's existing admin tools. Use it, review the rewards and click Open case.

Inventory item IDs: common_case, rare_case, epic_case, legendary_case, mythic_case, godly_case.

Case Manager

Select a case on the left. Set its label, tier color and enabled state. Add item searches the live inventory registry, including weapons when they are inventory items. Set item name, display label, quantity, weight and reward color in each row. Add money adds cash or bank rewards; bank requires a framework. Press Save to publish that case's changes. Cases have independent reward pools and quantities are fixed per reward.

Chance = reward weight / sum of weights. Weights are positive whole numbers from 1 to 1,000,000. For example, weights 70, 25 and 5 produce 70%, 25% and 5%. Quantity must be a positive whole number, up to Config.MaxAmount. Duplicate rows are permitted and each contributes its weight. Reward color is visual only and does not affect odds. Preview spin is cosmetic: it neither consumes nor grants anything and is not an odds test.

Reward pictures come from the inventory item definition: ox's client.image or the QB item image, with the standard {itemname}.png fallback. The opening reel, reward grid and item picker all use the same picture. Config.ItemImages can supply a custom inventory path. Missing images show a box icon. Case hero pictures are the bundled generic case icons. Changing a case's displayed title does not rename its inventory item.

The resource supports ESX, QBCore, Qbox and ox_inventory without a framework. Auto-detection prefers Qbox before QBCore and ox_inventory before framework inventories. Qbox normally uses ox_inventory. ESX default inventory and QBCore/qb-inventory use the framework bridge. Custom inventories need the editable functions in server/bridge.lua adapted to their own exports. Native ESX loadout weapons that are not inventory items are outside this version's item reward support.

Opening and delivery

The server checks ownership, enabled state, reward validity and opening cooldown, selects the reward, consumes the case and attempts delivery. The browser only animates the result. Closing the UI cannot reroll it. Admin edits affect subsequent openings; an opening uses one reward snapshot.

If the selected item cannot fit, the consumed case's reward is saved to the character and can be collected with /caserewards after making room. Pending rewards block new openings until resolved. The reward is fixed and is never rerolled on collection. Character identity is used for ESX/QB/Qbox; standalone uses the FiveM license identifier.

Case configuration and delivery receipts use server resource KVP storage. No SQL is needed for this resource's configuration. Back up your server KVP storage and keep the resource name unchanged. Completed receipt records are retained for audit.

Inventory/account changes and KVP are separate systems, so they cannot form a single atomic transaction. If the process stops during an inventory mutation, or the inventory throws an error, the receipt is held for administrator review rather than automatically replayed. In the server console only:

casereceipt                         # list unresolved receipts
casereceipt <receipt-id>            # inspect one receipt
casereceipt <receipt-id> retry      # review -> pending, then player uses /caserewards
casereceipt <receipt-id> delivered  # review -> resolved, no additional reward grant

Check the player's items/money and the receipt before resolving it. A receipt interrupted during case removal may require manually removing the case before marking it for retry. Never choose retry if the reward has already been granted. Custom reward adapters must return false only if nothing was granted; throw on ambiguous outcomes. They receive a stable receipt ID for idempotent external integrations.

Files and configuration

config.lua sets detection, admin permissions, cooldown, spin duration, item image paths and basic UI theme. Inventory IDs are fixed there so useable registrations and inventory definitions agree. All case content is saved in-game. server/rewards.lua handles grants; server/bridge.lua handles framework and inventory APIs. Config.CustomRewards is an optional server-side allowlist for custom reward handlers, which become selectable in the editor. It is empty by default. There is no client-supplied arbitrary event or command reward execution.

Notification text is in locales/en.lua; the editor's HTML labels are currently English. Like the reference UI, headings/body fonts load through Google Fonts and have local system fallbacks if unavailable.

For a browser-only visual preview, serve html/ using any local static server and open index.html?preview=case or index.html?preview=admin. Preview data is isolated from the game and never grants rewards. A normal game session starts hidden.

Validation

Lua sources and inventory snippets compiled successfully in a Lua runtime. Mocked FiveM/inventory tests cover permissions, validation, case consumption, weighted odds, full-inventory delivery, repeated claims, ambiguous inventory errors, console recovery and configuration reload. Browser tests cover reel winner alignment, item search/add, live odds, saves, independent case pools, unsaved-change protection and money rewards, with layouts reviewed at 1600×1000 and 1280×720.

A live FiveM framework/inventory integration test is still required after registering the items. This build does not change your inventory definitions, database or server.cfg automatically.

API references: ox item definitions and use callbacks, ox server inventory functions, FiveM NUI callbacks.

PreviousMoney Wash
Orynt Development© Orynt Development. Docs for every Orynt FiveM script.