# Weapons, Gems, and Enchantments

## Overview
This file documents the live gear systems that sit on top of animals:
- **Weapons** for stat boosts and slot-based loadouts
- **Weapon crates** and tower crates as alternate gear sources
- **Gems** for hunt modifiers
- **Enchantments** for combat effects on animals (and legacy weapon enchants)
- **Weapon rerolls** for scaling a weapon up or down with gem cost based on player wealth

## Commands

### Weapons

| Command | What it does | Notes |
|---|---|---|
| `.weapon` | Shows owned weapons | Displays top entries, reroll status, equipped slots |
| `.dismantle <weaponId or name>` | Dismantles a weapon for gems | `.weapon sell` was removed |
| `.weapon reroll <weaponId>` | Rolls a random reroll modifier change | Gem cost is dynamic |
| `.equip <weaponId> <animal name>` | Equips weapon to that team's animal slot | Uses `equip_target_team` |
| `.unequip <animal name>` | Removes the weapon from the named team animal | Searches across teams |
| `.shop [page]` | Shows weapon shop pages | 10 items per page |
| `.buy <weaponTypeId>` | Buys a fresh weapon instance | Example: `SWD1` |
| `.crate` | Opens a normal weapon crate | Uses the standard crate drop table |

### Enchantments

| Command | What it does | Notes |
|---|---|---|
| `.enchant <animalName> <enchId>` | Equips an enchantment to an animal | `EN**` enchants are the normal current path |
| `.enchant <weaponId> <enchId>` | Equips a legacy enchant to a weapon | `EF**` path still exists in code |
| `.enchant keep <enchId>` | Removes an equipped enchant but keeps the inventory entry | Keeps remaining usage |
| `.enchants` | Opens the enchantment codex | Shows owned quantity, usage, equipped target |

### Gems

| Command | What it does | Notes |
|---|---|---|
| `.gem` / `.gems` | Shows inventory gems and equipped gem slots | 3 slots max |
| `.gem equip <gemId>` | Equips a gem into its category slot | Removes one gem copy from inventory |
| `.gem unequip <hunt|lucky|stone>` | Unequips the gem in that slot | The gem is consumed and not returned |

## Weapons

### Weapon families and shop pricing

| Family | Mythic | Legendary | Fabled | Gods | Specialty |
|---|---:|---:|---:|---:|---|
| Sword (`SWD`) | 15,000 | 45,000 | 100,000 | 150,000 | Balanced ATK/DEF/crit |
| Katana (`KTA`) | 15,000 | 45,000 | 100,000 | 150,000 | ATK + mana bonus |
| Dagger (`DGR`) | 15,000 | 45,000 | 100,000 | 150,000 | High crit |
| Axe (`AXE`) | 18,000 | 50,000 | 110,000 | 160,000 | Highest raw ATK |
| Hammer (`HMR`) | 18,000 | 50,000 | 120,000 | 170,000 | Tank / DEF-heavy |
| Spear (`SPR`) | 16,000 | 48,000 | 105,000 | 150,000 | Balanced ATK/DEF |
| Scythe (`SCY`) | 17,000 | 48,000 | 110,000 | 160,000 | Lifesteal |

The data file also includes **Ascendant** weapons used by higher-end reward systems.

### Equipping rules
- Weapons are equipped to **team slots**, not directly to animal IDs.
- `.equip <weaponId> <animal>` finds the named animal on the current `equip_target_team`.
- If another weapon is already on that slot, the old one is auto-unequipped.
- A weapon already equipped on another team cannot be reused across teams until unequipped.
- Listed marketplace weapons cannot be equipped.

### Dismantling Weapons
Weapons can be dismantled for gems using `.dismantle <weapon ID>` or `.dismantle <weapon name>`.
You cannot dismantle an equipped weapon.

Gem rewards by rarity:
- **Mythic**: 400 💎
- **Legendary**: 1,000 💎
- **Fabled**: 2,500 💎
- **Gods**: 4,000 💎
- **Ascendant**: 6,000 💎

## Weapon Rerolls

### Reroll cost
Reroll cost is based on the player's current coin wealth:

| Coin balance | Reroll cost |
|---|---:|
| `< 100,000` | 700 gems |
| `100,000 - 999,999` | 900 gems |
| `1,000,000 - 9,999,999` | 1,200 gems |
| `10,000,000+` | 1,500 gems |

### Reroll result table
Each reroll adds one random step from:

```text
-50, -40, -30, -20, -10, 0, +10, +20, +30, +40, +50
```

The accumulated reroll bonus is clamped to:

```text
minimum -100%
maximum +200%
```

`reroll_count` increases by 1 each time.

### Where rerolls matter
Reroll bonuses are applied in multiple systems:
- normal dungeon team weapon loading
- guild raid/guild war team building
- guild boss skirmish building

## Normal Weapon Crates

### Source
- 1x from `.daily`
- purchasable with `.buy crate` for **3,000 coins**
- can also come from some reward systems

### Live drop table
Standard `.crate` uses this weight table:

| Outcome | Weight | Approx. chance |
|---|---:|---:|
| Enchantment | 60 | 60% |
| Sacrificial Diamond | 18 | 18% |
| Legendary weapon | 7 | 7% |
| Nothing | 15 | 15% |

### Crate outcomes
- **Enchantment** -> random enchant tier from `pickEnchantment()`
- **Diamond** -> 1x `SDMND`
- **Weapon** -> random Legendary weapon instance
- **Nothing** -> empty crate result

## Tower Crates
Tower-exclusive crates are separate from normal `.crate` and are opened with:
- `.mythic crate`
- `.legendary crate`
- `.fabled crate`
- `.gods crate`
- `.ascendant crate`
- `.infinity crate`

Their drop tables are defined in `server/data/towerCrates.js` and can award animals, weapons, evolution stones, enchantments, coins, and profiles depending on crate tier.

## Enchantments

### Inventory and usage model
Enchantments are stored in `inventory` as:
- `item_type='enchantment'`
- `item_id='<enchant id>'`
- `quantity`
- `usage`

Key rule:
- each copy adds **50 usage**
- stacked copies share a **single pooled usage total**

Example:
- 1 copy -> 50 usage
- 2 copies -> 100 usage
- 3 copies -> 150 usage

### Usage consumption
After a battle/raid/dungeon/war/boss attack, the server consumes **1 usage per unique equipped enchant ID** on the user's current team.

When usage hits 0:
- that enchant is removed from all of the user's animals,
- removed from all of the user's weapons carrying it,
- deleted from the inventory table.

### Equip / keep rules
- `EN**` enchants equip to animals.
- `EF**` enchants still equip to weapons through the legacy branch.
- `.enchant keep <id>` only removes the equipped link; it does **not** restore usage.

### Double Enchantment System
**Level 25+ animals can equip 2 enchantments simultaneously.**

#### Commands
- `.enchant <animalName> <enchId>` - Equip enchantment to slot 1
- `.enchant2 <animalName> <enchId>` - Equip enchantment to slot 2 (requires level 25)
- `.unequipenchant1 <animalName>` - Unequip enchantment from slot 1
- `.unequipenchant2 <animalName>` - Unequip enchantment from slot 2
- `.enchant keep` - Keep enchantments on your current team animals

#### Rules
- **Level 25 Unlock**: The second enchantment slot unlocks at level 25
- **No Duplicates**: You cannot equip the same enchantment to both slots on the same animal
- **Shared Mana Pool**: Both enchantments share the same mana pool
- **Sequential Trigger**: Enchantments trigger in order (slot 1 first, then slot 2) when applicable
- **Independent Usage**: Each enchantment has its own usage counter (50 uses per copy)

#### Validation
- Animals below level 25 cannot equip a second enchantment
- Attempting to equip duplicate enchantments will be rejected
- Usage is tracked independently for each enchantment slot

### Sell restrictions
The marketplace helper blocks enchantment sales when:
- usage is below the full stacked maximum,
- the enchant is equipped and the player only has one copy.

### Live enchant list

| ID | Name | Tier | Core effect |
|---|---|---|---|
| `EN01` | Critical | Mythic | 26% chance to multiply damage by x1.52 for 48 mana |
| `EN02` | Spirit Guard | Legendary | Opening heal from remaining mana + 24% passive damage reduction |
| `EN03` | Mana Tap | Legendary | On hit, spends mana to restore ally mana from dealt damage |
| `EN04` | Sacrifice | Legendary | On death, burns mana and heals allies for 30% max HP |
| `EN05` | Resurrection | Legendary | Once per battle revive at 11% HP |
| `EN06` | Taunting | Legendary | 3-turn taunt, ~75% forced focus, 35% damage reduction |
| `EN07` | Kamikaze | Fabled | On death, burns mana and explodes for 12% max HP damage |
| `EN08` | Health Point | Mythic | Battle-start +25% max HP |
| `EN09` | Reflection | Mythic | Reflects 26% damage for 3 turns |
| `EN10` | Mana Tank | Mythic | Battle-start +45% max mana to allies |
| `EN11` | Negator | Fabled | Nullifies enemy enchantments for 3 turns (7-turn cooldown) |
| `EN12` | Time Freeze | Fabled | Freezes a random enemy for 2 turns |
| `EN13` | Combat Combo | Mythic | +8% attack damage per stack, up to 9 stacks |
| `EN14` | Mana Whip | Fabled | First swing converts full mana into x5 bonus burst damage |
| `EN15` | Healer | Fabled | Periodic lowest-ally healing |

## Gems

### Slot model
The gem system has exactly **three categories**, one slot each:
- `hunt`
- `lucky`
- `stone`

`gem_slots` stores:
- `user_id`
- `category`
- `gem_id`
- `charges`

### Equip / unequip behavior
- Equipping removes one gem copy from inventory and fills the slot with its starting charges.
- Each successful `.hunt` consumes **1 charge** from each equipped slot.
- If charges drop to 0, the slot is deleted automatically.
- Manual `.gem unequip ...` also deletes the slot, and the gem is **gone permanently**.

### Live gem behavior in hunt logic
The hunt command currently checks **slot presence**, not gem tier scaling, so the live effects are:

| Category | Live effect in `hunt.js` |
|---|---|
| Hunt gem | Doubles the post-stone hunt count (`baseCount *= 2`) |
| Lucky gem | Adds a flat **+2** lucky boost into `rollHunt()` |
| Stone gem | Adds **+3 animals** before hunt doubling |

That means the tier difference currently matters mainly through **starting charges**, not stronger live hunt math.

### Gem definitions and charges

| ID | Name | Category | Charges |
|---|---|---|---:|
| `HGC` | Green Hunting Gem | Hunt | 10 |
| `HGR` | Yellow Hunting Gem | Hunt | 25 |
| `HGM` | Red Hunting Gem | Hunt | 50 |
| `LGC` | Green Lucky Gem | Lucky | 10 |
| `LGR` | Yellow Lucky Gem | Lucky | 15 |
| `LGM` | Red Lucky Gem | Lucky | 20 |
| `GST` | Gemstone | Stone | 20 |

### Gem sources
- Hunt drops: 5% gem drop chance using the weighted `rollGemDrop()` table
- Lootboxes: 10% gem outcome branch, then equal random pick across all 7 gem IDs

## Database / Storage Details
- Weapons live in `weapons`
- Enchantments live in `inventory` as `item_type='enchantment'`
- Gems live in `inventory` as `item_type='gem'`
- Equipped gem slots live in `gem_slots`
- Weapon reroll fields: `weapons.reroll_bonus`, `weapons.reroll_count`
- Equipped links: `weapons.animal_slot`, `weapons.enchant_id`, `animals.enchant_id`

## Strategic Tips / Balance Notes
- Rerolling is effectively an endgame gem sink because the cost rises with your coin wealth.
- Market-bought weapons are especially valuable because rerolls and weapon enchants stay on the item.
- Manual gem unequip is destructive, so only socket gems you plan to use through their charges.
- Lucky gem tiers currently differ by charge count more than live hunt power because `hunt.js` applies a flat lucky bonus whenever any lucky gem is slotted.
- Enchantments are best treated as durable but finite resources: each duplicate extends a shared usage pool by another 50.