# Inventory & Animal Management

## Overview
The inventory system manages all player-owned items: animals, weapons, enchantments, gems, evolution stones, materials, lootboxes, crates, and profile pictures. Animals have a full lifecycle including catching, leveling, renaming, evolving, sacrificing, selling, and crafting into higher rarities.

---

## Commands

| Command | Description |
|---|---|
| `.inventory` / `.inv` | View all owned items |
| `.zoo` | View your animal collection |
| `.zoo @user` | View another player's zoo |
| `.dex <name>` | View detailed stats for a specific animal you own |
| `.tier [rarity]` | Browse all animal tiers and drop rates |
| `.rename <old> \| <new>` | Rename an animal (max 20 chars) |
| `.sacrifice <name>` | Sacrifice an animal for 💎 gems |
| `.sacrifice <count> <name>` | Sacrifice multiple copies |
| `.sacrifice <rarity>` | Bulk sacrifice all animals of a rarity |
| `.sell <name>` | Sell an animal for 🪙 coins |
| `.sell <count> <name>` | Sell multiple copies |
| `.sell <rarity>` | Bulk sell all animals of a rarity |
| `.craft <epic\|mythic\|legendary>` | Craft a higher-rarity animal from lower ones |
| `.craft <rarity> diamond` | Diamond craft — fewer animals, max stats |
| `.lootbox` | Open a lootbox |
| `.crate` | Open a weapon crate |
| `.enchants` | View all enchantments and owned status |
| `.get items` | Claim items from temporary overflow storage |

---

## Animal Rarity Values

| Rarity | Drop Rate | Sell Value | Sacrifice Value | Zoo Points | XP | Shop Price |
|---|---|---|---|---|---|---|
| Common | 100 | 1 🪙 | 5 💎 | 2 | 2 | — |
| Uncommon | 25 | 3 🪙 | 10 💎 | 5 | 5 | — |
| Rare | 10 | 10 🪙 | 20 💎 | 10 | 20 | — |
| Epic | 5 | 250 🪙 | 40 💎 | 250 | 400 | — |
| Mythic | 2 | 5,000 🪙 | 150 💎 | 2,000 | 1,000 | 10,000 🪙 |
| Legendary | 0.7 | 35,000 🪙 | 500 💎 | 5,000 | 2,000 | 75,000 🪙 |
| Fabled | 0.04 | 200,000 🪙 | 1,500 💎 | 10,000 | 5,000 | — |
| patron | 0 | 0 🪙 | 0 💎 | 12,000 | 10,000 | — |
| Gods | 0 | 2,500,000 🪙 | 2,500 💎 | 15,000 | 15,000 | 5,000,000 🪙 |
| Boundless | 0.06 | 5,000,000 🪙 | 5,000 💎 | 30,000 | 15,000 | — |

---

## Base Stats by Rarity

| Rarity | HP | ATK | DEF | SPD | Mana |
|---|---|---|---|---|---|
| Common | 80 | 10 | 5 | 12 | 50 |
| Uncommon | 120 | 20 | 10 | 16 | 80 |
| Rare | 250 | 50 | 30 | 25 | 150 |
| Epic | 500 | 90 | 60 | 40 | 250 |
| Mythic | 1,200 | 300 | 150 | 100 | 350 |
| Legendary | 2,500 | 600 | 300 | 200 | 500 |
| Fabled | 5,000 | 1,200 | 600 | 400 | 800 |
| patron | 10,000 | 2,500 | 1,100 | 1,000 | 1,300 |
| Gods | 10,000 | 2,500 | 1,200 | 800 | 1,200 |
| Boundless | 20,000 | 5,000 | 2,500 | 1,500 | 2,000 |

- **Level scaling:** +10% per level to all stats
- Individual animals may have custom baseStats that override tier defaults

---

## Level Caps

| Rarity | Max Level |
|---|---|
| Common–Epic | 5 |
| Mythic | 10 |
| Legendary | 15 |
| Fabled | 20 |
| patron | 30 |
| Gods | 30 |
| Boundless | ∞ |

---

## Evolution System

Animals of mythic+ rarity can evolve through stages, gaining new forms and stat bonuses.

### Evolution Chains
- **1-stage chains** (→ +): Minotaur, Centaur, Ghost, Werewolf, Knight, Anubis, Nyx, The Presence, Zeus, Hades
- **2-stage chains** (→ + → ++): Wolf, Lich, Grim, Revenant, Golem, Leviathan, Medusa, Ghidorah, Oracle, Godzilla

### Evolution Limits

| Rarity | Max Stage |
|---|---|
| Mythic | 1 (+) |
| Legendary | 2 (++) |
| Fabled | 2 (++) |
| Gods | 1 (+) |
| patron | 0 (no evolution) |
| Boundless | 0 (no evolution) |

### Role Bonuses
Evolved animals gain role-based stat bonuses:

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

---

## Zoo

- Shows all owned animals grouped by rarity tier
- Display order: Boundless → Gods → patron → Fabled → Legendary → Mythic → Epic → Rare → Uncommon → Common
- Shows: species name, icon, count, max level
- Total zoo points calculated from all owned animals
- Zoo points contribute to leaderboard score

---

## Dex (Animal Details)

Shows detailed information for a specific **owned** animal:
- Name, rarity, evolution label (e.g., "Legendary+")
- Full stats: HP, ATK, DEF, SPD, Mana
- Level, XP, XP needed for next level
- Evolution chain with current stage highlighted
- Equipped weapon and enchantment (if any)
- Must own the animal to view it (otherwise: "🔒 You have not discovered this creature yet")

---

## Rename

- **Syntax:** `.rename <old name> | <new name>`
- Max 20 characters
- Allowed characters: `a-z A-Z 0-9 spaces _ -`
- Matches by name (case-insensitive)

---

## Sacrifice

Converts animals into 💎 gems. Animals must be:
- **Not in any team** (team_slot = 0)
- **Not equipped** (equipped = 0)

**Modes:**
- `.sacrifice <name>` — sacrifice 1 animal
- `.sacrifice <count> <name>` — sacrifice N copies (max 500)
- `.sacrifice <rarity>` — bulk sacrifice all animals of that rarity

---

## Sell

Converts animals into 🪙 coins. Same restrictions as sacrifice (not in team, not equipped).

**Modes:**
- `.sell <name>` — sell 1 animal
- `.sell <count> <name>` — sell N copies (max 500)
- `.sell <rarity>` — bulk sell all animals of that rarity

---

## Crafting

Combines lower-rarity animals + coins into a random higher-rarity animal.

### Recipes

| Output | Input Rarity | Animals Needed | Coin Cost |
|---|---|---|---|
| Epic | Rare | 3 | 5,000 🪙 |
| Mythic | Epic | 5 | 20,000 🪙 |
| Legendary | Mythic | 3 | 70,000 🪙 |

### Standard Craft
- Sacrificed animals are destroyed (lowest HP first)
- Output animal is a random base form of the target rarity
- Stats: **80%–110%** of tier base stats (random roll)

### Diamond Craft (`.craft <rarity> diamond`)
- Requires 1 💠 Sacrificial Diamond (consumed)
- **1 fewer animal** required (minimum 1)
- Stats: **125%** of tier base stats (guaranteed max)
- Animals in teams or marketplace listings cannot be used

---

## Enchantment Usage System

Enchantments have a **limited usage** system:
- Each enchantment copy provides **50 uses**
- Stacking: 2 copies = 100 uses, 3 copies = 150 uses, etc.
- **1 use consumed per battle/raid/dungeon/war** for each equipped enchantment
- When usage reaches 0: enchantment is removed from all animals/weapons and deleted from inventory
- Used enchantments **cannot be sold** on the marketplace
- Equipped enchantments cannot be sold unless you have duplicate copies

---

## Inventory Capacity

- **Default capacity:** 100 items
- Items tracked: gems, enchantments, lootboxes, crates, evolution stones, materials
- Each **weapon** also counts as 1 capacity slot
- When full, new items go to **temporary storage**
- Use `.get items` to claim from temp storage when space opens
- Temp storage items have an expiry time

---

## Inventory Categories

| Category | Contents |
|---|---|
| Gems | Hunting gem, Lucky gem, Gemstone |
| Enchantments | EN01–EN15 (with usage tracking) |
| Weapons | All owned weapons (top 20 shown) |
| Lootboxes | Openable containers with random animals |
| Crates | Openable containers with enchantments/weapons/diamonds |
| Evolution Stones | Mythic, Legendary, Fabled, Gods stones |
| Materials | Sacrificial Diamond (SDMND) |
| Profiles | Owned profile pictures |

---

## Edge Cases

- Animals in a team cannot be sold, sacrificed, or used in crafting
- Animals listed on marketplace cannot be used in crafting
- Renaming only changes the display name — the `animal_key` stays the same
- Bulk sacrifice/sell uses rarity names as arguments (e.g., `.sacrifice common`)
- Dex lookup matches by display name, case-insensitive
- Zoo shows aggregated species counts — individual animals are not listed separately
- Crafting always produces base forms (stage 0), never evolved forms
- Diamond craft consumes the Sacrificial Diamond from inventory