gogobee/gogobee_spell_system.md

# GogoBee — Spell System
> **Companion to:** `gogobee_dnd_design_doc.md`, `gogobee_subclass_system.md`
> **Version:** 1.0

---

## 1. Spell Slots by Class and Level

### Mage Spell Slots
| Level | Cantrips | 1st | 2nd | 3rd | 4th | 5th |
|---|---|---|---|---|---|---|
| 1 | 3 | 2 | — | — | — | — |
| 2 | 3 | 3 | — | — | — | — |
| 3 | 3 | 4 | 2 | — | — | — |
| 4 | 4 | 4 | 3 | — | — | — |
| 5 | 4 | 4 | 3 | 2 | — | — |
| 7 | 4 | 4 | 3 | 3 | 1 | — |
| 9 | 4 | 4 | 3 | 3 | 2 | — |
| 11 | 5 | 4 | 3 | 3 | 3 | 1 |
| 15 | 5 | 4 | 3 | 3 | 3 | 2 |
| 20 | 5 | 4 | 3 | 3 | 3 | 3 |

### Cleric Spell Slots
| Level | Cantrips | 1st | 2nd | 3rd | 4th | 5th |
|---|---|---|---|---|---|---|
| 1 | 3 | 2 | — | — | — | — |
| 3 | 3 | 4 | 2 | — | — | — |
| 5 | 3 | 4 | 3 | 2 | — | — |
| 7 | 4 | 4 | 3 | 3 | 1 | — |
| 9 | 4 | 4 | 3 | 3 | 2 | — |
| 11 | 4 | 4 | 3 | 3 | 3 | 1 |
| 17 | 4 | 4 | 3 | 3 | 3 | 3 |
| 20 | 5 | 4 | 3 | 3 | 3 | 3 |

### Ranger Spell Slots
| Level | Spells Known | 1st | 2nd | 3rd |
|---|---|---|---|---|
| 2 | 2 | 2 | — | — |
| 5 | 3 | 3 | — | — |
| 7 | 4 | 3 | 1 | — |
| 9 | 5 | 3 | 2 | — |
| 13 | 6 | 3 | 2 | 1 |
| 17 | 7 | 3 | 2 | 2 |
| 20 | 8 | 3 | 3 | 2 |

Rangers are half-casters. Spell slots reset on long rest only.

---

## 2. Concentration

Some spells require **Concentration** — they persist until dropped or broken.

- Only one Concentration spell may be active at a time. Casting a second ends the first.
- Taking damage while Concentrating requires a **CON save (DC = 10 or half damage taken, whichever is higher)**. Failure ends the spell.
- Dropping Concentration voluntarily costs no action.
- Flagged in spell entries with `[C]`.

---

## 3. Cantrips

Cantrips cost no spell slots. Usable unlimited times per day.

| Cantrip | Classes | Damage / Effect | Notes |
|---|---|---|---|
| **Fire Bolt** | Mage | 1d10 fire (scales: 2d10 at Lv5, 3d10 at Lv11) | Ranged spell attack |
| **Toll the Dead** | Mage, Cleric | 1d8 necrotic; 1d12 if target missing HP | WIS save for half |
| **Chill Touch** | Mage, Cleric | 1d8 necrotic; target can't heal until next turn | Ranged spell attack |
| **Poison Spray** | Mage | 1d12 poison | CON save or full damage; melee range |
| **Shocking Grasp** | Mage | 1d8 lightning; target loses Reaction | Advantage vs. metal armor |
| **Sacred Flame** | Cleric | 1d8 radiant | DEX save; ignores cover |
| **Guidance** | Cleric, Ranger | +1d4 to one ability check (self or ally) | [C] |
| **Shillelagh** | Ranger, Cleric | Club/staff uses WIS for attack+damage; 1d8 | Bonus action; [C] |
| **Thorn Whip** | Ranger | 1d6 piercing; pull target 10 ft | Ranged; melee range |
| **Mending** | All casters | Repair one non-magical item | Out of combat only |
| **Message** | Mage | Whisper to target up to 120 ft | Utility |
| **Minor Illusion** | Mage | Create a sound or image | Utility; Investigation DC 14 to disbelieve |

---

## 4. 1st Level Spells

### Mage — 1st Level
| Spell | Slots | Effect | Notes |
|---|---|---|---|
| **Magic Missile** | 1st | 3 darts × 1d4+1 force; auto-hit | +1 dart per slot above 1st |
| **Thunderwave** | 1st | 2d8 thunder in 15 ft cube; push 10 ft | CON save half; loud (+8 Threat Clock) |
| **Mage Armor** | 1st | AC = 13 + DEX mod (no armor required) | 8 hours; [C] |
| **Burning Hands** | 1st | 3d6 fire in 15 ft cone | DEX save half |
| **Detect Magic** | 1st | Sense magic within 30 ft | [C]; ritual castable (no slot) |
| **Fog Cloud** | 1st | 20 ft radius heavily obscured | [C]; all attacks inside have disadvantage |
| **Grease** | 1st | 10 ft square; DEX save or Prone | Difficult terrain while active |
| **Shield** | 1st | +5 AC as Reaction until next turn | Reaction spell |
| **Sleep** | 1st | Incapacitate creatures totaling 5d8 HP (weakest first) | HP threshold; mindless immune |
| **Chromatic Orb** | 1st | 3d8 of chosen damage type | Ranged spell attack |

### Cleric — 1st Level
| Spell | Slots | Effect | Notes |
|---|---|---|---|
| **Cure Wounds** | 1st | Heal 1d8 + WIS mod HP | Touch; +1d8 per slot above 1st |
| **Bless** | 1st | 3 targets: +1d4 to attack rolls and saves | [C]; 1 min |
| **Inflict Wounds** | 1st | 3d10 necrotic | Melee spell attack; +1d10 per slot above 1st |
| **Guiding Bolt** | 1st | 4d6 radiant; next attack on target has advantage | Ranged spell attack; +1d6 per slot |
| **Shield of Faith** | 1st | +2 AC to one target | [C]; bonus action; 10 min |
| **Healing Word** | 1st | 1d4 + WIS mod HP (bonus action) | Range 60 ft; +1d4 per slot above 1st |
| **Command** | 1st | One-word command (Flee, Grovel, Halt, etc.) | WIS save negates; 1 turn |
| **Protection from Evil and Good** | 1st | Aberrations, fiends, undead have disadvantage vs. target | [C] |

### Ranger — 1st Level
| Spell | Slots | Effect | Notes |
|---|---|---|---|
| **Hunter's Mark** | 1st | +1d6 damage to marked target; track as bonus action | [C]; bonus action; 1 hr |
| **Ensnaring Strike** | 1st | On hit: STR save or Restrained; 1d6/turn | [C]; bonus action before attack |
| **Fog Cloud** | 1st | 20 ft radius heavily obscured | [C] |
| **Speak with Animals** | 1st | Communicate with beasts | Ritual; 10 min; useful in Forest/Feywild |
| **Absorb Elements** | 1st | Reaction: resistance to incoming elemental damage; +1d6 on next hit | Reaction spell |
| **Cure Wounds** | 1st | 1d8 + WIS mod HP | Touch |

---

## 5. 2nd Level Spells

### Mage — 2nd Level
| Spell | Slots | Effect | Notes |
|---|---|---|---|
| **Scorching Ray** | 2nd | 3 rays × 2d6 fire; each is a separate attack roll | +1 ray per slot above 2nd |
| **Mirror Image** | 2nd | 3 duplicates; attackers roll to hit duplicate (roll d20: 6+ hit duplicate) | No [C]; duplicates absorb hits |
| **Misty Step** | 2nd | Bonus action teleport up to 30 ft | Bypasses OA and difficult terrain |
| **Hold Person** | 2nd | Paralyzed; auto-crit on melee hits while held | WIS save; [C]; +1 target per slot above 2nd |
| **Shatter** | 2nd | 3d8 thunder in 10 ft sphere | CON save half; extra damage to objects/constructs |
| **Blur** | 2nd | All attacks vs. you have disadvantage | [C] |
| **Web** | 2nd | 20 ft cube; Restrained (STR DC to escape) | [C]; flammable |
| **Levitate** | 2nd | Float up to 20 ft; immune to ground-based effects | [C]; CON save to resist if unwilling |
| **Knock** | 2nd | Open any mundane lock or magically sealed door | Loud (+5 Threat Clock) |

### Cleric — 2nd Level
| Spell | Slots | Effect | Notes |
|---|---|---|---|
| **Spiritual Weapon** | 2nd | Bonus action: spectral weapon attacks for 1d8+WIS each turn | No [C]; 1 min; +1d8 per 2 slots above 2nd |
| **Hold Person** | 2nd | Paralyzed; auto-crit melee | WIS save; [C] |
| **Lesser Restoration** | 2nd | Remove one condition (Blinded, Deafened, Paralyzed, Poisoned) | Touch |
| **Prayer of Healing** | 2nd | Heal up to 6 targets 2d8 + WIS mod HP | 10 min cast; out of combat only |
| **Silence** | 2nd | No sound in 20 ft sphere; no verbal spells | [C]; -8 Threat Clock if used strategically |
| **Aid** | 2nd | 3 targets: +5 max HP and current HP | 8 hr; +5 HP per slot above 2nd |
| **Augury** | 2nd | Omen about action in next 30 min: Weal/Woe/Both/Neither | Ritual; TwinBee delivers cryptic answer |

### Ranger — 2nd Level
| Spell | Slots | Effect | Notes |
|---|---|---|---|
| **Pass Without Trace** | 2nd | +10 to Stealth; can't be tracked magically | [C]; -5 Threat Clock per room while active |
| **Spike Growth** | 2nd | 20 ft radius; 2d4 per 5 ft moved through | [C]; Difficult terrain |
| **Silence** | 2nd | No sound; no verbal spells in area | [C] |
| **Beast Sense** | 2nd | See/hear through a beast's senses | [C]; ritual |
| **Cordon of Arrows** | 2nd | 4 arrows guard area; fire on intruders (1d6+DEX) | 8 hr |
| **Find Traps** | 2nd | Detect presence of traps within 120 ft | Doesn't reveal details; no [C] |

---

## 6. 3rd Level Spells

### Mage — 3rd Level
| Spell | Slots | Effect | Notes |
|---|---|---|---|
| **Fireball** | 3rd | 8d6 fire in 20 ft radius | DEX save half; +1d6 per slot; very loud (+12 Threat Clock) |
| **Lightning Bolt** | 3rd | 8d6 lightning in 100 ft line | DEX save half; +1d6 per slot; loud (+10 Threat Clock) |
| **Counterspell** | 3rd | Reaction: cancel a spell of 3rd level or lower | Higher level: INT check DC 10+spell level |
| **Fly** | 3rd | Target gains 60 ft fly speed | [C]; 10 min; bypasses ground traps |
| **Hypnotic Pattern** | 3rd | Creatures in 30 ft cube: Incapacitated, speed 0 | WIS save; [C]; breaks on damage |
| **Dispel Magic** | 3rd | End one magical effect on target | Auto for ≤3rd level; ability check for higher |
| **Slow** | 3rd | Up to 6 targets: halve speed, -2 AC, no reactions, 1 action or bonus | WIS save; [C] |
| **Animate Dead** | 3rd | Animate up to 3 corpses as skeletons/zombies | Cleric/Mage; control 24 hr; re-cast to extend |

### Cleric — 3rd Level
| Spell | Slots | Effect | Notes |
|---|---|---|---|
| **Spirit Guardians** | 3rd | 15 ft aura: 3d8 radiant/necrotic per turn to enemies | WIS save half; [C]; +1d8 per slot above 3rd |
| **Revivify** | 3rd | Restore a creature dead less than 1 minute to 1 HP | Requires 300-coin diamond component |
| **Dispel Magic** | 3rd | End one magical effect | — |
| **Mass Healing Word** | 3rd | Up to 6 targets: 1d4+WIS mod HP (bonus action) | Range 60 ft |
| **Beacon of Hope** | 3rd | Targets have advantage on WIS saves and death saves; max healing | [C]; 1 min |
| **Animate Dead** | 3rd | Animate up to 3 undead | 24 hr control |
| **Remove Curse** | 3rd | End one curse on target or object | Removes attunement to cursed items |

### Ranger — 3rd Level
| Spell | Slots | Effect | Notes |
|---|---|---|---|
| **Lightning Arrow** | 3rd | Ranged attack: 4d8 lightning on hit; 2d8 to creatures within 10 ft | Bonus action before attack |
| **Conjure Barrage** | 3rd | Throw a weapon: 3d8 of weapon type in 60 ft cone | DEX save half |
| **Water Walk** | 3rd | Up to 10 targets walk on liquid surfaces | Ritual; 1 hr |
| **Plant Growth** | 3rd | 100 ft radius: Difficult terrain; or enhance crops | Ritual (crop version); instant (terrain version) |
| **Nondetection** | 3rd | Target undetectable by divination magic | 8 hr; useful in Underdark/Abyss Portal |

---

## 7. 4th Level Spells (Mage / Cleric)

| Spell | Class | Effect | Notes |
|---|---|---|---|
| **Banishment** | Cleric | Send extraplanar creature to home plane temporarily | CHA save; [C]; permanent if held 1 min — critical in Abyss Portal |
| **Polymorph** | Mage | Transform target into beast | WIS save if unwilling; [C]; max CR = target's level |
| **Ice Storm** | Mage | 2d8 bludgeoning + 4d6 cold in 20 ft cylinder | DEX save half; Difficult terrain afterward |
| **Wall of Fire** | Mage | 60 ft wall; 5d8 fire to those passing through | [C]; DEX save half; doubles as zone control |
| **Greater Invisibility** | Mage | Target invisible; attacks have advantage; can't be targeted | [C]; 1 min |
| **Guardian of Faith** | Cleric | Spectral guardian deals 20 radiant to approaching enemies | 50 total damage then vanishes; no [C] |
| **Death Ward** | Cleric | Next time target would drop to 0 HP: drops to 1 instead | 8 hr; one-use |
| **Freedom of Movement** | Cleric, Ranger | Target ignores Difficult terrain, paralysis, restraint | 1 hr |

---

## 8. 5th Level Spells (Mage / Cleric)

| Spell | Class | Effect | Notes |
|---|---|---|---|
| **Cone of Cold** | Mage | 8d8 cold in 60 ft cone | CON save half |
| **Hold Monster** | Mage | Paralyze any creature type (not just humanoid) | WIS save; [C]; auto-crit melee |
| **Wall of Force** | Mage | Invisible impenetrable wall | [C]; nothing passes — including spells |
| **Scrying** | Mage, Cleric | Observe target at any distance | WIS save; [C]; useful for pre-boss recon |
| **Mass Cure Wounds** | Cleric | Up to 6 targets: 3d8+WIS mod HP | Range 60 ft |
| **Flame Strike** | Cleric | 4d6 fire + 4d6 radiant in 10 ft cylinder | DEX save half |
| **Divine Word** | Cleric | Targets suffer effects based on current HP | WIS save negates; kills below 20 HP |
| **Raise Dead** | Cleric | Restore a creature dead up to 10 days | Requires 500-coin diamond; target -4 to all rolls for 4 days |

---

## 9. Spell Rules — Bot Context

### Casting in Combat
- Casting a spell of 1st level or higher uses the **Action** (unless Bonus Action spell or Reaction spell)
- Bonus action spells: if you cast a bonus action spell, any other spell cast this turn must be a cantrip
- Reaction spells (Shield, Counterspell, Absorb Elements) fire outside your turn and consume your Reaction

### Verbal / Material Components
- All spells with Verbal components fail in a **Silence** zone
- Spells with Material components require either a **Spell Component Pouch** or **Arcane Focus** (Mage) / **Holy Symbol** (Cleric)
- Ranger spells use nature focus — no separate item required
- Expensive material components (Revivify, Raise Dead) are tracked as consumed inventory items

### Spell Save DC
```
Spell Save DC = 8 + proficiency bonus + spellcasting modifier
  Mage: INT modifier
  Cleric: WIS modifier
  Ranger: WIS modifier
```

### Spell Attack Bonus
```
Spell Attack Bonus = proficiency bonus + spellcasting modifier
```

### Upcasting
Spells marked with "per slot above Xth" scale when cast at higher levels. The bot handles upcast selection automatically on `!cast <spell> --upcast <level>`.

---

## 10. Go Data Structures

```go
type KnownSpell struct {
    PlayerID   string `json:"player_id"`
    SpellID    string `json:"spell_id"`
    Level      int    `json:"level"`       // spell level (0 = cantrip)
    Source     string `json:"source"`      // class, subclass, racial
    Prepared   bool   `json:"prepared"`    // Cleric must prepare daily; Mage knows fixed list
}

type SpellSlotState struct {
    PlayerID string         `json:"player_id"`
    Slots    map[int]SlotPair `json:"slots"` // key = spell level
}

type SlotPair struct {
    Total int `json:"total"`
    Used  int `json:"used"`
}

type ActiveConcentration struct {
    PlayerID  string    `json:"player_id"`
    SpellID   string    `json:"spell_id"`
    ExpiresAt time.Time `json:"expires_at"`
    SaveDC    int       `json:"save_dc"` // for concentration checks on damage
}

type SpellDefinition struct {
    ID           string   `json:"id"`
    Name         string   `json:"name"`
    Level        int      `json:"level"`
    School       string   `json:"school"`
    Classes      []string `json:"classes"`
    CastingTime  string   `json:"casting_time"`  // action, bonus_action, reaction
    Range        string   `json:"range"`
    Concentration bool    `json:"concentration"`
    Duration     string   `json:"duration"`
    SaveStat     string   `json:"save_stat"`     // empty if attack roll
    AttackRoll   bool     `json:"attack_roll"`
    Description  string   `json:"description"`
    Upcast       string   `json:"upcast"`        // scaling description
    Components   []string `json:"components"`    // V, S, M
    MaterialCost int      `json:"material_cost"` // coins if expensive component
}
```

---

## 11. Implementation Phases

### Phase SP1 — Core Spell Infrastructure
- [ ] `SpellDefinition` registry (all spells this doc)
- [ ] `KnownSpell` and `SpellSlotState` structs and DB schema
- [ ] `!cast <spell>` command with slot consumption
- [ ] Cantrip handling (no slot cost)
- [ ] Spell save DC and spell attack bonus calculation

### Phase SP2 — Concentration System
- [ ] `ActiveConcentration` struct
- [ ] Concentration check on damage (CON save)
- [ ] Casting second concentration spell ends first
- [ ] TwinBee narrates concentration breaks

### Phase SP3 — Advanced Spell Rules
- [ ] Upcasting (`!cast fireball --upcast 4`)
- [ ] Bonus action spell restriction
- [ ] Reaction spells (Shield, Counterspell, Absorb Elements)
- [ ] Silence zone interaction
- [ ] Material component consumption (expensive components)

### Phase SP4 — Prepared Spells (Cleric)
- [ ] Cleric daily preparation (`!prepare <spell>`)
- [ ] Prepared spell limit = WIS mod + Cleric level
- [ ] Rest resets preparation choices

---
*End of Spell System.*