Lootboxes & Roulette
A lootbox is a product with random delivery. The player pays a fixed price and receives ONE random item from the pool. Each item's chance is determined by its weight.
How it works
- The store owner creates a product of type lootbox and defines the item pool
- Each item has a weight (integer, min 1, max 10 000)
- On purchase the system randomly selects one item
- Drop chance = item weight / sum of all weights × 100%
Example:
| Item | Weight | Chance |
|---|---|---|
| AK-47 (legendary) | 10 | 10% |
| SAR (epic) | 30 | 30% |
| Revolver (rare) | 60 | 60% |
Sum of weights = 100. AK-47 drops with a 10% probability.
Rarity
Each item in a lootbox has a rarity tier. It affects the color of the result badge on drop:
| Rarity | Color | Example |
|---|---|---|
common | Gray | Basic resources |
uncommon | Green | Tools |
rare | Blue | Weapons |
epic | Purple | Rare weapons |
legendary | Gold | Unique items |
Lootbox configuration
Show odds (showOdds)
- true (default) — the player sees percentages and an odds bar on the storefront
- false — odds are hidden; the player does not know exact probabilities. Only the list of possible items is shown
Animation (animation)
The current version supports only spin (spinning roulette):
- The player clicks "Open"
- The spin animation starts — a strip of items scrolls rapidly
- After ~3 seconds the animation slows and stops
- The result is shown: name, rarity, image
No-repeat streak (noRepeatStreak)
If set (e.g. noRepeatStreak: 3), the system guarantees the same item will not drop 3 times in a row.
How the player sees a lootbox
On the storefront (ProductCard)
- Case name + price
- "Open" button instead of "Buy"
- Optional: odds bar (OddsBar) with colored segments
In quick-view (ProductQuickView)
- Full description
- List of possible items with rarity
- Detailed odds table (if
showOdds: true)
In the roulette modal (RouletteModal)
- Full-screen spin animation
- Sound effect (planned)
- Result with a large icon and name
Lootbox cooldown
Cooldown is especially important for lootboxes:
- cooldownSeconds — if > 0, the player cannot open another lootbox until N seconds have elapsed
- This protects against accidental repeat purchases (shaky hand, double-click)
- Recommended value: 5–10 seconds for regular cases, 30+ for rare ones
Limits and images
- Minimum 2 items, maximum 50
- Item images work the same way as in kits
perPlayerLimit— caps the total number of opens per player