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

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.