diff --git a/README.md b/README.md index 77c5dd1..62fe67b 100644 --- a/README.md +++ b/README.md @@ -62,184 +62,26 @@ Helix formats the document or saves it with automatic formatting enabled. ## Building the book -Clone the repository with its submodules, then compile the main book and the -balance report: +Clone the repository with its submodules, then compile the main book: ```sh git clone --recurse-submodules cd ravenous_typst typst compile main.typ main.pdf -typst compile balance_report.typ balance_report.pdf ``` -All shared build settings live in `data/config/build.yaml`. Build the dedicated -player-facing edition with the predefined chapter exclusions using: +[Read the advanced main-book build guide](docs/builds/main/README.md) for themes, +presets, content selection, persistent configuration, live rebuilding, and CI +reproduction. -```sh -typst compile --input preset=player-handbook player_handbook.typ player-handbook.pdf -``` +## Building other documents -Select any theme from `setup/theme/themes.typ` with the `theme` input: +Each standalone document has its own build guide: -```sh -typst compile --input preset=player-handbook --input theme=steel \ - player_handbook.typ player-handbook-steel.pdf -``` - -Sections can be toggled with comma-separated chapter IDs. `chapters` is an -allow-list; `disabled_chapters` removes entries from it (or from the default -set when no allow-list is supplied): - -```sh -typst compile --input preset=player-handbook \ - --input chapters=title,origins,schools,rules \ - --input disabled_chapters=rules \ - player_handbook.typ player-handbook-classes.pdf -``` - -`origin-lore` and `origin-artwork` control the lore quotations and images -inside `origins`. The player preset hides `origin-lore` by default. For example: - -```sh -typst compile --input disabled_chapters=origin-artwork \ - player_handbook.typ player-handbook-without-origin-art.pdf -``` - -When using the `chapters` allow-list, include `origin-artwork` alongside -`origins` to retain images. The preset can also be combined with independent -origin and school selectors: - -```sh -typst compile \ - --input preset=player-handbook \ - --input origin=dragon_1 \ - --input school=artilleur \ - player_handbook.typ dragon-1-artilleur-handbook.pdf -``` - -`origin` and `school` default to an empty string, which includes every entry. -Origins identify individual YAML variants such as `dragon_1`, `dragon_2`, or -`guivre_1`. They can also be set persistently under `build` in the YAML. Invalid -identifiers fail compilation with an explicit error. - -Edit `build.disabled_chapters` for permanent project-specific exclusions, or -add another entry under `presets` for a reusable edition. Chapter IDs are the -names passed to `chapter-enabled` in `main.typ`. - -For live rebuilding while editing, use: - -```sh -typst watch main.typ main.pdf -``` - -The CI build also generates Git metadata before compiling. To reproduce that -locally: - -```sh -./tools/pseudo_toolchain.sh -typst compile main.typ main.pdf -``` - -## Building the master screen - -Build the four-panel portrait reference screen with: - -```sh -typst compile master_screen.typ master_screen.pdf -``` - -Its summaries are declared beside the rules they describe and imported by both -the standalone PDF and the `master-screen` chapter of the complete book. -Disable that book chapter through the normal `disabled_chapters` configuration. -The player-handbook preset excludes it by default. CI encrypts and publishes the -standalone screen under the same policy as the other master-facing artifacts. - -## Building the master handbook - -Build the complete master handbook: - -```sh -typst compile master_handbook.typ master_handbook.pdf -``` - -To work on one creature without rendering every other bestiary entry, pass its -database ID through `creature_id`: - -```sh -typst compile --input creature_id=3 master_handbook.typ creature-3.pdf -``` - -The master handbook automatically enables its master-only glossary entries, so -no preset argument is required. An unknown ID, or an ID not visible to the -master, produces an explicit error. - -For a persistent local selection, set `build.creature_id` in -`data/config/build.yaml`. Keep it as an empty string to render every -master-visible creature: - -```yaml -build: - creature_id: "3" -``` - -To test trusted database markup and glossary evaluation one creature at a time: - -```sh -tools/check_creature_eval.sh -``` - -Pass an ID to check only one entry: - -```sh -tools/check_creature_eval.sh 3 -``` - -## Building the master creature balance report - -Build the standalone creature analysis report with: - -```sh -typst compile balance_report_master.typ balance_report_master.pdf -``` - -Its sections are enabled in `data/config/balance_report_master.yaml`. The -initial report covers common creature profiles, rewards, and regional -difficulty; later creature-specific analyses can be added independently. - -In CI, this report is handled like the master handbook: Jenkins compiles a -temporary plaintext PDF, protects it with `qpdf` and `MASTER_PASSWORD`, deletes -the plaintext intermediate, then archives and publishes only -`Report/Ravenous_master_balance_report_build.pdf`. The stable deployed path is -`Report/Ravenous_master_balance_report.pdf`. - -The advanced creature-by-creature section reproduces the combat model from -`rust_base/monsters` directly in Typst. Configure it in -`data/config/balance_report_master.yaml`: - -```yaml -advanced_balance: - creature_ids: [] # Every master-visible creature - show_extra: true # Include alternate player stances - show_balanced: true # Keep rows already matching their targets -``` - -`creature_ids` is only a narrowing filter over the master-visible collection. -It never overrides `show_to_master`: requesting a hidden or unknown ID cannot -make that creature appear in the report. Advanced tables use Typst's natural -page flow and repeat their headers automatically; only creature boundaries -force a new page. - -The calculations and presentation are kept in separate modules, so later -metrics can reuse the same normalized defense and attack records without -changing the report tables. - -The advanced section also includes an independent heuristic attack diagnosis. -It compares success depth and defensive thresholds within each Difficulty, -measures one- and two-success damage, estimates the chance of producing enough -defensive successes to survive, checks every player stance against an -unmitigated hit, and proposes archetypes such as Thrashing, Defense Check, Tank -Buster, or Nuke. These inferred labels are shown beside—not substituted for—the -attack type declared in the database. +- [Player handbook and cookbook](docs/builds/player/README.md) +- [Master handbook and master screen](docs/builds/master/README.md) +- [Balance reports](docs/builds/reports/README.md) +- [Changelog](docs/builds/changelog/README.md) ## Project layout diff --git a/docs/builds/changelog/README.md b/docs/builds/changelog/README.md new file mode 100644 index 0000000..901cd7f --- /dev/null +++ b/docs/builds/changelog/README.md @@ -0,0 +1,18 @@ +# Building the changelog + +[Back to the project README](../../../README.md) + +Build the standalone changelog with: + +```sh +typst compile changelog.typ changelog.pdf +``` + +Select a theme through the shared `theme` input: + +```sh +typst compile --input theme=steel changelog.typ changelog-steel.pdf +``` + +The changelog content is stored in `data/config/changelog.yaml` and rendered by +`chapters/changelog.typ`. diff --git a/docs/builds/main/README.md b/docs/builds/main/README.md new file mode 100644 index 0000000..ddd46a9 --- /dev/null +++ b/docs/builds/main/README.md @@ -0,0 +1,107 @@ +# Advanced main-book building + +[Back to the project README](../../../README.md) + +The defaults shared by all book builds live in `data/config/build.yaml`. +Command-line `--input` values are useful for one-off builds and override the +corresponding default selectors without modifying that file. + +## Themes + +Select a theme from `setup/theme/themes.typ`: + +```sh +typst compile --input theme=steel main.typ main-steel.pdf +``` + +The default theme is `document.color_scheme` in `data/config/build.yaml`. + +## Presets and chapter selection + +The full preset is used by default. Select another preset with: + +```sh +typst compile --input preset=player-handbook main.typ player-handbook.pdf +``` + +The `chapters` input is a comma-separated allow-list. Only the named sections +are included: + +```sh +typst compile \ + --input chapters=title,origins,schools,crafting \ + main.typ selected-chapters.pdf +``` + +The `disabled_chapters` input is a comma-separated deny-list: + +```sh +typst compile \ + --input disabled_chapters=geography,bestiary,game-master-help \ + main.typ reduced-book.pdf +``` + +When both inputs are present, a chapter must be in the allow-list and absent +from every deny-list. Command-line exclusions are combined with both +`build.disabled_chapters` and the selected preset's exclusions; they do not +replace them. Unknown preset and chapter IDs stop compilation with an explicit +error. The canonical chapter IDs are declared in `setup/build_config.typ` and +used by `main.typ`. + +`origin-lore` and `origin-artwork` are content switches rather than standalone +chapters. Include or exclude them through the same inputs to control quotations +and artwork inside the origins chapter: + +```sh +typst compile \ + --input chapters=title,origins,origin-artwork \ + --input disabled_chapters=origin-lore \ + main.typ origins-only.pdf +``` + +## Origin and school filters + +Build only one origin variant, one school, or both: + +```sh +typst compile \ + --input origin=dragon_1 \ + --input school=artilleur \ + main.typ dragon-artilleur.pdf +``` + +An empty `origin` or `school` value includes every entry. Origin filters use +variant IDs such as `dragon_1`, not family names such as `dragon`. Invalid +selectors fail explicitly instead of silently producing an incomplete book. + +## Persistent configuration + +For settings that should apply to every local build, edit +`data/config/build.yaml`: + +- `document.color_scheme` selects the default theme. +- `build.preset` selects the default preset. +- `build.origin` and `build.school` provide persistent content filters. +- `build.disabled_chapters` adds permanent exclusions. +- `build.max_tier_exclusive` includes data whose tier is lower than this value. +- `build.warnings` controls the project's Typst warning policy. +- `presets` defines reusable editions and their exclusions. + +The `creature_id` setting is specific to master-bestiary diagnostics and is +covered by the [master document guide](../master/README.md). + +## Watching and reproducing CI + +For live rebuilding while editing, use: + +```sh +typst watch main.typ main.pdf +``` + +The CI build also generates Git metadata before compiling. To reproduce that +locally: + +```sh +./tools/pseudo_toolchain.sh +typst compile main.typ main.pdf +``` diff --git a/docs/builds/master/README.md b/docs/builds/master/README.md new file mode 100644 index 0000000..55ac9a1 --- /dev/null +++ b/docs/builds/master/README.md @@ -0,0 +1,56 @@ +# Building the master documents + +[Back to the project README](../../../README.md) + +## Master handbook + +Build the complete master handbook: + +```sh +typst compile master_handbook.typ master_handbook.pdf +``` + +To work on one creature without rendering every bestiary entry, pass its +database ID through `creature_id`: + +```sh +typst compile --input creature_id=3 master_handbook.typ creature-3.pdf +``` + +The master handbook automatically enables its master-only glossary entries. An +unknown ID, or an ID not visible to the master, produces an explicit error. + +For a persistent local selection, set `build.creature_id` in +`data/config/build.yaml`. Keep it empty to render every master-visible creature: + +```yaml +build: + creature_id: "3" +``` + +Test trusted database markup and glossary evaluation for every creature, or +for one selected entry, with: + +```sh +tools/check_creature_eval.sh +tools/check_creature_eval.sh 3 +``` + +## Master screen + +Build the four-panel portrait reference screen with: + +```sh +typst compile master_screen.typ master_screen.pdf +``` + +Its summaries are declared beside the rules they describe and imported by both +the standalone PDF and the `master-screen` chapter of the complete book. +Disable that chapter through the normal `disabled_chapters` configuration. The +player-handbook preset excludes it by default. + +## Protected CI artifacts + +CI compiles plaintext versions of both documents, protects them with `qpdf` +and `MASTER_PASSWORD`, deletes the plaintext intermediates, and publishes only +the encrypted master-facing artifacts. diff --git a/docs/builds/player/README.md b/docs/builds/player/README.md new file mode 100644 index 0000000..38df0c1 --- /dev/null +++ b/docs/builds/player/README.md @@ -0,0 +1,72 @@ +# Building the player documents + +[Back to the project README](../../../README.md) + +## Player handbook + +Build the player-facing edition with its predefined chapter exclusions: + +```sh +typst compile --input preset=player-handbook player_handbook.typ player-handbook.pdf +``` + +Select any theme from `setup/theme/themes.typ` with the `theme` input: + +```sh +typst compile --input preset=player-handbook --input theme=steel \ + player_handbook.typ player-handbook-steel.pdf +``` + +Sections can be toggled with comma-separated chapter IDs. `chapters` is an +allow-list; `disabled_chapters` removes entries from it, or from the default set +when no allow-list is supplied: + +```sh +typst compile --input preset=player-handbook \ + --input chapters=title,origins,schools,rules \ + --input disabled_chapters=rules \ + player_handbook.typ player-handbook-classes.pdf +``` + +`origin-lore` and `origin-artwork` control the lore quotations and images +inside `origins`. The player preset hides `origin-lore` by default: + +```sh +typst compile --input disabled_chapters=origin-artwork \ + player_handbook.typ player-handbook-without-origin-art.pdf +``` + +When using the `chapters` allow-list, include `origin-artwork` alongside +`origins` to retain images. The preset can also be combined with independent +origin and school selectors: + +```sh +typst compile \ + --input preset=player-handbook \ + --input origin=dragon_1 \ + --input school=artilleur \ + player_handbook.typ dragon-1-artilleur-handbook.pdf +``` + +`origin` and `school` default to an empty string, which includes every entry. +Origins identify individual YAML variants such as `dragon_1`, `dragon_2`, or +`guivre_1`. Invalid identifiers fail compilation with an explicit error. + +Persistent settings live in `data/config/build.yaml`. Edit +`build.disabled_chapters`, or add an entry under `presets`, for a reusable +edition. Chapter IDs are the names passed to `chapter-enabled` in `main.typ`. + +## Cookbook + +Build the standalone collection of crafting recipes with the player preset: + +```sh +typst compile --input preset=player-handbook cookbook.typ cookbook.pdf +``` + +The cookbook also accepts the shared `theme` input: + +```sh +typst compile --input preset=player-handbook --input theme=steel \ + cookbook.typ cookbook-steel.pdf +``` diff --git a/docs/builds/reports/README.md b/docs/builds/reports/README.md new file mode 100644 index 0000000..f400609 --- /dev/null +++ b/docs/builds/reports/README.md @@ -0,0 +1,45 @@ +# Building the balance reports + +[Back to the project README](../../../README.md) + +## Player-facing report + +Build the standard balance-analysis report with: + +```sh +typst compile balance_report.typ balance_report.pdf +``` + +Its enabled sections are configured in `data/config/balance_report.yaml`. + +## Master report + +Build the standalone master creature-analysis report with: + +```sh +typst compile balance_report_master.typ balance_report_master.pdf +``` + +Its sections are enabled in `data/config/balance_report_master.yaml`. Configure +the advanced creature-by-creature analysis there: + +```yaml +advanced_balance: + creature_ids: [] # Every master-visible creature + show_extra: true # Include alternate player stances + show_balanced: true # Keep rows already matching their targets +``` + +`creature_ids` only narrows the master-visible collection. It never overrides +`show_to_master`, so requesting a hidden or unknown ID cannot expose it. + +The advanced section reproduces the combat model from `rust_base/monsters`. It +compares success depth and defensive thresholds within each Difficulty, +measures one- and two-success damage, estimates defensive survival chances, +checks each player stance against an unmitigated hit, and proposes attack +archetypes. Inferred labels are shown beside, rather than substituted for, the +attack type declared in the database. + +In CI, the master report is compiled to a temporary plaintext PDF, protected +with `qpdf` and `MASTER_PASSWORD`, and published as the encrypted +`Report/Ravenous_master_balance_report_build.pdf` artifact.