Sub readmes
Build Successful The Ravenous rulebook, changelog, player books, master handbook, and balance reports were built successfully.
Ravenous/ravenous_typst/pipeline/head This commit looks good Details

This commit is contained in:
Dandaedre 2026-08-25 20:24:25 +02:00
parent 883aabe0a5
commit cae9da04c8
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
6 changed files with 308 additions and 168 deletions

178
README.md
View File

@ -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 <repository-url>
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

View File

@ -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`.

107
docs/builds/main/README.md Normal file
View File

@ -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
```

View File

@ -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.

View File

@ -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
```

View File

@ -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.