The Gambling feature allows players to open Standard or Premium hidden boxes from the Inventory by paying a fixed amount of coins and receiving chance-based rewards.

The feature includes:

• Standard hidden box
• Premium hidden box
• Weighted reward pools
• Hidden-box opening animation
• Reward reveal
• Integration with the existing inventory, upgrade, and pet systems

The player flow is:

Open Inventory → Press Hidden Box → Pay Fixed Coin Price → Weighted Reward Selection → Box Opening Animation → Reward Reveal → Reward Delivery

The gambling result is selected before the hidden-box opening animation begins. The animation only presents the predetermined result and does not perform another random roll.

The Gambling UI is presented as hidden boxes in the Inventory.

The feature contains two box options:

The Standard hidden box has:

• Lower fixed coin cost
• A standard reward pool
• More common rewards

The Premium hidden box has:

• Higher fixed coin cost
• A separate reward pool
• Rarer and exclusive rewards

The exact fixed prices and reward pools are defined as part of the Gambling configuration.

Each box has its own reward pool. Rewards use a weight-based distribution to determine their probability.

Each reward contains:

• Reward
• Weight
• Reward payload

Higher-value or exclusive rewards can have lower weights, making them less likely to be selected.

Rarity is determined by reward weights rather than item price.

Item prizes use the shared weapon and consumable generators. The prize helper passes an item type and tier to the appropriate generator, and the reward reveal displays the generated item's name rather than a separately defined display name. Each item win creates a new item.

Premium slot 4 contains the Regen on Kill upgrade. Winning an upgrade applies its effects through the existing upgrade level-up logic rather than only storing its name.

When the player presses a hidden box in the Inventory, the gambling system first validates whether the transaction can proceed.

If the purchase is valid:

1. The box's fixed coin price is deducted.
2. The gambling system selects a reward using the configured weights.
3. The UI plays the hidden-box opening animation.
4. The selected reward is revealed.
5. The reward is delivered to the player.

The fixed box price is the only amount charged. Winning an upgrade does not charge an additional upgrade price.

If the purchase cannot proceed, no coins are deducted and the box opening animation does not start. A purchase the player cannot afford also leaves their upgrades unchanged.

The hidden-box opening animation is a visual presentation of the gambling result.

The UI should:

• Start the opening animation after a successful purchase and reward selection.
• Animate the hidden box opening.
• Reveal the selected reward when the animation finishes.

The UI must not generate or re-roll the result during the animation. The gambling logic determines the reward first, and the hidden-box UI displays that result.

After the hidden box opens, the player is shown a reward reveal indicating what they have won.

The reward reveal should clearly display:

• Reward name
• Reward icon or relevant visual
• Confirmation that the box opening has completed

The player can then return to the Inventory.

Rewards are delivered using the existing game systems.

Item rewards are added to the player's inventory and must follow the existing inventory capacity rules.

Each item win creates a new item through the shared weapon or consumable generator, keeping its name and properties consistent with the corresponding starting gear and shop items. Consumable rewards retain their effects, and weapon rewards retain their weapon stats.

Upgrade rewards use the existing UpgradeNode level-up logic used by the Shop's Upgrades tab. A successful box opening that awards an upgrade calls purchaseNextTier() so the upgrade affects the player.

Only the fixed box price is charged; the player does not pay an additional upgrade price.

Pet rewards use the existing pet management and activation path. The Gambling system does not introduce a separate pet-management system.

The feature supports item, upgrade, and pet rewards through the existing game architecture.

The Gambling UI is responsible for:

• Displaying Standard and Premium hidden boxes in the Inventory.
• Displaying fixed coin prices and reward information.
• Handling the hidden-box interaction.
• Starting the opening animation after a successful purchase and reward selection.
• Animating the hidden box opening.
• Revealing the predetermined reward.
• Refreshing relevant Inventory and Shop UI after the transaction.

The UI does not handle:

• Random number generation.
• Reward probability calculation.
• Reward selection.
• Independent coin deduction.
• Reward inventory rules.
• Upgrade level-up logic.
• Pet activation logic.

The feature separates the gambling logic from the hidden-box presentation.

The Gambling feature integrates with the existing:

• ShopComponent
• ShopDisplay
• Inventory UI
• InventoryComponent
• Item systems
• Item generators
• UpgradeNode upgrades and the Shop's Upgrades tab
• PetManager
• PetFactory
• Existing Shop and game events

createPlayer creates one WeaponGenerator and one ConsumableGenerator and passes both into installDefaultCatalog. The item listings and both spin catalogs use these generators, keeping item definitions consistent across starting gear, shop stock, and prizes.

The Gambling feature uses the existing Shop systems rather than changing the existing Items, Upgrades, Pets, or normal buy/sell behaviour.

The implementation follows these constraints:

• The Gambling feature has two hidden-box types.
• Each hidden-box type has a configured fixed coin price.
• Inventory capacity remains five slots by default.
• Only one pet can be active at a time.
• Reward rarity is controlled through weights.
• Existing Shop buy/sell rules are not changed.
• The hidden-box animation does not perform an additional random roll.
• Upgrade prizes apply through the existing upgrade system without an additional upgrade charge.

Member	Responsibility
Khang	Gambling Shop structure
Brian	Gambling logic and probability
Tris	Gambling UI and hidden-box opening animation

The responsibilities are separated so that the gambling logic determines the result while the UI presents that result to the player.

The feature should be tested through automated tests where applicable and manual gameplay testing.

Key scenarios include:

• Hidden boxes appear correctly in the Inventory.
• Standard and Premium hidden boxes are displayed.
• Correct fixed coin prices are displayed.
• A successful purchase deducts the fixed box price and selects a reward using the configured weights.
• The box opening animation starts after reward selection.
• The opening animation reveals the predetermined reward without another random roll.
• Reward reveal displays the correct result.
• Failed purchases do not start the opening animation.
• Insufficient coins do not deduct coins or change upgrades.
• Inventory restrictions are handled correctly.
• Item reward names match the generated items.
• Each item win creates a new item with the correct type, tier, and properties.
• Consumable rewards can be used, and weapon rewards function as weapons.
• Won upgrades apply their effects to the player.
• Upgrade wins deduct only the fixed box price, without an additional upgrade charge.
• Pet rewards follow the existing pet system.
• Inventory, Shop, and player state are updated after receiving a reward.

The following are not included:

• Additional hidden-box tiers beyond Standard and Premium.
• A pity system.
• Trading exclusive gambling rewards.
• Changes to pet combat AI.
• Changes to existing Shop buy/sell rules.

These items are explicitly outside the scope of the Gambling feature.