# Hunt System

## Overview
The hunt system is the core animal-catching mechanic in Advenexus. Players spend coins and stamina to hunt wild animals of varying rarities. Hunts can also drop gems and lootboxes. All caught animals go into the player's zoo.

---

## Commands

| Command | Description |
|---|---|
| `.hunt` | Catch a wild animal (costs coins + 1 stamina) |
| `.zoo` | View all animals you own, grouped by rarity |
| `.dex <animal>` | View detailed stats for an owned animal |
| `.sell <animal>` | Sell an animal for coins |
| `.sell <count> <animal>` | Sell multiple animals by name |
| `.sell <rarity>` | Bulk sell all animals of a rarity tier (e.g. `.sell common`) |
| `.sacrifice <animal>` | Sacrifice an animal for gems |
| `.sacrifice <count> <animal>` | Sacrifice multiple animals by name |
| `.sacrifice <rarity>` | Bulk sacrifice all animals of a rarity tier |
| `.rename <current> \| <new>` | Rename an animal (max 20 characters, alphanumeric + space/dash/underscore) |
| `.tier` | Show all animals grouped by rarity tier |
| `.tier <rarity>` | Show animals for a specific rarity tier |
| `.evolve <animal>` | Evolve an animal to its next stage (requires duplicate + stone for mythic+) |

---

## Hunt Cost

| Player Level | Hunt Cost |
|---|---|
| 1–5 | Free (0 coins) |
| 6–15 | 1 coin |
| 16+ | 2 coins |

- Each hunt also costs **1 stamina** (hunt stamina).

---

## Stamina

- Max stamina: **100 hunt** / **100 battle** (separate pools)
- Refills daily at **11 PM UTC** (full reset to 100)
- When stamina hits 0, you cannot hunt until the next refill

---

## Hunt Cooldown

- **15 seconds** between hunts

---

## Rarity Tiers

| Rarity | Drop Rate | XP | Sell Value (🪙) | Sacrifice Value (💎) | Zoo Points | Level Cap |
|---|---|---|---|---|---|---|
| Common | ~57% | 2 | 1 | 5 | 2 | 5 |
| Uncommon | ~25% | 5 | 3 | 10 | 5 | 5 |
| Rare | ~10% | 20 | 10 | 20 | 10 | 5 |
| Epic | ~5% | 400 | 250 | 40 | 250 | 5 |
| Mythic | ~2% | 1,000 | 5,000 | 150 | 2,000 | 10 |
| Legendary | ~0.7% | 2,000 | 35,000 | 500 | 5,000 | 15 |
| Fabled | ~0.01% | 5,000 | 200,000 | 1,500 | 10,000 | 20 |
| patron | 0% (special) | 10,000 | 0 | 0 | 12,000 | 30 |
| Gods | 0% (shop only) | 15,000 | 2,500,000 | 2,500 | 15,000 | 30 |
| Boundless | ~0.006% | 15,000 | 5,000,000 | 5,000 | 30,000 | ∞ |

> **Note:** Gods-tier animals are **not huntable** — they can only be obtained via the shop. patron-tier animals are exclusive to patron supporters.

---

## Drops During Hunts

### Gem Drops
- **5% chance** per hunt to find a random gem
- Gems are added to inventory

### Lootbox Drops
- **10% chance** per hunt to find a lootbox
- Max **3 lootboxes per day** (UTC midnight reset)

---

## Gems (Hunt Modifiers)

Gems are equipped and consumed per-charge during hunts. Three categories:

| Gem | Effect | Charges (by tier) |
|---|---|---|
| Hunting Gem (🟢🟡🔴) | **x2 animals** per hunt | 10 / 25 / 50 |
| Lucky Gem (💚💛❤️) | **+2% fabled/boundless** rarity boost | 10 / 15 / 20 |
| Gemstone (💎) | **+3 animals** per hunt | 20 |

- Hunting Gem + Gemstone stack: base 1 → +3 (stone) = 4 → x2 (hunt gem) = **8 animals per hunt**
- Lucky boost stacks with Hunt Frenzy event bonus

---

## Hunt Frenzy

- A global event that adds **+2% rarity boost** to all hunts
- Stacks with Lucky Gem boost
- Set via `global.huntFrenzyActive`

---

## Rare Drop Broadcasts

When a player catches **Legendary, Fabled, Gods, or Boundless** animals:
- A server-wide broadcast is sent
- Confetti animation triggers on the client

| Rarity | Icon | Confetti Intensity |
|---|---|---|
| Legendary | ⭐ | Low |
| Fabled | 🔥 | Medium |
| Gods | 👑 | Medium |
| Boundless | ✨ | Medium |

---

## Evolution System

Animals Mythic+ can evolve through stages. Evolution requires:
1. **2 copies** of the same animal at the same evolution stage
2. An **evolution stone** matching the target rarity (mythic, legendary, fabled, gods)

### Evolution Stones Required

| Target Rarity | Stone Needed |
|---|---|
| Mythic | 🧿 Mythic Stone |
| Legendary | ⭐ Legendary Stone |
| Fabled | 🔥 Fabled Stone |
| Gods | 👑 Gods Stone |

> Evolution stones drop from **Dungeon Raids**.

### Max Evolution Stages by Rarity

| Rarity | Max Stages | Suffix Labels |
|---|---|---|
| Mythic | 1 (base → +) | Mythic, Mythic+ |
| Legendary | 2 (base → + → ++) | Legendary, Legendary+, Legendary++ |
| Fabled | 2 (base → + → ++) | Fabled, Fabled+, Fabled++ |
| Gods | 1 (base → +) | Gods, Gods+ |
| Boundless | 0 | No evolution |

### Evolution Stat Multiplier

| Stage | Global Multiplier |
|---|---|
| 0 (base) | 1.0x |
| 1 (+) | 1.5x |
| 2+ (++) | 2.0x |

---

## Animal Roles (Mythic+)

Mythic and higher tier animals have combat roles that grant bonus stats:

| Role | Boosted Stat | Bonus by Stage (0/1/2) |
|---|---|---|
| Tank | HP | +30% / +40% / +50% |
| Mage | Mana | +50% / +60% / +70% |
| Berserker | ATK | +40% / +50% / +60% |
| Armored | DEF | +50% / +60% / +70% |
| Speed | SPD | +30% / +40% / +50% |

---

## Level Scaling

- All stats scale by **+10% per level** (level 1 = 1.0x, level 2 = 1.1x, etc.)
- XP required per level: `floor(100 × level^1.8)`

---

## Autohunt (Huntbot)

An automated hunting system that hunts animals over time while you're away.

### Commands

| Command | Description |
|---|---|
| `.autohunt` | Start a huntbot session |
| `.huntresults` | Claim animals when session ends |
| `.huntbot` | View huntbot status and build |
| `.huntbot upgrade <trait>` | Upgrade a trait with gems |

### How It Works
1. Pay coins to start a session (cost = animals × 10 🪙)
2. Huntbot rolls animals in the background
3. Claim results with `.huntresults` when the session timer ends

### Traits (Max Level: 50 each)

| Trait | Effect | Upgrade Cost |
|---|---|---|
| Efficiency | Faster hunt speed (10s → 1s per animal) | 10 💎 × 1.5^(level-1) |
| Duration | Longer sessions (more animals) | 10 💎 × 1.5^(level-1) |
| Radar | Slightly better rare chance | 10 💎 × 1.5^(level-1) |

- Base animals per session: `5 + (efficiency + duration + radar) × 2`
- Max session duration: **8 hours** (hard cap)
- Radar boost is tiny: `level × 0.001%` per level

### Session Cost
- `animals_per_session × 10 coins`

---

## Sell / Sacrifice Rules

- Animals **in your team** (team_slot > 0) or **equipped** cannot be sold or sacrificed
- Animals listed on the marketplace cannot be used for evolution
- Bulk operations work up to **500** at a time
- Selling gives **coins**; sacrificing gives **gems**

---

## Player XP & Level-Up Rewards

Catching animals gives XP. Leveling up gives coins, lootboxes, and crates:

| Level Range | Coin Reward | Lootboxes | Weapon Crates |
|---|---|---|---|
| 1–5 | 200 × 1.5^(level-1) | 2 | 0 |
| 6–10 | 200 × 1.5^(level-1) | 2 | 1 |
| 11–15 | 5,000 + (level-10) × 2,000 | 2 | 3 |
| 16–20 | 5,000 + (level-10) × 2,000 | 3 | 4 |
| 21–25 | 5,000 + (level-10) × 2,000 | 4 | 5 |
| 30–35 | 35,000 + (level-25) × 500 | 5 | 6 |
| 40–45 | 35,000 + (level-25) × 500 | 6 | 7 |
| 46+ | 35,000 + (level-25) × 500 | 7 | 8 |

---

## Inventory Overflow

- Each player has a **max inventory** (default 100 slots)
- Weapons count toward inventory capacity
- If inventory is full, overflow items go to **temporary storage** (expires in **1 hour**)

---

## Edge Cases

- Hunting with 0 stamina is blocked with a clear message
- Hunting with insufficient coins is blocked
- Selling/sacrificing animals in your team slot is prevented
- Rename has character restrictions: alphanumeric, spaces, dashes, underscores only (max 20 chars)
- Gods-tier animals cannot be hunted — shop purchase only
- Boundless animals have **no level cap** (Infinity)