ravenous_typst/README.md

89 lines
3.0 KiB
Markdown

# Ravenous Typst
## 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
`Ravenous_master_balance_report_build.pdf`. The stable deployed filename is
`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.