# Animal System

## Overview
The animal system is the core collection mechanic in Advenexus. Players hunt wild animals of varying rarities, each with unique stats, roles, and evolution paths. Animals are used for battle, zoo progression, and can be evolved into stronger forms.

---

## Rarity Tiers

Animals are classified into 12 rarity tiers, each with distinct drop rates, base stats, and rewards:

| Rarity | Drop Rate | Zoo Points | XP | Sell Value (🪙) | Sacrifice Value (💎) | Shop Price (🪙) | Level Cap | Max Evolution Stages |
|---|---|---|---|---|---|---|---|---|
| Common | 100% | 2 | 2 | 1 | 5 | - | 10 | 0 |
| Uncommon | 25% | 5 | 5 | 3 | 10 | - | 10 | 0 |
| Rare | 10% | 10 | 20 | 10 | 20 | - | 10 | 0 |
| Epic | 5% | 250 | 400 | 250 | 40.4 | - | 10 | 0 |
| Mythic | 0.5% | 2,000 | 1,000 | 7,000 | 150 | 10,000 | 20 | 1 |
| Legendary | 0.1% | 5,000 | 2,000 | 40,000 | 500 | 70,000 | 25 | 2 |
| Fabled | 0.01% | 10,000 | 5,000 | 200,000 | 1,500 | - | 30 | 2 |
| Patron | 0% | 12,000 | 10,000 | 0 | 0 | - | 40 | 0 |
| Gods | 0% | 15,000 | 15,000 | 1,500,000 | 4,000 | 5,000,000 | 40 | 1 |
| Ascendants | 0% | 40,000 | 25,000 | 3,000,000 | 8,000 | - | 50 | 1 |
| Boundless | 0.001% | 30,000 | 15,000 | 3,000,000 | 10,000 | - | ∞ | 0 |
| Infinity | 0% | 50,000 | 30,000 | 10,000,000 | 15,000 | - | ∞ | 0 |

> **Note:** Patron, Gods, Ascendants, and Infinity tiers are not huntable and can only be obtained through special means (shop purchase, patron support, etc.)

---

## Base Stats by Rarity

All animals of the same rarity tier share base stats, with individual variations for Common-Epic tiers:

### Tier Base Stats (Mythic+)
| Rarity | HP | ATK | DEF | SPD | Mana |
|---|---|---|---|---|---|
| Common | 120 | 10 | 5 | 12 | 50 |
| Uncommon | 220 | 20 | 10 | 16 | 80 |
| Rare | 350 | 40 | 30 | 25 | 150 |
| Epic | 500 | 60 | 60 | 50 | 250 |
| Mythic | 1,400 | 120 | 200 | 100 | 400 |
| Legendary | 3,000 | 250 | 500 | 200 | 600 |
| Fabled | 5,500 | 350 | 800 | 400 | 800 |
| Patron | 11,000 | 450 | 1,200 | 600 | 1,400 |
| Gods | 11,000 | 500 | 1,400 | 600 | 1,500 |
| Ascendants | 25,000 | 800 | 2,500 | 800 | 2,000 |
| Boundless | 36,000 | 1,200 | 3,000 | 1,000 | 2,000 |
| Infinity | 55,000 | 3,000 | 5,000 | 1,500 | 3,000 |

### Individual Base Stats (Common-Epic)
Common-Epic animals have individual stat variations from the tier base stats. These animals do not have roles.

#### Common Animals (Tier Base: HP 120, ATK 10, DEF 5, SPD 12, Mana 50)
| Animal | HP | ATK | DEF | SPD | Mana | Notes |
|---|---|---|---|---|---|---|
| Cat | 90 | 10 | 5 | 14 | 50 | Faster than average |
| Dog | 110 | 12 | 7 | 11 | 50 | Tankier than average |
| Rabbit | 75 | 7 | 4 | 18 | 50 | Very fast, low stats |
| Hamster | 60 | 6 | 3 | 16 | 50 | Fast but fragile |
| Chicken | 70 | 8 | 4 | 10 | 50 | Below average stats |
| Pig | 120 | 9 | 8 | 7 | 50 | High HP/DEF, slow |
| Sheep | 100 | 8 | 6 | 9 | 50 | Balanced but slow |
| Duck | 80 | 9 | 5 | 12 | 50 | Near tier average |

#### Uncommon Animals (Tier Base: HP 220, ATK 20, DEF 10, SPD 16, Mana 80)
| Animal | HP | ATK | DEF | SPD | Mana | Notes |
|---|---|---|---|---|---|---|
| Fox | 130 | 22 | 10 | 20 | 80 | Fast, good ATK |
| Deer | 150 | 18 | 14 | 17 | 80 | High HP/DEF, balanced |
| Penguin | 140 | 16 | 15 | 11 | 80 | High DEF, slow |
| Koala | 160 | 15 | 18 | 9 | 80 | Very tanky, slow |
| Monkey | 125 | 25 | 8 | 22 | 80 | High ATK/SPD, low DEF |
| Parrot | 115 | 20 | 9 | 19 | 80 | Fast, good ATK |

#### Rare Animals (Tier Base: HP 350, ATK 40, DEF 30, SPD 25, Mana 150)
| Animal | HP | ATK | DEF | SPD | Mana | Notes |
|---|---|---|---|---|---|---|
| Lion | 230 | 50 | 22 | 24 | 150 | Balanced stats |
| Tiger | 210 | 55 | 18 | 30 | 150 | High ATK/SPD, lower HP/DEF |
| Bear | 280 | 48 | 30 | 15 | 150 | High HP/DEF, slow |
| Panda | 260 | 40 | 35 | 12 | 150 | Very tanky, slow |
| Gorilla | 300 | 52 | 28 | 14 | 150 | Highest HP, balanced |

#### Epic Animals (Tier Base: HP 500, ATK 60, DEF 60, SPD 50, Mana 250)
| Animal | HP | ATK | DEF | SPD | Mana | Notes |
|---|---|---|---|---|---|---|
| Elephant | 450 | 95 | 60 | 16 | 250 | Tanky, very slow |
| Rhinoceros | 500 | 95 | 75 | 12 | 250 | High DEF, very slow |
| Shark | 400 | 75 | 40 | 35 | 250 | High ATK, fast |
| Eagle | 350 | 85 | 35 | 50 | 250 | Very fast, good ATK |
| Crocodile | 480 | 80 | 65 | 18 | 250 | Balanced tank |

### Individual Base Stats (Mythic+ with Roles)
Mythic and higher tier animals use tier base stats with role bonuses. Only base forms (first in evolution chain) are listed.

#### Mythic Animals (Tier Base: HP 1,400, ATK 120, DEF 200, SPD 100, Mana 400)
| Animal | Role | HP | ATK | DEF | SPD | Mana | Role Bonus (Stage 0) |
|---|---|---|---|---|---|---|---|
| Minotaur | Tank | 1,820 | 120 | 200 | 100 | 400 | HP +30% |
| Werewolf | Berserker | 1,400 | 168 | 200 | 100 | 400 | ATK +40% |
| Centaur | Speed | 1,400 | 120 | 200 | 130 | 400 | SPD +30% |
| Ghost | Speed | 1,400 | 120 | 200 | 130 | 400 | SPD +30% |
| Knight | Armored | 1,400 | 120 | 300 | 100 | 400 | DEF +50% |

#### Legendary Animals (Tier Base: HP 3,000, ATK 250, DEF 500, SPD 200, Mana 600)
| Animal | Role | HP | ATK | DEF | SPD | Mana | Role Bonus (Stage 0) |
|---|---|---|---|---|---|---|---|
| Wolf | Speed | 3,000 | 250 | 500 | 260 | 600 | SPD +30% |
| Lich | Mage | 3,000 | 250 | 500 | 200 | 900 | Mana +50% |
| Grim | Berserker | 3,000 | 350 | 500 | 200 | 600 | ATK +40% |
| Revenant | Tank | 3,900 | 250 | 500 | 200 | 600 | HP +30% |
| Golem | Armored | 3,000 | 250 | 750 | 200 | 600 | DEF +50% |

#### Fabled Animals (Tier Base: HP 5,500, ATK 350, DEF 800, SPD 400, Mana 800)
| Animal | Role | HP | ATK | DEF | SPD | Mana | Role Bonus (Stage 0) |
|---|---|---|---|---|---|---|---|
| Leviathan | Tank | 7,150 | 350 | 800 | 400 | 800 | HP +30% |
| Medusa | Mage | 5,500 | 350 | 800 | 400 | 1,200 | Mana +50% |
| Ghidorah | Berserker | 5,500 | 490 | 800 | 400 | 800 | ATK +40% |
| Oracle | Mage | 5,500 | 350 | 800 | 400 | 1,200 | Mana +50% |
| Godzilla | Berserker | 5,500 | 490 | 800 | 400 | 800 | ATK +40% |

#### Gods Animals (Tier Base: HP 11,000, ATK 500, DEF 1,400, SPD 600, Mana 1,500)
| Animal | Role | HP | ATK | DEF | SPD | Mana | Role Bonus (Stage 0) |
|---|---|---|---|---|---|---|---|
| Anubis | Armored | 11,000 | 500 | 2,100 | 600 | 1,500 | DEF +50% |
| Nyx | Speed | 11,000 | 500 | 1,400 | 780 | 1,500 | SPD +30% |
| Zeus | Mage | 11,000 | 500 | 1,400 | 600 | 2,250 | Mana +50% |
| Hades | Berserker | 11,000 | 700 | 1,400 | 600 | 1,500 | ATK +40% |

#### Ascendants Animals (Tier Base: HP 25,000, ATK 800, DEF 2,500, SPD 800, Mana 2,000)
| Animal | Role | HP | ATK | DEF | SPD | Mana | Role Bonus (Stage 0) |
|---|---|---|---|---|---|---|---|
| Manhattan | Mage | 25,000 | 800 | 2,500 | 800 | 3,000 | Mana +50% |
| Lucifer | Berserker | 25,000 | 1,120 | 2,500 | 800 | 2,000 | ATK +40% |
| Galactus | Tank | 32,500 | 800 | 2,500 | 800 | 2,000 | HP +30% |

#### Boundless Animals (Tier Base: HP 36,000, ATK 1,200, DEF 3,000, SPD 1,000, Mana 2,000)
| Animal | Role | HP | ATK | DEF | SPD | Mana | Role Bonus (Stage 0) |
|---|---|---|---|---|---|---|---|
| Absolute Being | Tank | 46,800 | 1,200 | 3,000 | 1,000 | 2,000 | HP +30% |
| The Beyonder | Mage | 36,000 | 1,200 | 3,000 | 1,000 | 3,000 | Mana +50% |

#### Infinity Animals (Tier Base: HP 55,000, ATK 3,000, DEF 5,000, SPD 1,500, Mana 3,000)
| Animal | Role | HP | ATK | DEF | SPD | Mana | Role Bonus (Stage 0) |
|---|---|---|---|---|---|---|---|
| One Above All | Tank | 71,500 | 3,000 | 5,000 | 1,500 | 3,000 | HP +30% |
| The Presence | Mage | 55,000 | 3,000 | 5,000 | 1,500 | 4,500 | Mana +50% |

---

## Animal Roles (Mythic+)

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

| Role | Boosted Stat | Stage 0 Bonus | Stage 1 Bonus | Stage 2 Bonus |
|---|---|---|---|---|
| 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% |

### Role Examples by Rarity
- **Mythic**: Minotaur (Tank), Werewolf (Berserker), Centaur (Speed), Ghost (Speed), Knight (Armored)
- **Legendary**: Wolf (Speed), Lich (Mage), Grim (Berserker), Revenant (Tank), Golem (Armored)
- **Fabled**: Leviathan (Tank), Medusa (Mage), Ghidorah (Berserker), Oracle (Mage), Godzilla (Berserker)
- **Gods**: Anubis (Armored), Nyx (Speed), Zeus (Mage), Hades (Berserker)
- **Ascendants**: Manhattan (Mage), Lucifer (Berserker), Galactus (Tank)
- **Boundless**: Absolute Being (Tank), The Beyonder (Mage)
- **Infinity**: One Above All (Tank), The Presence (Mage)

---

## Evolution System

### Evolution Chains
Animals can evolve through stages, becoming stronger with each evolution. Evolution chains vary by rarity:

#### Mythic Evolution Chains (1 stage)
- Minotaur → War Minotaur
- Werewolf → Primordial Werewolf
- Centaur → War Centaur
- Ghost → Dark Angel
- Knight → Wraith Knight

#### Legendary Evolution Chains (2 stages)
- Wolf → Spirit Wolf → Celestial Wolf
- Lich → Elder Lich → Lich King
- Grim → Soul Reaper → Grim Reaper
- Revenant → Frost Revenant → Frost Revenant King
- Golem → Ancient Golem → War Golem

#### Fabled Evolution Chains (2 stages)
- Leviathan → Abyssal Leviathan → Primordial Leviathan
- Medusa → Cursed Medusa → Queen Medusa
- Ghidorah → Storm Ghidorah → King Ghidorah
- Oracle → Curse Oracle → Seraph Oracle
- Godzilla → GVK Godzilla → Burning Godzilla

#### Gods Evolution Chains (1 stage)
- Anubis → Lord Anubis
- Nyx → Goddess of Darkness
- Zeus → God of Thunder
- Hades → King of Underworld

#### Ascendants Evolution Chains (1 stage)
- Manhattan → Dr Manhattan
- Lucifer → Lucifer Morningstar
- Galactus → Galactus The Devourer

### Evolution Requirements
To evolve an animal:
1. **2 copies** of the same animal at the same evolution stage
2. An **evolution stone** matching the target rarity:
   - Mythic Stone for Mythic animals
   - Legendary Stone for Legendary animals
   - Fabled Stone for Fabled animals
   - Gods Stone for Gods animals

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

The global multiplier applies to all stats after role bonuses and level scaling.

---

## Level Scaling

All animal stats scale with level:
- **Scaling formula**: +10% per level
- **Level 1**: 1.0x multiplier
- **Level 2**: 1.1x multiplier
- **Level 10**: 1.9x multiplier
- **XP required per level**: `floor(100 × level^2.0)`

### Level Caps by Rarity
| Rarity | Level Cap |
|---|---|
| Common | 10 |
| Uncommon | 10 |
| Rare | 10 |
| Epic | 10 |
| Mythic | 20 |
| Legendary | 25 |
| Fabled | 30 |
| Patron | 40 |
| Gods | 40 |
| Ascendants | 50 |
| Boundless | ∞ (Infinity) |
| Infinity | ∞ (Infinity) |

---

## Stat Calculation Formula

Final animal stats are calculated as follows:

```
1. Start with base stats (tier base or individual base stats)
2. Apply role bonus at current evolution stage (if applicable)
3. Apply level scaling: 1 + (0.10 × (level - 1))
4. Apply evolution global multiplier:
   - Stage 0: 1.0x
   - Stage 1: 1.5x
   - Stage 2+: 2.0x
5. Final stat = floor(base_stat × role_bonus × level_scale × evolution_multiplier)
```

### Example Calculation
**Level 15 Celestial Wolf (Legendary, Speed role, Stage 2)**:
1. Base stats: HP 2,500, ATK 600, DEF 300, SPD 300, Mana 500
2. Role bonus (Speed, Stage 2): SPD × 1.50 = 300 × 1.5 = 450
3. Level scaling: 1 + (0.10 × 14) = 2.4x
4. Evolution multiplier (Stage 2): 2.0x
5. Final SPD: floor(450 × 2.4 × 2.0) = floor(2,160) = 2,160

---

## Complete Animal List

### Common Animals
- Cat, Dog, Rabbit, Hamster, Chicken, Pig, Sheep, Duck

### Uncommon Animals
- Fox, Deer, Penguin, Koala, Monkey, Parrot

### Rare Animals
- Lion, Tiger, Bear, Panda, Gorilla

### Epic Animals
- Elephant, Rhinoceros, Shark, Eagle, Crocodile

### Mythic Animals
- Minotaur, War Minotaur, Werewolf, Primordial Werewolf, Centaur, War Centaur, Ghost, Dark Angel, Knight, Wraith Knight

### Legendary Animals
- Wolf, Spirit Wolf, Celestial Wolf, Lich, Elder Lich, Lich King, Grim, Soul Reaper, Grim Reaper, Revenant, Frost Revenant, Frost Revenant King, Golem, Ancient Golem, War Golem

### Fabled Animals
- Leviathan, Abyssal Leviathan, Primordial Leviathan, Medusa, Cursed Medusa, Queen Medusa, Ghidorah, Storm Ghidorah, King Ghidorah, Oracle, Curse Oracle, Seraph Oracle, Godzilla, GVK Godzilla, Burning Godzilla

### Gods Animals
- Anubis, Lord Anubis, Nyx, Goddess of Darkness, Zeus, God of Thunder, Hades, King of Underworld

### Ascendants Animals
- Manhattan, Dr Manhattan, Lucifer, Lucifer Morningstar, Galactus, Galactus The Devourer

### Boundless Animals
- Absolute Being, The Beyonder

### Infinity Animals
- One Above All, The Presence

### Patron Animals
- Exclusive to patron supporters, custom stats and properties

---

## Rarity Drop Mechanics

### Hunt Drop Rates
When hunting, rarity is determined by a weighted roll:
- Boundless: 0.001% + (luckyBoost × 0.01%)
- Fabled: 0.01% + (luckyBoost × 0.02%)
- Legendary: 0.1%
- Mythic: 0.5%
- Epic: 5% + extraEpic%
- Rare: 10%
- Uncommon: 25%
- Common: remainder (~57%)

### Lucky Boost
- Lucky Gems add +2% to Fabled/Boundless drop rates
- Hunt Frenzy event adds +2% rarity boost
- Effects stack additively

---

## Animal Management Commands

| Command | Description |
|---|---|
| `.zoo` | View all animals you own, grouped by rarity |
| `.dex <animal>` | View detailed stats for an owned animal |
| `.tier` | Show all animals grouped by rarity tier |
| `.tier <rarity>` | Show animals for a specific rarity tier |
| `.rename <current> \| <new>` | Rename an animal (max 20 characters) |
| `.evolve <animal>` | Evolve an animal to its next stage |
| `.sell <animal>` | Sell an animal for coins |
| `.sacrifice <animal>` | Sacrifice an animal for gems |

---

## Key Concepts

### Zoo Points
- Points accumulated from owned animals
- Used for leaderboard calculations and progression tracking
- Higher rarity animals give more zoo points

### Base Form
- The first animal in an evolution chain
- Used for determining evolution paths and base stats
- Only base forms can be randomly obtained from hunts

### Stage
- Evolution stage (0, 1, or 2)
- Determines evolution multiplier and role bonus
- Higher stages require evolution stones and duplicate animals

### Trade Locking
- Animals in evolution chains cannot be sold on marketplace while evolving
- Animals in team slots cannot be sold or sacrificed
- Prevents accidental loss of valuable animals

---

## Edge Cases and Special Rules

- **Gods-tier animals**: Cannot be hunted, only obtainable via shop purchase
- **Patron animals**: Exclusive to patron supporters, cannot be sold or sacrificed
- **Boundless/Infinity**: No level cap (Infinity), but no evolution stages
- **Duplicate species**: Cannot have same base animal in the same team slot
- **Evolution limits**: Some rarities have max evolution stages (e.g., Mythic: 1 stage)
- **Role bonuses**: Only apply to Mythic+ animals with defined roles
- **Individual stats**: Common-Epic animals have individual stat variations from tier base