# Battle System

## Overview
The battle system is Advenexus's turn-based combat mechanic. Players build a team of up to 3 animals, equip weapons and enchantments, and fight against AI bots or other players. Battles are simulated server-side with speed-based turn order, crits, enchantment abilities, and mana management.

---

## Commands

| Command | Description |
|---|---|
| `.battle` | Fight a random bot |
| `.battle @user` | Challenge another player to PvP |
| `.battle ranked` | Ranked battle (affects ELO, costs stamina) and fights with real players team builds. |
| `.battle gods` | Fight a super-tier bot (hardest difficulty) |
| `.accept` | Accept a PvP challenge (must respond within 60 seconds) |
| `.team` | View your team(s) |
| `.team add <animal>` | Add an animal to your active equip team (max 3) |
| `.team remove <animal>` | Remove an animal from your team |
| `.leaderboard` | View the top 20 players ranked by ELO |

---

## Cooldown

- **20 seconds** between battles

---

## Battle Modes

### Normal Bot Battle (`.battle`)
- Fight a randomly selected bot from 4 difficulty tiers
- Bot selection weighted: **50% weak**, **30% weak/mid**, **15% mid/strong**, **5% strong/super**
- Daily bot battle reward cap: **20 battles/day** — after 20 wins, you gain 0 coins and 0 XP

### Ranked Battle (`.battle ranked`)
- Costs **1 battle stamina** (100/day, refills at 11 PM UTC)
- Matchmaking: **27% real players**, **70% strong bots**, **3% super bots**
- Affects ELO rating
- ELO changes:
  - Win vs real player: **+25 ELO** (loser: -20 ELO, min 100)
  - Win vs ranked bot: **+20 ELO**
  - Loss vs ranked bot: **-10 ELO** (min 100)

### Gods Battle (`.battle gods`)
- Always fights the hardest **super-tier** bots
- No stamina cost
- Normal reward rules apply

### PvP Challenge (`.battle @user`)
- Challenger sends invite, opponent must `.accept` within **60 seconds**
- Cannot battle yourself
- Loser loses **500 coins**
- No ELO changes in normal PvP

---

## Team System

- Each player has **2 teams** (Team 1 and Team 2)
- Each team holds **up to 3 animals**
- Only the **active team** is used in battle
- Cannot add duplicate species (same base animal key) to the same team
- Animals in a team cannot be sold, sacrificed, or listed on marketplace

### Team Slots
- Animals are assigned slots 1–3 within each team
- Weapons are equipped per-slot (slot 1 weapon goes on slot 1 animal)
- Removing an animal auto-repacks slot numbers

---

## Combat Mechanics

### Turn Order
- All alive animals from both sides are queued each turn
- Sorted by **speed (SPD)** — highest goes first
- Ties broken randomly

### Damage Formula
```
mitigation = DEF / (DEF + ATK × 0.8)
rawDamage = rollDamage(max(1, ATK × (1 - mitigation × 0.6)))
```
- `rollDamage` adds ±20% random variance
- Base crit chance: **12%**, crit multiplier: **1.75×**

### Targeting
- Default: targets enemy with **lowest current HP**
- If an enemy has **Taunt** active: **67% chance** to be forced to target them

### Max Turns
- Battle ends after **50 turns** — if both sides still alive, it's a **tie**

---

## Battle Rewards

### Win Rewards
| Reward | Amount |
|---|---|
| Coins | 100–300 🪙 (random) |
| XP | 50 + (turns × 5) |
| Animal XP | Same as player XP, given to each winning team animal |
| Win streak | +1 (tracked, highest streak saved) |
| Weapon Crate | 10% chance per win (max 3/day) |

### Loss Penalties
| Penalty | Amount |
|---|---|
| Coins lost | 500 🪙 |
| Win streak | Reset to 0 |

### Tie
- Both players get **20 XP**
- No coins gained or lost

---

## Weapons

Weapons provide stat bonuses when equipped to team slots. Three tiers available:

### Weapon Types

| Type | Specialty | Stats |
|---|---|---|
| Sword (SWD) | Balanced | ATK + small DEF + crit |
| Staff (STF) | Mage | ATK + DEF + mana bonus |
| Dagger (DGR) | Crit-focused | Lower ATK + high crit |
| Bow (BOW) | Crit | ATK + crit |
| Axe (AXE) | Raw damage | Highest ATK + small DEF |
| Hammer (HMR) | Tank | Equal ATK + DEF |
| Spear (SPR) | Balanced | ATK + moderate DEF |
| Scythe (SCY) | Lifesteal | ATK + lifesteal % |

### Weapon Tiers & Prices

| Tier | ATK Range | Price |
|---|---|---|
| Mythic | 80–150 | 15,000–18,000 🪙 |
| Legendary | 140–250 | 45,000–50,000 🪙 |
| Fabled | 220–380 | 100,000–120,000 🪙 |

### Weapon Reroll Bonus
- Weapons can have a `reroll_bonus` (percentage)
- All weapon stats (ATK, DEF, crit, mana, lifesteal) are multiplied by `1 + (reroll_bonus / 100)`

---

## Enchantments

Enchantments are mana-based abilities applied to animals. Each animal can have one enchantment. Enchantments consume mana during battle.

### Mana by Rarity

| Rarity | Mana Range |
|---|---|
| Common | 20 |
| Uncommon | 30 |
| Rare | 40 |
| Epic | 50–70 |
| Mythic | 100–150 |
| Legendary | 200–300 |
| Fabled | 400–500 |
| Gods | 500–600 |
| Boundless | 800–900 |

### Enchantment List

| ID | Name | Tier | Effect |
|---|---|---|---|
| EN01 | Critical | Mythic | 26% chance per hit: ×1.52 damage (costs 48 mana) |
| EN02 | Spirit Guard | Legendary | Battle start: pays 108 mana, heals allies 40% of remaining mana. Passive: -24% incoming damage |
| EN03 | Mana Tap | Legendary | On hit: pays 92 mana to restore all allies' mana by 20% of damage dealt |
| EN04 | Sacrifice | Legendary | On death: burns 78% mana, heals allies 30% of this animal's max HP |
| EN05 | Resurrection | Legendary | Once per battle: pays 195 mana to revive fallen ally at 11% max HP |
| EN06 | Taunting | Legendary | Battle start: pays 118 mana, taunts for 3 turns (67% forced target), -20% damage taken |
| EN07 | Kamikaze | Fabled | On death: burns 80% mana, deals 12% of max HP to random enemy |
| EN08 | Health Point | Mythic | Battle start: pays 58 mana, +25% max HP |
| EN09 | Reflection | Mythic | Pays 62 mana once: reflects 26% damage back for 3 turns |
| EN10 | Mana Tank | Mythic | Battle start: pays 52 mana, all allies gain +45% max mana |
| EN11 | Negator | Fabled | Pays 235 mana: nullifies all enemy enchantments for 3 turns. 7-turn cooldown |
| EN12 | Time Freeze | Fabled | Pays 210 mana: freezes random enemy for 2 turns. 6-turn cooldown |
| EN13 | Combat Combo | Mythic | Each attack pays 38 mana: +8% damage per stack (max 9 stacks = +72%) |
| EN14 | Mana Whip | Fabled | First swing: consumes all mana, deals ×5 max mana as bonus damage |
| EN15 | Healer | Fabled | Every 2 turns: pays 165 mana, heals lowest-HP ally for 14% of their max HP |

### Enchantment Interactions
- **Negated** animals cannot use their enchantments for the duration
- **Frozen** animals skip their turn entirely
- **Resurrection** cannot chain (one revive per resurrector per battle)
- **Taunt** + **Spirit Guard** = tanky frontliner that absorbs hits and reduces damage
- **Combat Combo** stacks persist all battle — strongest with high-mana animals
- **Mana Whip** is a one-shot nuke that burns all mana on first attack

### Enchantment Drop Tiers (from crates)

| Tier | Weight |
|---|---|
| Mythic | 35% |
| Legendary | 20% |
| Fabled | 8% |

---

## Bot Difficulty Tiers

The game has **35 pre-built bot opponents** across 4 tiers:

| Tier | Animals | Levels | Count |
|---|---|---|---|
| Weak | Common–Uncommon | 1–6 | 8 bots |
| Mid | Rare–Epic | 7–14 | 10 bots |
| Strong | Mythic–Legendary (evolved) | 13–20 | 10 bots |
| Super | Fabled–Boundless (max evolved) | 20–50 | 8 bots |

- Bots have anime-themed names (e.g., Goku, Saitama, Rimuru_Tempest)
- Higher-tier bots have full weapon loadouts with enchantments
- The hardest bot (Yogiri) runs 3× One Above All / Absolute Being at level 50 with triple Fabled Axe + Mana Whip

---

## Leaderboard

- Ranked by **ELO** (default starting value, min 100)
- Shows top 20 players
- Displays: username, ELO, wins, losses, ranked W/L, level, streak, highest streak, equipped profile

### Leaderboard Points Formula
```
points = max(0, round(zooPoints / 250 × 5) + wins × 2 - losses)
```

---

## Edge Cases

- You cannot battle without a team — must `.team add` at least 1 animal first
- Cannot battle yourself in PvP
- PvP challenge expires after 60 seconds
- Battle stamina only consumed for ranked battles
- Daily bot battle cap (20) only affects reward gains — you can still fight, but earn nothing
- Enchantment usage is consumed after each battle (enchantments have limited uses)
- Loser in PvP loses 500 coins (coins cannot go below 0)
- ELO floor is 100 — cannot drop lower