> For the complete documentation index, see [llms.txt](https://docs.hyper-code.eu/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hyper-code.eu/documentation/case-system/config.md).

# Case System – Configuration

All options in shared/config.lua of Case System: framework, notifications, tiers, drop rates, cases, rewards, announcements, Discord log and vehicles.

All settings are in `shared/config.lua`. This file is not escrowed.

## General

| Option               | Default                             | Description                                                                                                                                      |
| -------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Config.Framework`   | `"es_extended"`                     | Resource name of your framework (`es_extended`, `qb-core` or a renamed core). ESX is detected via `getSharedObject`, QBCore via `GetCoreObject`. |
| `Config.ImageSource` | `"nui://inventory/html/img/items/"` | Folder with your item images, as `nui://<resource>/<path>/`. The UI loads `<name>.png` from here.                                                |

{% hint style="info" %}
Point `Config.ImageSource` to the image folder of the inventory you actually use, for example `nui://ox_inventory/web/images/` for ox\_inventory. A reward can also use its own `image` URL (see [Cases](#cases)).
{% endhint %}

## Notifications

```lua
Config.ShowNotification = function(source, message, title, type)
    if IsDuplicityVersion() then -- server side
        TriggerClientEvent("hc_notify:notify", source, message, title, type, 3000)
    else -- client side
        exports["hc_notify"]:notify(message, title, type, 3000)
    end
end

Config.ShowAnnouncement = function(source, message)
    if IsDuplicityVersion() then -- server side
        TriggerClientEvent("hc_notify:announce", source, message, "CASE WIN", 5000)
    end
end
```

Replace the calls with your own notification resource if you do not use [Premium Notify](https://shop.hyper-code.eu/package/6496308).

{% hint style="info" %}
`Config.ShowAnnouncement` is called with the player who opened the case as `source`, so by default only that player sees the announcement. Replace `source` with `-1` inside the function to send it to everyone.
{% endhint %}

## Tiers

`Config.Tiers` defines the five rarity tiers. Every reward in a case points to one tier.

| Tier  | `name`    | `rate` | `color`            |
| ----- | --------- | ------ | ------------------ |
| `[1]` | Common    | `50`   | `#ababab` (grey)   |
| `[2]` | Uncommon  | `40`   | `#33ff00` (green)  |
| `[3]` | Rare      | `20`   | `#0381ff` (blue)   |
| `[4]` | Epic      | `10`   | `#ff9203` (orange) |
| `[5]` | Legendary | `1.5`  | `#9603ff` (purple) |

### How the drop chance works

`rate` is a weight **per reward**, not per tier. The chance of one reward is its tier rate divided by the sum of the rates of all rewards in that case.

Example `case` (default): one tier 5 vehicle (1.5), one tier 1 item (50), one tier 2 item (40), one tier 3 item (20) and two tier 4 weapons (10 + 10) = 131.5 in total. The vehicle drops with 1.5 / 131.5 ≈ 1.1 %, the tier 1 item with 50 / 131.5 ≈ 38 %.

{% hint style="info" %}
Adding more rewards of the same tier makes that tier more likely overall. Rates can have one or two decimals (for example `1.5`).
{% endhint %}

## Announcement

```lua
Config.Announcement = {
    TierToAnnounce = 1, -- announce wins of this tier and higher
    UseColor = true     -- show the reward name in the tier colour
}
```

| Option           | Default | Description                                                                                                                                |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `TierToAnnounce` | `1`     | Wins with this tier or higher trigger `Config.ShowAnnouncement`. With `1` every win is announced; set `5` to announce only Legendary wins. |
| `UseColor`       | `true`  | Wraps the reward name in the tier colour                                                                                                   |

## Cases

Every case is keyed by its **item name**:

```lua
Config.Cases = {
    ["case2"] = {                    -- item name of the case
        Name = "Case #2",            -- label
        ItemNeededToOpen = "casekey", -- false or an item name
        Items = {
            {type = "weapon", name = "weapon_pistol", amount = 1, tier = 1},
            {type = "item", name = "cola", amount = 5, tier = 2},
            {type = "money", name = "bank", amount = 10000, tier = 3},
            {type = "vehicle", name = "blista", amount = 1, tier = 5,
             image = "https://docs.fivem.net/vehicles/blista.webp"},
        }
    },
}
```

| Field              | Description                                                                    |
| ------------------ | ------------------------------------------------------------------------------ |
| `Name`             | Label of the case. The UI title is taken from the item label of the case item. |
| `ItemNeededToOpen` | `false`, or an item that is required and removed (1×) when the case is opened  |
| `Items`            | List of possible rewards                                                       |

Reward fields:

| Field    | Description                                                                                                                         |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `type`   | `"item"`, `"weapon"`, `"money"` or `"vehicle"`                                                                                      |
| `name`   | Item name, weapon name (for example `weapon_pistol`), account name (`money` = cash, `bank`, `black_money`, …) or vehicle spawn name |
| `amount` | Amount. For weapons on ESX this is the ammo count.                                                                                  |
| `tier`   | Tier number from `Config.Tiers`                                                                                                     |
| `image`  | Optional. Own image URL; otherwise `Config.ImageSource` + `<name>.png` is used.                                                     |

When a player uses the case item, the case and (if set) the key item are removed and the reward is given after the animation.

## Discord log

```lua
Config.DiscordWebhook = "https://discord.com/api/webhooks/"
```

Every opening is posted to this webhook. Put your full webhook URL here, or set `""` to turn the log off.

## Translations and colours

* `Config.Translation` contains every text in the UI, the notifications, the announcement and the Discord message. Placeholders: `WinningText` uses `%name` and `%amount`, `GlobalAnnouncement` uses `%name`, `%case` and `%item`, the others use `%s`.
* `Config.Style` sets the two accent colours of the UI (`LightColor`, `DarkColor`).

## Vehicle rewards

When a vehicle is won, the client creates the vehicle properties with a new unique plate and calls `Config.VehicleBuyTrigger`. By default it sends them to the server event `hc_cases:setVehicleOwner`, which is also defined in `shared/config.lua`:

```lua
Config.VehicleBuyTrigger = function(veh, vehProperties)
    TriggerServerEvent("hc_cases:setVehicleOwner", vehProperties)
end

if IsDuplicityVersion() then
    RegisterNetEvent("hc_cases:setVehicleOwner")
    AddEventHandler("hc_cases:setVehicleOwner", function(vehicleProps)
        local xPlayer = ESX.GetPlayerFromId(source)
        MySQL.insert(
            'INSERT INTO owned_vehicles (owner, plate, vehicle, stored, job) VALUES (?, ?, ?, 1, "civ")',
            {xPlayer.identifier, vehicleProps.plate, json.encode(vehicleProps)})
    end)
end
```

{% hint style="warning" %}
This default handler is written for **ESX** and the `owned_vehicles` table. On **QBCore** replace it with the event of your vehicle shop or your own insert into `player_vehicles`. The config file contains commented QBCore examples (`vehiclekeys:client:SetOwner`, `qb-vehicletuning:server:SaveVehicleProps`).
{% endhint %}

The plate check uses `owned_vehicles` on ESX and `player_vehicles` on QBCore.
