hbm-foundry-system/README.md

Foundry VTT System: Homebrew Magic RPG v3

A custom Foundry Virtual Tabletop v13 system implementing Homebrew Magic: Role Playing Game v3 — a Polish tabletop RPG with a d6 success-pool (TS — Trudność:Sukcesy) dice mechanic.

Internal identifiers are English; user-facing labels are Polish (canonical) with English fallback. The locale files in lang/ hold the translations.

Status

v1.0.0 — first production release. Full magic and resource model from books I–VIII, 152 compendium docs across 11 packs, automated build pipeline that parses _books/*.md directly. See CHANGELOG.md for the full history.

A companion lore module (foundry-lore) ships JournalEntry compendia for narrative chapters.

What's implemented

• Document types — Actor: character, npc. Item: spell, gear, ability, class, race, discipline, talent.
• TS d6 dice pool roller (HbmTSRoll) — 1 auto-fail, 6 auto-success, configurable Threshold (T) and required Successes (Y), plus T-step / Y-step modifiers driven by Active Effects.
• Derived stats — health.max = 3 × (body + mind + soul), zeal.max = ceil(soul/2), initiative pool, mana table lookup (Magic Power Level 0–X), blood pool (body + soul), elixir tolerance cap (body + 1), insanity counter.
• 4-layer damage model — Magical Armor (with runic counter) → Magical Shield → Physical Armor (DR + condition) → Health. Apply Damage dialog with bypass flags; auto-applies Oszołomiony on heavy HP loss.
• Combat hooks — Mana resets each round; Zeal +1 each turn; turns auto-skipped for Nieprzytomny / Obezwładniony; Podpalony ticks 1 environmental damage; Umierający prompts a Death Save.
• Spell-cast workflow — validateCast() gates on resources / race / talent / discipline / deity / group / inCombat / superspell / witch-symbol; dispatcher routes to standard / Sacred / Witch / Blood / Hekate hybrid; rollSpellDamage() parses formula tokens; reactive triggers (killWithWeapon, targetCastsSpell, damageTaken, turnStart).
• Cast dialog — mana / zeal / blood inputs, group-caster picker, Hekate toggle, GM bypass checkboxes (superspell, non-combat block), inline validation feedback.
• Mechanics modules (game.hbm.*) — bloodMagic (Self-Harm, Life Steal, talent integration), abyssMagic (Aspects vs Primal, Mistrz Losu penalty, Dary Otchłani, insanity gain), brewing (TS test + tolerance counter), rest (short / long), trade (founding company workflow, transactions, smuggling).
• Status conditions (Active Effects) — 15 physical conditions (Aneks A) plus 5 mental conditions from Klątwa Otchłani VIII (paranoja, fobia, depresja, mania, schizofrenia).
• Sheets — ApplicationV2 + Handlebars for every document type. Character sheet: short-rest / long-rest header buttons, conditional resource cards (blood pool, elixir tolerance, insanity), spells tab grouped by school with badges (★ super, ⛧ group, ☮ noncombat, 🔒 race-lock) and source-book pip.
• Compendia (11 packs, 152 docs) — spells-general, spells-elements, spells-sacred, spells-academic, spells-superspells, spells-crimson (93 spells); talents, talents-npc (34 talents); races (5), disciplines, disciplines-forbidden (20). Each pack carries flags.hbm-rpg-v3.{category, sourceBook} for compendium-browser; packFolders group them in the sidebar.
• Race / Class linking — drag a Race or Class item onto a Character to auto-link system.details.raceId / system.details.classIds[year]. Feeds the Advancement panel (attribute / skill points available).
• Migration runner — src/migrations/ upgrades v0.2.x worlds (complexityLevel → components.symbols.length, targets regex → areaOfEffect, overcasting text → overcastOptions[0].description).

Project layout

src/foundry-system/
├── system.json          # Foundry system manifest (includes documentTypes since v14)
├── LICENSE.txt
├── lang/                # pl.json (canonical) + en.json
├── styles/hbm.css
├── templates/
│   ├── actor/           # character.hbs, npc.hbs
│   ├── item/            # per-type partials + dispatcher
│   └── chat/ts-roll.hbs
├── scripts/package.ts   # zip builder
├── src/
│   ├── hbm.ts           # entry point
│   ├── constants.ts
│   ├── data/            # DataModels
│   ├── dice/            # HbmTSRoll + macros
│   ├── sheets/
│   └── logic/           # combat, conditions, spell-cast
└── package.json + vite.config.ts + tsconfig.json

Build & deploy

This system is built with Vite + TypeScript. Foundry runs in Docker on a remote host, so the workflow is build → package → drop the zip into the container's Data/systems/.

cd src/foundry-system
bun install               # one-time
bun run build             # compile TS to dist/
bun run build:packs       # parse _books/ → dist/packs/ (LevelDB)
bun run package           # → hbm-rpg-v3-v1.0.0.zip

To deploy to a Docker-hosted Foundry instance:

# Option A: extract into the volume-mounted Data folder
unzip -o hbm-rpg-v3-v0.3.x.zip -d /path/to/foundry-data/Data/systems/

# Option B: docker cp into a running container
docker cp hbm-rpg-v3-v0.3.x.zip foundry:/data/Data/systems/
docker exec foundry sh -c "cd /data/Data/systems && unzip -o hbm-rpg-v3-v0.3.x.zip"
docker restart foundry

Then in Foundry: Game Systems → Install System → (system appears once it's in Data/systems/) → create a world.

Mechanic notes

TS dice pool (d6)

Roll N d6  →  count successes  →  succeed if successes ≥ Y
  1            → forced failure (always)
  6            → forced success (always)
  >= T (2..6) → success

Default T = 4, Y = 1. The roll dialog accepts both per-roll for harder tasks (GM may demand Y ≥ 2).

Magic Power Level table

Level	Dice	Max/spell	Mana/round
0	6	10	20
I	4	6	12
II	4	5	10
III	3	5	7
IV	3	4	8
V	3	4	6
VI	2	3	6
VII	2	3	4
VIII	1	2	3
IX	1	1	2
X	0	1	1

Out of scope (v1.0.0)

Deferred to follow-up versions:

• Gear / artifact / actor / roll-table compendia — source books lack stat-block data.
• Adventures package (hbm-rpg-v3-adventures).
• Character creation wizard, advancement automation (PD spending).
• Macro packs.
• Compendium browser premium-module integration (basic flag metadata only).

Reference material

Game rules and content live in sibling folders of this repo:

• ../../_books/ — synced PDFs of the rulebooks (read-only)
• ../../spells/, ../../creatures/, ../../items/ — structured content
• ../../rules/, ../../revisions/ — current and proposed mechanics

Useful links

• Foundry VTT System Development
• Foundry API v13

License

All Rights Reserved — see LICENSE.txt.