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
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:
parent
883aabe0a5
commit
cae9da04c8
178
README.md
178
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 <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
|
||||
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue