Octoturge
132 lines
7.2 KiB
Markdown
132 lines
7.2 KiB
Markdown
# 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/`](./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`](./CHANGELOG.md) for the full history.
|
||
|
||
A companion lore module ([`foundry-lore`](https://github.com/iwo-strzebonski/hbm-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/`**.
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
# 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/`](../../_books/) - synced PDFs of the rulebooks (read-only)
|
||
- [`../../spells/`](../../spells/), [`../../creatures/`](../../creatures/), [`../../items/`](../../items/) - structured content
|
||
- [`../../rules/`](../../rules/), [`../../revisions/`](../../revisions/) - current and proposed mechanics
|
||
|
||
## Useful links
|
||
|
||
- [Foundry VTT System Development](https://foundryvtt.com/article/system-development/)
|
||
- [Foundry API v13](https://foundryvtt.com/api/)
|
||
|
||
## License
|
||
|
||
All Rights Reserved - see [LICENSE.txt](./LICENSE.txt).
|