octoturge/homebrew-magic-rpg
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5c7f72f0d5bbab9ea8f366675864d4e4e50cb7ed
homebrew-magic-rpg/_drafts/module-system-split.md
T
Octoturge a4f8941fca chore: initialize homebrew-magic-rpg monorepo 
Consolidates the HbM: RPG project (formerly the loose hbm-books
working folder) into a single repo. ObsidianNotes, foundry-lore, and
foundry-system are wired in as submodules pointing at their existing
Gitea repos. Loose tooling scripts are organized under tools/,
obsolete/one-off scripts (fix_vault.py, generate_mocs.py, debug-*.ts,
write_file_helper.py) and _books/ (superseded by ObsidianNotes) are
excluded via .gitignore rather than deleted. foundryvtt-admin is
excluded pending its own separate repo.
2026-08-17 21:28:50 +02:00

20 KiB
Raw Blame History

Module / System Content Split - HbM RPG v3

Status: Draft / Planning Document Audience: Developer (next iteration of hbm-rpg-v3 Foundry system + companion lore module) Purpose: Classify every chapter of every rulebook as SYSTEM (mechanics → Foundry system code/compendia), MODULE (lore → separate companion module), or BOTH (split content). Drives the package architecture for the v0.3+ release.

Table of Contents

  1. Classification Legend
  2. Per-Book Classification
    1. Podręcznik Gry
    2. Księga Magii
    3. Arcanum Sanguinis
    4. Chwała Szkarłatnemu Kultowi
    5. Klątwa Otchłani
    6. Przewodnik Ludzkości po Magicznym Świecie
    7. Bestiariusz
    8. Złoto Stal i Magia
  3. Aggregate Summary
  4. Proposed Package Architecture
  5. Compendium Pack Plan (System)
  6. Module Pack Plan (Lore)
  7. Cross-References & Dependencies
  8. Migration & Build Pipeline

1. Classification Legend

Tag Meaning Destination
[SYSTEM] Pure mechanics: rules, tables, stat blocks, character options hbm-rpg-v3 system package + bundled compendium packs
[MODULE] Pure lore/setting/fiction with no mechanical impact hbm-rpg-v3-lore companion module (JournalEntry packs)
[BOTH] Mixed content - split per section: stats stay in system, narrative moves to module, cross-linked Both packages, with bidirectional @UUID links

Decision rule:

If removing the content would require renumbering rules, breaking character creation, or invalidating compendium entries → SYSTEM. If removing the content would only reduce flavor/setting depth → MODULE. If both apply → BOTH with explicit split points.

2. Per-Book Classification

2.1 Podręcznik Gry

Chapter Class Destination Notes
Wstęp MODULE Lore module → JournalEntry "Świat HbM - Wprowadzenie" Narrative about the Awakening
I - Klasy (lata 1–5) SYSTEM Compendium: classes Year-by-year unlocks
II - Tworzenie Postaci (rasy, dziedziny) SYSTEM Compendia: races, disciplines Race traits, discipline picks
III - Atrybuty i Umiejętności SYSTEM Hard-coded in actor-character.ts + constants.ts 4 attributes, 24 skills
IV - Talenty SYSTEM Compendium: talents All baseline talents
V - Walka i Magia SYSTEM logic/combat.ts, logic/spell-cast.ts Initiative, actions, tests
VI - Odpoczywanie i Leczenie SYSTEM New logic/rest.ts Short/long rest mechanics
VII - Religia BOTH Stats → disciplines/sacred, deity entries; Lore → module 7 deities
Aneks A - Stany Postaci SYSTEM logic/conditions.ts (already exists) Status effects
Aneks B - Podstawowe Zaklęcia SYSTEM Compendium: spells-general Superseded by Księga Magii - keep as reference variants
Aneks C - Podstawowe Eliksiry SYSTEM Compendium: elixirs-baseline Eliksir Zdrowia + others
Aneks D - Cechy Broni SYSTEM constants.ts weapon traits "Eksperymentalny" etc.

Verdict: ~90% SYSTEM. Only the foreword and parts of Religia (deity narratives) move to MODULE.

2.2 Księga Magii

Chapter Class Destination Notes
Wstęp MODULE JournalEntry "Filozofia Magii" Philosophical narrative
I - Dziedziny Magii SYSTEM Compendium: disciplines Discipline definitions
II - Teoria Rzucania Zaklęć SYSTEM Hard-coded in spell-cast.ts + GM rules journal Overcast, Symbolika, Variety
III - Warzenie Eliksirów SYSTEM Compendium: elixirs + new logic/brewing.ts Tolerance, brewing checks
IV - Artefakty SYSTEM Compendium: artifacts Stat blocks with upgrades
V - Lista Zaklęć SYSTEM Compendia: spells-* (multiple packs by discipline) All ~85 spells
VI - Superzaklęcia SYSTEM Compendium: spells-superspells 8 superspells
VII - Tworzenie Zaklęć SYSTEM GM journal + future macro tooling Creation rules + tables
VIII - Dzika Magia Dzikich Wiedźm BOTH Sabaty/hierarchia → MODULE; chaos rules → SYSTEM

Verdict: ~95% SYSTEM. Only the foreword and witch coven lore are MODULE.

2.3 Arcanum Sanguinis

Chapter Class Destination Notes
Wstęp MODULE JournalEntry "Marginalia Magii Krwi" Narrative about marginalization
I - Magia Krwi a Otchłań MODULE JournalEntry chapter Worldview, Inquisition relations
II - Bóg Krwi / Robert Zaryn MODULE JournalEntries + Actor doc (Robert Zaryn) NPC & deity lore
III - Teoria Magii Krwi SYSTEM New logic/blood-magic.ts + new actor field attributes.blood Blood Points, Self-Harm, Life Steal
IV - Talenty SYSTEM Compendium: talents-blood Szacunek do Życia → Rytualista / Pojedynkowicz trees

Verdict: 50/50 split - clean separation between organisational/divine lore and Blood Magic mechanics.

2.4 Chwała Szkarłatnemu Kultowi

Chapter Class Destination Notes
Wstęp MODULE JournalEntry Mysterious organisation tone
I - Pogłoski MODULE JournalEntry In-world rumors
II - Struktura MODULE JournalEntry + Actor folder structure Hierarchy: Rycerz→Pretor, Kultysta→Arcykapłan
III - Lokalizacje MODULE JournalEntries with embedded Scenes Obeliski, Domena Szkarłatu, Twierdze
IV - Zaklęcia SYSTEM Compendium: spells-crimson 5 + 1 superspell
V - Artefakty BOTH Stats → artifacts-crimson; History → MODULE Cross-link via @UUID

Verdict: 50/50.

2.5 Klątwa Otchłani

Chapter Class Destination Notes
Wstęp MODULE JournalEntry Nature of the Abyss
I - Otchłań i Przebudzenie MODULE JournalEntry History: pre-modern traces, 2023
II - Potężniejsza Magia SYSTEM logic/abyss-magic.ts Aspects vs Primal mechanics
III - Kara za nieudolność SYSTEM Roll table compendium: roll-tables-abyss Failure penalty table
IV - Talenty SYSTEM Compendium: talents-abyss Swobodny Przepływ, Dar Otchłani, Metamagia
V - Dary Otchłani SYSTEM Roll table d100 in roll-tables-abyss Boons/banes
VI - Personifikacje Otchłani BOTH Stats → actors-abyss; Lore → MODULE Nil/Mundus/Tempus
VII - Istoty Otchłani SYSTEM Compendium: actors-abyss Mistrz Losu stat block
VIII - Choroby Psychiczne SYSTEM New conditions-mental set in conditions.ts Insanity mechanics
IX - Zaklęcia SYSTEM Compendium: spells-abyss 5 spells
X - Artefakty SYSTEM Compendium: artifacts-abyss Miotacz Entropii
Aneks A - Kara Mistrza Losu SYSTEM Roll table Penalty table

Verdict: 60% SYSTEM / 40% MODULE.

2.6 Przewodnik Ludzkości po Magicznym Świecie

Chapter Class Destination Notes
Wstęp MODULE JournalEntry
I - Teoria Jednego Wszechświata MODULE JournalEntry Cosmology, philosophy
II - Planety i Frakcje MODULE JournalEntries + Scenes Earth, Hiondirs, Xivell, Eldrakar, Malferian
III - Życie na Sol-3 MODULE JournalEntry Magical education, Inquisition
IV - Cywilizacja Hiondirs-4 MODULE JournalEntry + Scene
V - Cywilizacja Xivell MODULE JournalEntry Royal lineage, Crimson Cult genesis
VI - Cywilizacja Eldrakar MODULE JournalEntry + Scene
VII - Cywilizacja Malferian MODULE JournalEntry Consortium houses, rituals
VIII - Federacja Sol-3 MODULE JournalEntry + Actor folder (Special Forces X, Gaja) Syllia Orirel etc.
IX - Święta Inkwizycja MODULE JournalEntry + Actor folder Genesis, structure, ops
X - Zaświaty MODULE JournalEntry Hades, Niebo, Piekło hierarchies
Aneks A–D MODULE JournalEntries (in-world documents) Federation reports, Narcyza interview, Inquisitor notes

Verdict: ~98% MODULE. Race information is the only borderline - but actual race stats live in Podręcznik Gry, so this book stays purely lore.

2.7 Bestiariusz

Chapter Class Destination Notes
I - Przeciwnicy SYSTEM Compendium: actors-bestiary All hostile creature stat blocks
II - Inne Postacie (NPC) BOTH Stats → actors-npcs; personality → MODULE Cross-link via @UUID
III - Talenty SYSTEM Compendium: talents-special Wspomnienie Wspaniałego Świata, Pierwszy Patriarcha

Verdict: ~80% SYSTEM. NPC personality blurbs and faction histories are the MODULE pieces.

2.8 Złoto Stal i Magia

Chapter Class Destination Notes
Wstęp MODULE JournalEntry Post-Awakening economic revolution
I - Geopolityka MODULE JournalEntry USA/Chiny/Rosja/Europa post-2023
II - Ekonomia Magicznego Świata MODULE JournalEntry Sectors, dwarf monopolies
III - Handel Międzyrasowy MODULE JournalEntry + Scene (trade routes)
IV - Polityka na Ziemi MODULE JournalEntry Dwarf lobby, Inquisition vs trade
V - Bank Krasnoludzki MODULE JournalEntry + Actor (org)
VI - Waluty i Systemy Płatnicze BOTH Currency table → roll-tables-economy; cultural notes → MODULE
VII - Czarny Rynek i Kontrabanda BOTH Risk/negotiation rules → SYSTEM; catalog → MODULE
VIII - Krasnoludy BOTH Race traits → existing races compendium; culture → MODULE
IX - Mechanika Handlu dla PG SYSTEM New logic/trade.ts + journal Founding company, transactions, smuggling
Aneks A - Nowe Talenty SYSTEM Compendium: talents-trade Zmysł Kamienia, Kupiecka Intuicja, Złoty Nos
Aneks B - Przedmioty i Towary SYSTEM Compendium: gear-trade + price tables Dwarven items, price lists

Verdict: 40% SYSTEM / 60% MODULE.

3. Aggregate Summary

Book SYSTEM % MODULE % Primary destination
Podręcznik Gry ~90 ~10 System (core)
Księga Magii ~95 ~5 System (core)
Arcanum Sanguinis ~50 ~50 Both
Chwała Szkarłatnemu Kultowi ~50 ~50 Both
Klątwa Otchłani ~60 ~40 Both
Przewodnik Ludzkości ~2 ~98 Module
Bestiariusz ~80 ~20 System
Złoto Stal i Magia ~40 ~60 Both

4. Proposed Package Architecture

hbm-rpg-v3/                       (Foundry SYSTEM package)
├── system.json
├── src/                          (TypeScript)
│   ├── data/                     (TypeDataModel for actors/items)
│   ├── logic/                    (combat, spell-cast, brewing, blood-magic, abyss-magic, trade, rest, conditions)
│   ├── sheets/                   (character, npc, item sheets)
│   └── dice/                     (TS roll system)
├── packs/                        (LevelDB compendia - see §5)
└── data/                         (YAML source for pack generation)

hbm-rpg-v3-lore/                  (Foundry MODULE package - separate repo / sub-folder)
├── module.json                   (depends on hbm-rpg-v3 system)
├── packs/                        (JournalEntry packs - see §6)
├── data/                         (Markdown source for journal generation)
└── assets/                       (images, maps, scene backgrounds)

Why split?

  1. System is mandatory, module is optional → groups running custom settings can use the system without the canonical lore.
  2. Update cadence differs: rules patches (system) vs. lore expansions (module).
  3. Distribution rights: lore content may have separate licensing considerations.
  4. Clean dependency graph: module can @UUID link into system compendia (talents, spells, actors), but system never depends on module.

5. Compendium Pack Plan (System)

5.1 Items

Pack id Item type Source Est. count
hbm-rpg-v3.spells-general spell Księga Magii I-V 10
hbm-rpg-v3.spells-elements spell Księga Magii V 20
hbm-rpg-v3.spells-sacred spell Księga Magii V 35
hbm-rpg-v3.spells-academic spell Transmutacja, Iluzja, Nekromancja 15
hbm-rpg-v3.spells-superspells spell Księga Magii VI 8
hbm-rpg-v3.spells-crimson spell Chwała Szkarłatnemu Kultowi 6
hbm-rpg-v3.spells-abyss spell Klątwa Otchłani 5
hbm-rpg-v3.spells-blood spell Arcanum Sanguinis TBD
hbm-rpg-v3.talents-core talent Podręcznik Gry IV TBD
hbm-rpg-v3.talents-blood talent Arcanum Sanguinis IV TBD
hbm-rpg-v3.talents-abyss talent Klątwa Otchłani IV TBD
hbm-rpg-v3.talents-trade talent Złoto Stal i Magia A TBD
hbm-rpg-v3.talents-special talent Bestiariusz III TBD
hbm-rpg-v3.disciplines discipline Księga Magii I ~15
hbm-rpg-v3.classes class Podręcznik Gry I 5
hbm-rpg-v3.races race Podręcznik Gry II + Złoto Stal i Magia VIII 8
hbm-rpg-v3.gear-baseline gear Podręcznik Gry TBD
hbm-rpg-v3.gear-trade gear Złoto Stal i Magia B TBD
hbm-rpg-v3.elixirs-baseline gear Podręcznik Gry C TBD
hbm-rpg-v3.elixirs gear Księga Magii III TBD
hbm-rpg-v3.artifacts gear Księga Magii IV TBD
hbm-rpg-v3.artifacts-crimson gear Chwała Szkarłatnemu Kultowi V TBD
hbm-rpg-v3.artifacts-abyss gear Klątwa Otchłani X TBD

5.2 Actors

Pack id Actor type Source Est. count
hbm-rpg-v3.actors-bestiary npc Bestiariusz I TBD
hbm-rpg-v3.actors-npcs npc Bestiariusz II TBD
hbm-rpg-v3.actors-abyss npc Klątwa Otchłani VI–VII TBD

5.3 Roll tables

Pack id Source
hbm-rpg-v3.roll-tables-abyss Klątwa Otchłani III, V, Aneks A
hbm-rpg-v3.roll-tables-economy Złoto Stal i Magia VI–VII

6. Module Pack Plan (Lore)

6.1 JournalEntry packs

Pack id Source
hbm-rpg-v3-lore.world-overview Podręcznik Gry Wstęp + Przewodnik I
hbm-rpg-v3-lore.deities Podręcznik Gry VII (lore parts) + Klątwa Otchłani VI
hbm-rpg-v3-lore.universe Przewodnik II–VII (planets & civilizations)
hbm-rpg-v3-lore.sol3-society Przewodnik III, VIII, IX
hbm-rpg-v3-lore.afterlife Przewodnik X
hbm-rpg-v3-lore.documents Przewodnik Aneksy A–D
hbm-rpg-v3-lore.blood-magic-history Arcanum Sanguinis Wstęp + I + II
hbm-rpg-v3-lore.crimson-cult Chwała Szkarłatnemu Kultowi Wstęp, I, II, III, V (history)
hbm-rpg-v3-lore.abyss Klątwa Otchłani Wstęp, I, VI (lore)
hbm-rpg-v3-lore.witch-covens Księga Magii VIII (lore parts)
hbm-rpg-v3-lore.economy Złoto Stal i Magia I–VIII (narrative parts)
hbm-rpg-v3-lore.npc-personalities Bestiariusz II (personality parts)

6.2 Scene packs (asset-bundled)

Pack id Source
hbm-rpg-v3-lore.scenes-locations Locations folder + Chwała III + Przewodnik IV–VII

6.3 Macro packs (optional)

  • Quick-roll macros for common GM rolls
  • Lore lookup macros (search across journal compendia)

7. Cross-References & Dependencies

7.1 Dependency direction

hbm-rpg-v3-lore  ──depends-on──▶  hbm-rpg-v3  (system)
                                       │
                                       └─▶ no upward dependency

module.json declaration:

{
  "id": "hbm-rpg-v3-lore",
  "title": "HbM RPG v3 - Lore Companion",
  "system": "hbm-rpg-v3",
  "compatibility": { "minimum": "13", "verified": "13" },
  "relationships": {
    "systems": [{ "id": "hbm-rpg-v3", "type": "system", "compatibility": { "minimum": "0.3.0" } }]
  }
}

7.2 Cross-link patterns

  • Lore JournalEntry references SYSTEM compendium item: @UUID[Compendium.hbm-rpg-v3.spells-crimson.{id}]{Szkarłatny Pocisk}
  • SYSTEM item description references lore JournalEntry: @UUID[Compendium.hbm-rpg-v3-lore.crimson-cult.JournalEntry.{id}.JournalEntryPage.{pageId}]{Szkarłatny Kult}
  • NPC actor (SYSTEM) → personality journal (MODULE) via biography @UUID

7.3 Stable IDs

All compendium documents must have stable IDs (slug-derived) to prevent cross-link breakage on rebuilds:

  • Spells: spell-{slug} (e.g. spell-magic-missile)
  • Talents: talent-{slug}
  • NPCs: npc-{slug}
  • Lore: lore-{book}-{chapter}-{slug}

8. Migration & Build Pipeline

8.1 Source-of-truth strategy

Each domain has a machine-readable source file under .src/foundry-system/data/ (system) or .src/foundry-lore/data/ (module). The Foundry pack files (packs/*.db or LevelDB folders) are build artifacts, not source.

Source format Domain
YAML spells, talents, gear, races, classes, disciplines
YAML + Markdown NPCs / actors (YAML stat block + Markdown description)
Markdown JournalEntry pages
JSON RollTables

8.2 Build scripts

Script Output
scripts/build-spell-packs.ts All spells-* LevelDB packs
scripts/build-actor-packs.ts All actors-* LevelDB packs
scripts/build-journal-packs.ts All lore.* packs (in module repo)
scripts/build-roll-tables.ts All roll-tables-* packs
scripts/build-all.ts Wraps all above; called by bun run package

8.3 Migration scripts

When SpellData / ActorData schemas change, write a src/migrations/{version}.ts that runs on world load (Foundry Hooks.once('ready')).

8.4 Validation

  • Zod (or Foundry's own DataModel) schema validation in build scripts → fail build on invalid spell/actor entry
  • Cross-reference linter: ensures every @UUID[...] in lore points to a real system compendium entry

Appendix A - Implementation Order

  1. v0.2.0 - System foundation
    • Expand SpellData schema (per foundry-spell-reference.md §5)
    • Build spells-* packs from YAML sources
    • Migration 0.1 → 0.2 for existing world spells
  2. v0.3.0 - Compendium completeness
    • All talent / discipline / race / class packs built
    • Bestiariusz actors imported
  3. v0.4.0 - Mechanics expansion
    • logic/blood-magic.ts, logic/abyss-magic.ts, logic/brewing.ts, logic/rest.ts, logic/trade.ts
    • Status conditions expanded (mental illnesses)
  4. v0.5.0 - Lore module 1.0
    • Companion module hbm-rpg-v3-lore first release
    • Przewodnik Ludzkości fully ported
    • Cross-links established
  5. v1.0.0 - Polish & full content
    • All 8 books represented
    • English localization complete
    • Compendium browser metadata, icons, art

Appendix B - Outstanding Questions

  1. Module repo location: separate Git repo or sub-folder under .src/? Recommendation: separate folder .src/foundry-lore/ for unified editing, separate module.json package output.
  2. Asset licensing: scene images, NPC portraits - which assets can ship in the module vs. be GM-supplied?
  3. Polish-only vs bilingual: should lore JournalEntries ship Polish-only initially, with English translation pack later?
  4. Adventure content (adventures/ folder): adventure scenarios are neither system nor module content - recommend a third package hbm-rpg-v3-adventures per published adventure.
  5. Foundry Module Marketplace listing: needs cover art, description, screenshots before module submission.
Reference in New Issue View Git Blame Copy Permalink