homebrew-magic-rpg/_drafts/foundry-spell-reference.md

FoundryVTT Spell Reference - HbM RPG v3

Status: Draft / Planning Document Audience: Developer (next iteration of hbm-rpg-v3 Foundry system) Purpose: Single source of truth for all spells across all books + gap analysis for SpellData model and casting logic.

---

Table of Contents

1. Schools & Disciplines Inventory
2. Witch Magic Symbols Inventory
3. Sacred Magic Deities Inventory
4. Unified Spell Catalog
5. SpellData Model - Gap Analysis
6. Casting Logic - Gap Analysis
7. Constants Module - Required Additions
8. Character Sheet Spell Tab - Enhancement Spec
9. Spell Item Sheet - Enhancement Spec
10. Compendium Pack Plan
11. Implementation Phases

---

1. Schools & Disciplines Inventory

1.1 Academic disciplines (Eastern European School of Magic)

Discipline ID (en)	Polish name	Color	Notes
transmutation	Alchemia Transmutacji	Brązowy + fioletowy	Subset of legacy Taumaturgia
brewing	Warzenie Eliksirów	Brązowy + zielony	Subset of legacy Taumaturgia
botany	Botanika	Zielony	-
elementsAir	Magia Żywiołów - Powietrze	Żółty	-
elementsWater	Magia Żywiołów - Woda	Niebieski	-
elementsFire	Magia Żywiołów - Ogień	Pomarańczowy	-
elementsEarth	Magia Żywiołów - Ziemia	Jasnozielony	-
artifacts	Rzemiosło Artefaktów	Fioletowy	Subset of legacy Taumaturgia
golemancy	Golemancja	-	Subset of legacy Taumaturgia, no spells in books
runes	Magia Runiczna	-	Subset of legacy Taumaturgia, no spells in books
sources	Źródła Mocy	Tęcza	-
illusion	Magia Iluzji	Bladoniebieski	-
sacred	Magia Sakralna	Biały (egzorcyści: czarny)	Sub-divided by deity
witch	Wiedźmia Magia	-	Symbol-based casting
necromancy	Nekromancja	(kanon)	-

1.2 Forbidden / extra-academic disciplines

Discipline ID (en)	Polish name	Source book
blood	Magia Krwi	Arcanum Sanguinis
crimson	Magia Szkarłatu	Chwała Szkarłatnemu Kultowi
abyssAspects	Magia Otchłani - Magia Aspektów	Klątwa Otchłani
abyssPrimal	Magia Otchłani - Pierwotna Magia	Klątwa Otchłani
wildWitch	Dzika Wiedźmia Magia	Klątwa Otchłani / Księga Magii

---

2. Witch Magic Symbols Inventory

Note

: List is extensible - more symbols may be added in future content. Stored as string[] in constants.ts, used for autocomplete only; spell data accepts arbitrary strings.

Symbol	Domain meaning
Potentia	Power / damage
Tutamen	Protection / shield
Lux	Light
Motus	Movement
Iter	Travel / path
Vacuos	Void / displacement
Vitium	Decay / corruption
Praecantatio	Magic itself
Aer	Air
Aqua	Water
Gelum	Cold / ice
Ignis	Fire
Terra	Earth
Cognitio	Knowledge / mind
Alienis	Alien / foreign
Illusio	Illusion
Somnium	Dream
Tenebrae	Shadow / darkness
Auram	Aura
Vinculum	Binding
Telum	Weapon / projectile
Sensus	Sense / perception
Perditio	Destruction
Perfodio	Piercing / digging
Sano	Healing
Volatus	Flight
Tempestas	Storm

---

3. Sacred Magic Deities Inventory

Deity ID	Polish label	Notes
common	Modlitwy Powszechne	Available to all sacred casters
jahwe	Bóg-Jahwe-Jedyny	Some spells race-gated (Anioł, Człowiek)
zeus	Zeus-Jowisz	Storm domain
demeter	Demeter-Ceres	Agriculture / nature
artemis	Artemida-Diana	Hunt / beasts
hekate	Hekate	Hybrid sacred/witch - symbols + zeal
aphrodite	Afrodyta-Wenus	Charm / persuasion
eros	Amor-Eros	Bonds / desire

Hekate is special: her spells have witch-magic symbols and complexity, allowing them to be cast either as sacred (zeal) or witch (mana + symbols) prayers.

---

4. Unified Spell Catalog

Format per spell:

• Name (Polish), id (slug for compendium)
• school / discipline / deity / castingMode
• circle (T:Y) → difficulty.threshold:difficulty.successes
• manaCost / bloodCost (where applicable)
• castingTime / range / areaOfEffect / targets / duration
• components (verbal / somatic / material / symbols)
• requirements (race / talent / discipline mastery)
• flags (isSuperspell, nonCombatOnly, requiresGroupCast)
• damageBase (formula reference)
• statusEffects[] (conditions applied)
• overcastOptions[]
• sourceBook

4.1 Magia Ogólna (Księga Magii)

#	id	Name	T:Y	Mana	Range	Duration	Symbols	Damage	Status	Notes
1	magic-missile	Magiczny Pocisk	4:1	1	15 m	inst.	Potentia	½ magicalAbilities	-	Overcast: +1 dmg
2	magic-shield	Magiczna Tarcza	5:1	2	5 m	2 r	Tutamen	-	-	HP = ½ MA + 1; OC: +1d2 HP / +1 r
3	gleam	Poblask	3:1	1	self	1 h	Lux	-	-	Item glows; OC: +1 h
4	telekinesis	Telekineza	4:1	1	20 m	10 r	Motus	-	-	≤1 kg; OC: +10 r / +1 kg
5	blink	Przeskok	5:2	3	20 m	inst.	Iter, Praecantatio	-	-	No AoO; OC: +5 m
6	teleport	Teleportacja	6:3	5	known location	inst. (cast 10 min)	Iter, Praecantatio, Vacuos	-	-	OC: +1 person (3 mana)
7	ether-pierce	Przebicie Eteru	5:3	4	10 m	inst.	Tutamen, Vitium	½ MA, ignores armor	-	2 dmg = 1 Rune Shield; OC: +1d2 dmg
8	energy-wave	Fala Energii	5:2	4	10 m	inst.	Praecantatio, Potentia	½ MA AoE	Oszołomiony (Reflex save)	Rect 3×8 m; OC: +1d3 dmg / +2 Y
9	truth-glimpse	Przebłysk Prawdy	4:1	1	touch	1 r	Cognitio	-	-	+1 die lie/behavior; OC: +1 r / +1 die
10	quick-thought	Szybka Myśl	5:1	1	self	1 r	Cognitio	-	-	+1 init, +1 die; OC stacking

4.2 Magia Żywiołów - Powietrze

#	id	Name	T:Y	Mana	Range	Duration	Symbols	Damage	Status
11	flight	Latanie	5:2	3	self	10 r	Volatus	-	-
12	air-wave	Powietrzna Fala	5:1	3	10 m	inst.	Aer, Potentia	½ MA AoE	Powalony (Strength save)
13	danger-sense	Wyczucie Zagrożenia	6:1	4	self	2 r	Aer, Sensus	-	-
14	accuracy	Celność	6:1	2	self	2 r	Sensus, Telum	-	-
15	wind-swift	Szybki jak Wiatr	5:1	1	self	1 r	Motus	-	Immune Powalony

4.3 Magia Żywiołów - Woda

#	id	Name	T:Y	Mana	Range	Duration	Symbols	Damage	Status
16	water-create	Tworzenie i Kontrolowanie Wody	5:1	1	5 m	10 min	Aqua	-	-
17	ice-floor	Lodowa Podłoga	6:1	3	10 m	2 r	Gelum, Vinculum	-	Powalony (Athletics save)
18	solace	Ukojenie	5:1	2	self	1 r	Sano	heal ½ MA	-
19	hailstorm	Gradobicie	5:4	5	10 m	2 r	Gelum, Praecantatio, Tempestas	MA dmg	Trudny Teren; Reflex save
20	mystic-fog	Mistyczna Mgła	5:3	4	self	1 r	Aqua, Tenebrae	-	Oślepiony (enemies)

4.4 Magia Żywiołów - Ogień

#	id	Name	T:Y	Mana	Range	Duration	Symbols	Damage	Status
21	ignition	Podpalenie	5:2	3	15 m	1 r	Ignis, Vinculum	3 + 3/turn	Podpalony
22	kindle	Wzniecanie Ognia	3:1	1	touch	inst.	Ignis	-	-
23	fire-cloak	Ognista Powłoka	5:2	4	self	3 r	Ignis, Telum	weapon +2 magical	-
24	fireball	Kula Ognia	6:1	2	15 m	inst.	Ignis, Potentia	MA	Podpalony 3 r (Reflex save)
25	burning-skin	Gorejąca Skóra	4:3	5	self	1 r	Ignis, Tutamen	½ MA reactive	-

4.5 Magia Żywiołów - Ziemia

#	id	Name	T:Y	Mana	Range	Duration	Symbols	Damage	Status
26	stone-shield	Skalista Tarcza	5:1	2	5 m	1 r	Terra	wall HP = MA	blocks LoS
27	quicksand	Ruchome Piaski	5:3	3	10 m	2 r	Terra, Perfodio, Vinculum	-	half movement
28	earthquake	Trzęsienie Ziemi	4:6	5	10 m	3 r	Terra, Potentia, Perditio	-	Unieruchomiony+Powalony, Nieprzytomny on 3 fails
29	gravel-armor	Żwirowa Zbroja	4:1	2	self	2 r	Tutamen, Terra	-	+1 armor, –½ speed
30	stone-trap	Skalista Pułapka	5:4	4	15 m	1 min	Terra, Vinculum, Telum	MA (trigger)	-

4.6 Magia Sakralna - Modlitwy Powszechne

#	id	Name	T:Y	Mana	Range	Duration	Damage	Notes
31	sanctify	Uświęcenie	4:1	2	self	1 r	weapon → magical	-
32	holy-steel	Święta Stal	5:1	3	self	1 r	weapon +1 magical	–1 die Reflex on hit
33	healing-touch	Leczący Dotyk	3:1	1	touch	inst.	heal MA or Devotion	-
34	protection-prayer	Modlitwa o Opiekę	5:1	1	self	1 r	-	+1 die vs spells/curses
35	divine-justice	Boska Sprawiedliwość	6:1	2	10 m	inst.	½ MA/Dev (+1d6 vs heretic)	-

4.7 Magia Sakralna - Bóg-Jahwe-Jedyny

#	id	Name	T:Y	Mana	Race req	Damage	Notes
36	david-blade	Ostrze Dawida	5:1	3	Anioł	weapon S+1 magical slash	-
37	last-judgement	Sąd Ostateczny	6:3	6	-	3× MA/Dev	Instant death heretic/demon/undead if Devotion ≥ Soul
38	solomon-wisdom	Mądrość Salomona	5:1	2	-	-	+1 die all Mind tests, 1 h
39	fanatic-sacrifice	Fanatyczne Poświęcenie	6:2	5	Człowiek	reciprocal ×2	Przerażenie aura
40	cure-disease	Uzdrowienie Chorych	5:2	4	-	-	Removes 1 disease/poison

4.8 Magia Sakralna - Zeus-Jowisz

#	id	Name	T:Y	Mana	Damage	Status
41	thunderbolt	Grom z Nieba	5:4	4	2× MA/Dev AoE	Ogłuszony
42	chain-lightning	Błyskawice Łańcuchowe	5:3	3	MA/Dev per chain	-
43	aegis	Egida	6:1	2	-	+1 armor, attacks –1 step
44	static-discharge	Wyładowanie Elektrostatyczne	4:4	4	½ MA/Dev	Przewrócony
45	king-presence	Obecność Króla Bogów	6:3	6	-	Authority aura

4.9 Magia Sakralna - Demeter-Ceres

#	id	Name	T:Y	Mana	Notes	nonCombatOnly
46	harvest-blessing	Błogosławieństwo Zasiewów	6:2	3	+20% yields	✓
47	earth-power	Moc Ziemi	5:2	4	regen on natural soil	-
48	accelerated-harvest	Przyspieszone Żniwa	6:4	5	rzucanie 1 h	✓
49	season-cycle	Cykl Pór Roku	6:6	6	microclimate	-
50	mother-wrath	Gniew Matki Ziemi	4:4	4	½ MA/Dev per move	-

4.10 Magia Sakralna - Artemida-Diana

#	id	Name	T:Y	Mana	Damage	Notes
51	bridge	Pomost	6:1	4	-	partial beast morph
52	awakening	Przebudzenie	5:3	5	-	full beast morph
53	insect-swarm	Chmara Insektów	4:5	4	-	–1 armor, –50% speed
54	divine-aim	Boska Celność	4:3	2	-	+3 dice ranged
55	divine-spear	Boska Włócznia	5:2	3	MA/Dev ignore armor	+1d3/extra success

4.11 Magia Sakralna - Hekate (hybrid sacred/witch)

Special: cast as either sacred (zeal cost) or witch (mana + symbols).

#	id	Name	T:Y	Mana	Symbols	Notes
56	magic-amplify	Wzmocnienie Magii	4:3	4	Praecantatio, Auram	+4 dice Magical Abilities
57	mana-theft	Kradzież Many	6:3	5	Praecantatio, Telum, Auram	+2 mana / +1 max cost
58	magic-acceleration	Magiczne Przyspieszenie	5:2	3	Praecantatio, Potentia	+1 Zapał
59	hekate-curse	Klątwa Hekate	6:2	6	Praecantatio, Vitium, Vinculum	–1 die MA + Przerażony
60	arcane-knowledge	Tajemne Poznanie	5:1	2	Cognitio	+1 die magic/theology lore

4.12 Magia Sakralna - Afrodyta-Wenus

#	id	Name	T:Y	Mana	Notes	nonCombatOnly
61	innocence-charm	Urok Niewinności	5:1	2	+2 Y to attack	-
62	heart-bond	Więź Serc	6:3	4	empathic link	✓
63	passion-flame	Płomień Namiętności	6:1	5	+2 die empathy/persuasion	-
64	goddess-beauty	Piękno Bogini	5:5	6	+3 die persuasion	-
65	harmony-ray	Promień Harmonii	5:4	5	suppress conflict	-

4.13 Magia Sakralna - Amor-Eros

#	id	Name	T:Y	Mana	Status	nonCombatOnly
66	cupid-arrow	Strzała Kupidyna	4:3	3	Zauroczony	-
67	heart-longing	Tęsknota Serca	5:1	2	obsession	✓
68	senses-desire	Pożądanie Zmysłów	3:5	5	+5 die romantic	-
69	destiny-thread	Nić Przeznaczenia	(none)	6	bond (Soul save)	✓
70	desire-arrow	Strzała Pożądania	5:2	4	Zauroczony if dmg > Soul	-

4.14 Magia Alchemii Transmutacji

#	id	Name	T:Y	Mana	Notes
71	fools-gold	Złoto Głupców	6:2	3	item appears as gold
72	detect-changes	Wykrycie Zmian	5:S	1	GM-set difficulty; no overcast
73	magic-resistance	Magiczna Odporność	5:1	2	immunity to chosen status
74	lead-transmute	Przemiana w Ołów	5:2	3	–2 dice melee/ranged AoE
75	magnetism	Magnetyzm	5:1	5	metal items expelled

4.15 Magia Iluzji

#	id	Name	T:Y	Mana	Symbols	Notes
76	invisibility	Niewidzialność	5:2	5	Aer, Tenebrae	-
77	mirror-image	Zwierciadlany Wizerunek	5:1	3	Sensus, Vitium, Illusio	duplicate ≤20 m
78	mind-maze	Labirynt Umysłu	4:2	2	Cognitio, Alienis	concentration check or lose action
79	magic-shackles	Magiczne Kajdany	4:2	3	Vinculum, Cognitio	Unieruchomiony + no casting
80	dream-veil	Woal Snów	6:3	4	Somnium, Illusio, Cognitio	½ MA ignore armor + Przerażony

4.16 Nekromancja

#	id	Name	T:Y	Mana	Notes
81	ethereal-guide	Eteryczny Przewodnik	6:1	2	summons mindless ghost
82	negation	Negacja	5:3	5	anti-magic fog AoE
83	animate-skeleton	Ożywienie Szkieletu	6:2	3	mindless skeleton
84	dispersal	Rozsypanie	5:1	4	2× MA, destroy weak undead
85	speak-with-dead	Rozmawianie ze Zmarłymi	5:1	3	1 question / soul

4.17 Superzaklęcia (Księga Magii VI)

All flagged: isSuperspell: true, requires Mistrzostwo talent.

#	id	Name	T:Y	Mana	Mastery	Cast time	Group?	Notes
86	super-destruction	Destrukcja	6:20	20	any	1 h	-	50 m blast, 5 yr taint
87	super-disintegration	Prawdziwa Dezintegracja	6:15	15	any	10 min	-	irreversible
88	super-doom	Zagłada	6:30	30	any	3 h	≥3 mages	co-casters die
89	super-magical-plague	Magiczna Plaga	6:25	25	botany/witch/brewing/abyss	30 min	-	2d3 years
90	super-aegis	Aegis	6:30	30	any	1 h	-	24 h dome
91	super-landscape	Transmutacja Krajobrazu	6:20	20	transmutation/earth/botany	30 min	-	5 km² permanent
92	super-portal	Bramy Wymiarów	6:25	25	botany/witch/brewing/abyss	2 h	-	2d6 years
93	super-reanimation	Reanimacja	6:15	15	sacred	3 h	-	participants age 1d6

4.18 Magia Szkarłatu (Chwała Szkarłatnemu Kultowi)

#	id	Name	T:Y	Mana	Range	Damage	Notes
C1	crimson-bolt	Szkarłatny Pocisk	6:1	1	15 m	MA, ignore armor	-
C2	crimson-flames	Szkarłatne Płomienie	6:1	4	10 m	shield-eater	-
C3	crimson-justice	Szkarłatna Sprawiedliwość	5:3	5	10 m	2× MA + AoE	Ogłuszony+Oślepiony
C4	crimson-curse	Klątwa Szkarłatu	5:2	4	10 m	reactive	Nieprzytomny on cast
C5	crimson-dagger	Szkarłatny Sztylet	5:2	3	self	weapon +2 magical	trigger: free spell after kill (1/round)
CS	crimson-requiem	Requiem	6:25	25	100 m	3d6 ignore all	Superspell; 7 days "crimson dreams"

4.19 Magia Otchłani (Klątwa Otchłani)

#	id	Name	T:Y	Mana	Range	Damage	Notes
A1	primal-orb	Pierwotna Kula	5:2	2	15 m	MA + 1d6	chaotic targeting
A2	mysterious-stream	Tajemniczy Strumień	6:2	3	10 m	MA	+1d3 Insanity
A3	forbidden-ward	Zakazana Osłona	5:3	4	self	reflect	reactive, 1 use
A4	neutralization	Neutralizacja	6:3	5	20 m	Mind/turn	blocks casting
A5	summon-abyss	Przywołanie Istoty z Otchłani	6:n	6	5 m	-	variable Y per creature: 2/4/6/10

4.20 Magia Krwi (Arcanum Sanguinis) - TBD

Status: Per user clarification, Magia Krwi will get its own spell list in a future content release. Reserve castingMode: 'blood' and bloodCost: number field on SpellData. No spells to catalog yet.

---

5. SpellData Model - Gap Analysis

Reference: .src/foundry-system/src/data/item-spell.ts

5.1 Current schema (v0.1.2)

{
  circle, school, discipline,
  castingMode: 'standard' | 'sacred' | 'witch',
  difficulty: { threshold, successes },
  components: { verbal, somatic, material },
  castingTime, range, targets, duration,
  manaCost, overcasting,
  complexityLevel, // witch only
  description, higherCircles
}

5.2 Missing fields → required additions

New field	Type	Default	Why
deity	string	''	Sacred spells gated by deity (8 entries; '' = common)
castingMode (extend)	add 'blood' to enum	-	Magia Krwi gets its own mode
bloodCost	number	0	Magia Krwi resource cost
components.symbols	string[]	[]	Witch / Hekate spell symbol list (replaces only-counting complexityLevel)
requirements.race	string[]	[]	e.g. ['angel'], ['human']
requirements.talent	string[]	[]	e.g. ['mastery'] for superspells
requirements.discipline	string[]	[]	e.g. ['transmutation', 'botany'] for Magiczna Plaga
isSuperspell	boolean	false	Distinguishes superzaklęcia
requiresGroupCast	boolean	false	True for Zagłada
minCasters	number	1	3 for Zagłada
nonCombatOnly	boolean	false	Tęsknota Serca, Więź Serc, Demeter rituals, etc.
areaOfEffect	SchemaField	-	{ shape: 'point'|'square'|'rectangle'|'cone'|'sphere'|'line', x: number, y: number, unit: 'm' }
damageBase	string	''	Formula reference: 'magicalAbilities', 'magicalAbilities/2', 'magicalAbilities*2', '1d6+magicalAbilities', etc. Parsed at cast time.
damageType	string	'magical'	'magical' | 'physical-magical' | 'pure' (ignores armor)
ignoresArmor	boolean	false	Crimson, Ether Pierce, Divine Spear
statusEffects	string[]	[]	Conditions a spell may apply ('stunned', 'prone', 'frightened', 'charmed', etc.)
saveAttribute	string	''	If non-empty, target rolls <attribute>+<saveSkill> to resist
saveSkill	string	''	e.g. 'reflex', 'determination'
overcastOptions	array of {description, manaPerStep}	[]	Replace free-text overcasting with structured list (legacy field kept for migration)
sourceBook	string	''	'kg-magii' / 'crimson-cult' / 'abyss-curse' / 'arcanum-sanguinis' / 'core-rules'
castingTimeRounds	number	0	0 = action; >0 = rounds (used for combat enforcement of long casts)
castingTimeMinutes	number	0	For non-combat scaling (rituals, superspells)
triggers	array of {event, effect}	[]	Reactive effects: {event:'killWithWeapon', effect:'freeCrimsonSpell'}, {event:'targetCastsSpell', effect:'forceUnconscious'}
variableSuccesses	array of {label, successes}	[]	For Przywołanie Istoty z Otchłani: [{label:'Tajemny Krab', successes:2}, ...]

5.3 Backward compatibility / migration

• Keep legacy fields (overcasting, complexityLevel, targets) populated for one minor version.
• Migration script in src/migrations/0.2.0.ts:
  • Move complexityLevel count → ensure components.symbols.length matches; if symbols empty, leave count.
  • Best-effort parse of targets string → areaOfEffect (regex: /(\d+)\s*[×x]\s*(\d+)/, /promień\s+(\d+)/).
  • overcasting text → seed first entry of overcastOptions[0].description.

---

6. Casting Logic - Gap Analysis

Reference: .src/foundry-system/src/logic/spell-cast.ts

6.1 Pre-cast validation gates (new)

function validateCast(actor, spell, opts) -> ValidationResult
  - resourceCheck (mana / zeal / blood / mana+zeal for Hekate)
  - raceCheck (spell.requirements.race)
  - talentCheck (spell.requirements.talent - items on actor)
  - disciplineCheck (spell.requirements.discipline - at least one match)
  - deityCheck (sacred + non-empty deity → actor must be devoted to that deity)
  - groupCastCheck (warn if requiresGroupCast and only 1 caster targeted)
  - inCombatCheck for nonCombatOnly → block (warn-only override flag in opts)
  - inCombatCheck for isSuperspell → WARN (do not block); bypass via opts.bypassSuperspellWarning
  - witchSymbolCheck (count <= ceil(magic/2)) - already exists

6.2 New CastOptions

interface CastOptions {
  manaSpent?: number;
  zealSpent?: number;            // for Hekate when cast as sacred
  bloodSpent?: number;           // for blood mode
  hekateMode?: 'sacred' | 'witch'; // Hekate spell dispatch
  bypassSuperspellWarning?: boolean;  // Downcasting talent, NPC quick-cast abilities
  bypassNonCombatBlock?: boolean;     // GM override
  groupCasters?: string[];       // actor IDs of co-casters
  speaker?: ChatMessage.SpeakerData;
}

6.3 New casting modes

castBlood(actor, spell, opts)

• Resource: deduct spell.bloodCost from actor.system.attributes.blood.value (new attribute on character data - or HP if blood pool not added)
• Pool: magic + magicalAbilities (placeholder; final formula TBD when Blood Magic spells released)
• No overcast for v1; revisit when content lands

castSacred extension

• If spell has complexityLevel > 0 (Hekate), allow opts.hekateMode === 'witch' to dispatch to castWitch instead

6.4 Damage rolling integration

Currently castSpell only rolls the TS test - no damage application. Add:

function rollSpellDamage(actor, spell): Roll
  - parse spell.damageBase formula
  - resolve tokens: 'magicalAbilities', 'devotion', 'soul', '1d6', etc.
  - return Roll for chat output

Display side-by-side in chat card: TS result | Damage formula result | Status effects to apply | Save target attribute+skill.

6.5 Status effect auto-apply

When TS test succeeds AND target has lower successes on save:

• For each entry in spell.statusEffects[], apply ActiveEffect via Foundry condition system
• Hook into conditions.ts (already exists for combat status tracking)

6.6 Trigger registration

For reactive spells (Szkarłatny Sztylet, Klątwa Szkarłatu):

• On successful cast → register a hook on actor (flag.hbm-rpg-v3.triggers[])
• Hook fires on matching combat event ('killWithWeapon' → free spell prompt; 'targetCastsSpell' → opposed Determination test)
• Triggers expire on duration end or single use

6.7 Variable success summons

For Przywołanie Istoty z Otchłani:

• Cast UI prompts user to pick which entity (Tajemny Krab / Strażnik / Czempion / Simulacrum)
• Required successes loaded from spell.variableSuccesses[selected].successes
• Pass into TS test as required override

6.8 Group cast orchestration

For Zagłada:

• Cast UI lists co-casters from opts.groupCasters[]
• Each contributes their dice pool (sum)
• On success, all participants take "death" status (per spell description)
• Pre-cast warning chat card requires GM confirm

---

7. Constants Module - Required Additions

Reference: .src/foundry-system/src/constants.ts

export const CASTING_MODES = ['standard', 'sacred', 'witch', 'blood'] as const;

export const SPELL_SCHOOLS = [
  'general', 'elements', 'sacred', 'illusion', 'necromancy',
  'transmutation', 'brewing', 'botany', 'artifacts', 'golemancy',
  'runes', 'sources', 'witch',
  'blood', 'crimson', 'abyssAspects', 'abyssPrimal', 'wildWitch',
] as const;

export const SACRED_DEITIES = [
  'common', 'jahwe', 'zeus', 'demeter', 'artemis',
  'hekate', 'aphrodite', 'eros',
] as const;

/**
 * Witch magic symbols. EXTENSIBLE - new content may add more.
 * Used for autocomplete only; spell.components.symbols accepts arbitrary strings.
 */
export const WITCH_SYMBOLS: readonly string[] = Object.freeze([
  'Potentia', 'Tutamen', 'Lux', 'Motus', 'Iter', 'Vacuos', 'Vitium',
  'Praecantatio', 'Aer', 'Aqua', 'Gelum', 'Ignis', 'Terra',
  'Cognitio', 'Alienis', 'Illusio', 'Somnium', 'Tenebrae', 'Auram',
  'Vinculum', 'Telum', 'Sensus', 'Perditio', 'Perfodio', 'Sano',
  'Volatus', 'Tempestas',
]);

export const SOURCE_BOOKS = [
  'core-rules', 'magic-book', 'arcanum-sanguinis',
  'crimson-cult', 'abyss-curse', 'humanity-guide',
  'bestiary', 'gold-steel-magic',
] as const;

export const AOE_SHAPES = ['point', 'square', 'rectangle', 'cone', 'sphere', 'line'] as const;

export const CONDITIONS = [
  'stunned', 'prone', 'frightened', 'charmed', 'unconscious',
  'restrained', 'blinded', 'poisoned', 'burning',
  'authority', 'dominated', 'concentrating',
] as const;

---

8. Character Sheet Spell Tab - Enhancement Spec

Reference: .src/foundry-system/src/sheets/character-sheet.ts

8.1 Grouping & filtering

• Replace flat spells list with grouped structure in _prepareContext:

  spellsByDiscipline: Record<DisciplineId, Item[]>
  spellsBySchool: Record<School, Item[]>
  superspells: Item[]  // separate list pulled out
  

• Sidebar filter UI: by school, castingMode, deity, circle, search-by-name
• Persist filter in tabGroups['spellsFilter']

8.2 Per-row badges

Badge	Source field
Casting mode icon	system.castingMode (4 icons: ✦ standard, ✟ sacred, ✶ witch, ❤ blood)
Source book pip	system.sourceBook (color-coded)
Deity label	system.deity (only for sacred)
Superspell star	system.isSuperspell === true
Race-locked badge	system.requirements.race.length > 0

8.3 Cast button enhancements

• Greyed out + tooltip when validateCast() fails (race/talent/discipline missing)
• Yellow warning icon when superspell + actor in combat
• Click → opens enhanced cast dialog with mana/zeal/blood field, hekate-mode toggle, group-caster picker, bypass-warning checkbox (GM only)

8.4 Resource displays

Add to stats tab header:

• Mana / max-per-spell / per-round (existing)
• Blood pool (new, only if any spell with castingMode: 'blood' is owned)
• Zeal (existing)

---

9. Spell Item Sheet - Enhancement Spec

Reference: .src/foundry-system/templates/item/spell.hbs

9.1 Add fieldsets (in order)

1. Identyfikacja - name, sourceBook (select), school (select), discipline (select), deity (conditional select if school=sacred), circle
2. Tryb rzucania - castingMode (select), bloodCost (if blood), components.symbols (tag picker against WITCH_SYMBOLS, free-text allowed)
3. Trudność - threshold, successes, manaCost, castingTimeRounds, castingTimeMinutes
4. Zasięg & Obszar - range, areaOfEffect (shape select + x/y inputs), targets (kept as freetext fallback)
5. Czas trwania - duration, nonCombatOnly (checkbox)
6. Obrażenia - damageBase (text), damageType (select), ignoresArmor (checkbox)
7. Efekty statusu - statusEffects (multi-select against CONDITIONS), saveAttribute + saveSkill
8. Wymagania - requirements.race (multi-select), .talent (multi-select), .discipline (multi-select)
9. Flagi - isSuperspell, requiresGroupCast, minCasters
10. Nadczarowanie - repeatable list of overcastOptions[] (description + manaPerStep)
11. Wyzwalacze (Triggery) - repeatable list of triggers[] (event select + effect text)
12. Warianty sukcesu - repeatable list of variableSuccesses[] (label + successes)
13. Opis & komponenty fabularne - description (HTML), higherCircles (HTML, deprecated → migrated to overcastOptions)

9.2 Conditional rendering (Handlebars)

• Deity select: only if system.school === 'sacred'
• Blood cost: only if system.castingMode === 'blood'
• Witch complexity / symbols: if castingMode === 'witch' OR Hekate sacred spell
• Variable successes: only if non-empty (collapsible)
• Triggers: only if non-empty (collapsible)

---

10. Compendium Pack Plan

10.1 System-bundled packs

Pack id	Type	Contents	Estimated count
hbm-rpg-v3.spells-general	Item	Magia Ogólna	10
hbm-rpg-v3.spells-elements	Item	Żywioły × 4	20
hbm-rpg-v3.spells-sacred	Item	Sacred + 7 deities	35
hbm-rpg-v3.spells-academic	Item	Transmutacja, Iluzja, Nekromancja	15
hbm-rpg-v3.spells-superspells	Item	Superzaklęcia	8
hbm-rpg-v3.spells-crimson	Item	Magia Szkarłatu	6
hbm-rpg-v3.spells-abyss	Item	Magia Otchłani	5
hbm-rpg-v3.spells-blood	Item	Magia Krwi (placeholder)	0 (TBD)
hbm-rpg-v3.talents	Item	All talents	TBD
hbm-rpg-v3.disciplines	Item	All discipline definitions	~15
hbm-rpg-v3.classes	Item	Class progression items	5
hbm-rpg-v3.races	Item	Race definitions	8
hbm-rpg-v3.gear-baseline	Item	Core weapons/armor/equipment	TBD
hbm-rpg-v3.elixirs-baseline	Item	Aneks C eliksiry	TBD
hbm-rpg-v3.actors-bestiary	Actor	Bestiariusz creatures	TBD
hbm-rpg-v3.actors-npcs	Actor	Bestiariusz NPCs	TBD

10.2 Generation pipeline

• Source: structured YAML/JSON in .src/foundry-system/data/spells/*.yaml (one file per discipline)
• Build script (scripts/build-packs.ts) reads YAML, validates against Zod schema mirroring SpellData, writes LevelDB pack files into packs/
• Run as part of bun run package

---

11. Implementation Phases

Phase A - Data model expansion (no UI changes)

1. Extend SpellData schema with all fields from §5.2
2. Add constants from §7
3. Write migration 0.2.0 for existing world data
4. Bump version → 0.2.0

Phase B - Compendium seeding

1. Build YAML source files for all ~93 spells (§4) under .src/foundry-system/data/spells/
2. Implement scripts/build-packs.ts
3. Wire bun run package to generate packs

Phase C - Casting logic upgrade

1. validateCast() pre-cast gates (§6.1)
2. New castBlood() mode + extend CastOptions (§6.2-6.3)
3. rollSpellDamage() + chat card overhaul (§6.4)
4. Status effect auto-apply hook (§6.5)
5. Trigger registration system (§6.6)
6. Variable success / group cast UI (§6.7-6.8)

Phase D - Sheet UX

1. Spell item sheet enhancements (§9)
2. Character sheet spell tab grouping/filtering (§8)
3. Cast dialog overhaul

Phase E - Quality & polish

1. Localization keys (Polish + English) for all new fields
2. CSS for badges, condition icons, source book pips
3. Foundry compendium browser metadata (image, system tags)

---

Appendix A - Spell Field Naming Convention

• IDs: kebab-case matching slug-of-name (English-translated where idiomatic, Polish-derived otherwise)
• All UI labels: localized via lang/pl.json & lang/en.json keys under HBM.spell.*
• Damage formulas: lowercase camelCase tokens (magicalAbilities, devotion, soul, mind, body, magic)
• Conditions: lowercase singular (stunned, prone, frightened)

Appendix B - Outstanding Questions

1. Blood Pool resource: should actor.system.attributes.blood be a new dedicated pool, or does Magia Krwi simply consume HP? Pending Arcanum Sanguinis spell list.
2. Hekate "hybrid" persistence: when cast as witch, should the spell consume zeal or mana? Currently planned: choose one per cast via opts.hekateMode.
3. Detect Changes (detect-changes): spell explicitly says "no overcast"; need a noOvercast: boolean flag, OR encode in overcastOptions: [] (empty = no overcast).
4. Status effect saves: which spells require an opposed Magia/Zdolności Magiczne test vs target's saveAttribute + saveSkill, and which auto-apply on TS success? Each spell needs explicit annotation in compendium YAML.
5. Dzika Wiedźmia Magia spells: not enumerated separately in books; mostly variants of standard witch magic with chaos overlay. Defer to dedicated content drop.