Loot Boxes & Keys

Complete guide and documentation

Loot Boxes & Keys

Loot boxes are configurable reward containers. Keys are normal consumable items (ItemVariants). Player-owned boxes live in game_user_loot_boxes; keys and rewards live in game_user_inventory.

Panel Loot Boxes

  • Menu: Loot Boxes (sidebar) — create/edit boxes, loot table, key requirement, shop prices
  • Loot table: add Item Variants with probability (non-guaranteed rows must sum to 100%)
  • Requires key: checkbox + required key rarity (common → legendary)
  • Prices: soft_coin_cost / hard_coin_cost for API buy endpoint
  • Simulate: test roll on show page (admin only)

Panel Keys

  • Keys are NOT a separate entity — create them under Items Configuration
  • Item Type: Key (consumable, stackable)
  • Item Definition: Loot Box Key — json_schema must include properties.key_rarity (enum)
  • Master Item + Item Variant (level 0) per key (Common, Rare, Epic, Legendary, Unique)
  • Panel: edit variant → section Item Properties → Key rarity dropdown (maps to item_variants.content.key_rarity)
  • NOT unlock_features — that JSON is for level-up perks, not keys
  • If Item Properties is empty: fix Item Definition schema (run migration or LootBoxesAndKeysSeeder)
  • Item Variant Prices: sell keys via shop / buy-item API
  • Seeder: php artisan db:seed --class=LootBoxesAndKeysSeeder

Player Inventory

  • Unopened boxes → game_user_loot_boxes (quantity stack)
  • Keys & rewards → game_user_inventory (item_variant_id + quantity)
  • GET /api/v1/user/inventory returns inventory[] + loot_boxes[] + consumables[]
  • Keys expose key_rarity in inventory[].key_rarity, inventory[].content.key_rarity, and consumables[id].key_rarity

Api Endpoints

  • GET /api/v1/loot-boxes — catalog
  • GET /api/v1/user/loot-boxes — player boxes only
  • GET /api/v1/user/keys — player keys only (key_rarity, quantity)
  • GET /api/v1/user/loot-box-inventory — boxes + keys in one response (Unity screen)
  • POST /api/v1/user/loot-boxes/buy — purchase box with soft/hard coins
  • POST /api/v1/user/loot-boxes/open — open (optional key_item_variant_id)
  • POST /api/v1/user/loot-boxes/add — grant box (events/admin)
  • POST /api/v1/user/inventory/buy-item — purchase keys
  • Full reference: https://gamepanel.idcgames.com/documentation/developer/loot-boxes

Unity Flow

  • 1. GET /user/loot-box-inventory — loot_boxes[] + keys[] (or separate /user/loot-boxes + /user/keys)
  • 2. POST /user/loot-boxes/buy or /user/inventory/buy-item for keys
  • 3. Match key.key_rarity to box.required_key_rarity; POST /user/loot-boxes/open with key_item_variant_id
  • 4. Map rewards: master_item_id → weapon, item_variant_id → skin

Test Script

  • Run: php Example_lootbox_flow.php (after migrate/seed)
  • Also listed under Developer → Test Examples
Back to Documentation
Overview