🎡 Wheel of fortune — every detail
The preset list
Hub → Events → Wheel of fortune. Each preset is its own wheel configuration with its own prize list and its own jackpot.
| Control | Function |
|---|---|
| Start | Opens the hand-out screen for this preset (pick players). |
| Edit | Opens the prize editor. |
| Ticket tier | Shown in gold after the name: which ticket lets players redeem this wheel themselves (see tickets). If the same tier is already assigned to a wheel further up, the row turns red and is marked “(DUPLICATE)” — only the upper wheel is then reachable. |
| Delete | Removes the preset server-side. default cannot be deleted — the button is hidden there. |
| + New preset | The server creates a fresh preset and returns the updated list. |
| Mouse wheel | Scrolls the list when you have many presets. |
The prize editor
| Field | Behaviour |
|---|---|
| Label | Display name in the win message (“1x Bandage”). Leave empty to show the class name. |
| ClassName | Item class of the prize (editable as text). Add new prizes with “Add prize” — that opens the search picker and the chosen item becomes a new row. |
| Quantity | The number of pieces. Stackable items (ammo, nails, banknotes …) arrive as one bundled stack, large amounts as several full stacks; everything else as individual items. Handed into the inventory first, and dropped at the player’s feet if it is full — a prize is never lost. |
| Weight | One weighted roll per spin: chance = weight ÷ sum of all weights. The sum does not have to be 100 (but it is handy: then weight equals percent). |
| Att | Only shown for weapons (checked live). Opens the loadout panel (below). If the row is switched to a non-weapon the attachments stay in the data — only the button disappears. |
| Jackpot | Toggle + item + message using %player%/%item%. When someone wins the jackpot item: global broadcast, jackpot sound, entry in jackpots.log. |
| Redeemable with ticket | Click-through selector no ticket → bronze → silver → gold → prestige. Sets which ticket lets players start this wheel themselves. Gold = assigned, grey = admin hand-out only, red = the tier already belongs to another wheel (named in the status line). |
| Save | Transfers the list in chunks both ways — even 100+ prizes save reliably. |
Handing out a wheel — the claim flow
The admin starts it
Preset list → Start → pick the target players and send.
The player claims it
The player gets a notification and has 60 seconds to press L (CTRL+L is the boss ranking — no conflict). The wheel never opens on top of another menu or the inventory.
Spin & prize
The wheel shows live 3D previews of the possible prizes in its cells (weapons including their loadout). The server decides the outcome — the animation follows it, the client cannot influence anything. The prize is handed out afterwards.
Tickets — players redeem a wheel themselves
Besides the admin hand-out, players can start a wheel themselves with a ticket item. There are four tiers (bronze, silver, gold, prestige); each tier belongs to exactly one wheel — assigned in that preset’s prize editor.
Take the ticket in hand
Trigger the “Check wheel” action.
Read the preview
The prize list of the assigned wheel opens — with a 3D preview, quantity and win chance in percent for every prize. The server calculates those percentages from the very same weights it later spins with.
Redeem or cancel
Cancel leaves the ticket untouched. Only redeem consumes one ticket (one off the stack) and starts the wheel.
| Rule | Behaviour |
|---|---|
| Cooldown | 15 seconds after a spin before the next ticket can be redeemed (“please wait X s”). While the wheel is spinning no new preview opens. |
| Ticket without a wheel | If no preset is assigned to that tier the server replies “This ticket is not linked to any wheel” — the ticket is kept. |
| Empty wheel | If the assigned preset has no prizes, nothing is consumed either. |
| Pending admin offer | If a wheel is still waiting to be claimed with L, the ticket is blocked (“A wheel is already waiting for you”) — never two wheels at once. |
| Server-authoritative | The server reads the ticket from the player’s hands itself; the client never sends an item class. |
How players get tickets
Tickets are ordinary stackable items — any system that hands out items can distribute them. No extra configuration is needed inside the mod:
- ZYADTrader: put tickets up as an offer (e.g. for ZYAD banknotes) — the grind loop.
- Mutant loot: add the ticket class as a loot row, control rarity with the weight.
- RaidBases loot and world loot (
types.xml). - Admin: spawn tickets directly.
Weapon loadouts (Att panel)
Slot rows are generated from the weapon config (attachment slots + magazines); each slot opens a search list containing only compatible items. The live 3D preview shows the weapon with the current selection. On hand-out the server fits the whole loadout; invalid entries are skipped, never crashed on.
Design tips
- One “cheap” wheel (food/medical) and one rare “event” wheel — that is exactly what presets are for.
- Make the weights add up to 100 and you can think in percent directly.
- Add the jackpot item as a normal prize row too — the jackpot flag only controls broadcast/sound/log, not the chance.
- Quantity means pieces: for stackable goods enter the real number you want (ammo “20”, not “1” — otherwise it is exactly one round).
- Think of the ticket tiers as progression: bronze = consumables, gold/prestige = chase items. You can tune the inflow far more precisely through the trader price and drop weights than through the prize list itself.