The official version of Ravenous, now in Typst
Go to file
Dandaedre 883aabe0a5
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
Readme
2026-08-25 20:16:02 +02:00
chapters Readme 2026-08-25 20:16:02 +02:00
data Readme 2026-08-25 20:16:02 +02:00
docs Readme 2026-08-25 20:16:02 +02:00
images Display name & did 2026-08-25 00:56:18 +02:00
setup Craft cookbook 2026-08-25 19:58:21 +02:00
test Display name & did 2026-08-25 00:56:18 +02:00
tools Bestiairy formatting 2026-08-22 18:16:25 +02:00
.gitignore Renames the glossaries 2026-08-24 01:09:44 +02:00
.gitmodules
…
.ignore Master screen, einer & art 2026-08-24 00:27:12 +02:00
Jenkinsfile Craft cookbook 2026-08-25 19:12:09 +02:00
README.md Readme 2026-08-25 20:16:02 +02:00
balance_report.typ
…
balance_report_master.typ Map & Resists 2026-08-25 07:23:54 +02:00
changelog.typ Add a changelog & live tests 2026-08-25 01:54:59 +02:00
cookbook.typ First draft for recipies 2026-08-25 18:46:10 +02:00
main.typ FAQ 2026-08-24 22:33:07 +02:00
master_handbook.typ Map & Resists 2026-08-25 07:23:54 +02:00
master_screen.typ Master screen 2026-08-23 23:41:46 +02:00
player_handbook.typ FAQ 2026-08-24 22:33:07 +02:00

README.md

Ravenous

Ravenous is a French-language tabletop role-playing game about Hunters: mortals marked by the blood of Calamities who stand between humanity and monstrous threats. This repository contains the Typst sources and assets used to produce its rulebook.

Installing Typst

If you have a Rust toolchain installed, you can install:

  • The latest released Typst version with:

    cargo install --locked typst-cli
    
  • A development version with:

    cargo install --git https://github.com/typst/typst --locked typst-cli
    

Editor tooling

Tinymist provides Typst language server features such as diagnostics and completion. Install its latest development version with Cargo:

cargo install --git https://github.com/Myriad-Dreamin/tinymist --locked tinymist-cli

Typstyle formats Typst source files. Install it from crates.io with:

cargo install typstyle --locked

Make sure Cargo's binary directory is available on your PATH, so the editor can find the tinymist and typstyle executables.

Helix

Add the following to your global Helix languages.toml or to .helix/languages.toml inside this repository for a project-local setup:

[[language]]
name = "typst"
auto-format = true
language-servers = ["tinymist"]
formatter = { command = "typstyle", args = [] }

[language-server.tinymist]
command = "tinymist"

This enables Tinymist diagnostics and completion, and runs Typstyle whenever 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:

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:

typst compile --input preset=player-handbook player_handbook.typ player-handbook.pdf

Select any theme from setup/theme/themes.typ with the theme input:

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):

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:

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:

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:

typst watch main.typ main.pdf

The CI build also generates Git metadata before compiling. To reproduce that locally:

./tools/pseudo_toolchain.sh
typst compile main.typ main.pdf

Building the master screen

Build the four-panel portrait reference screen with:

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:

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:

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:

build:
  creature_id: "3"

To test trusted database markup and glossary evaluation one creature at a time:

tools/check_creature_eval.sh

Pass an ID to check only one entry:

tools/check_creature_eval.sh 3

Building the master creature balance report

Build the standalone creature analysis report with:

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:

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.

Project layout

  • main.typ is the rulebook entry point.
  • balance_report.typ is the automatically generated balance-analysis report.
  • chapters/ contains the book's content.
  • setup/ contains shared styles, models, and macros.
  • images/ and data/ contain supporting assets and game data.

Writing chapters

Import the chapter-authoring prelude to access the shared macros and styles:

#import "/setup/prelude.typ": *

See the Typst usage guide for the available helpers, section references, examples, and guidance on when to use a more specific import.

Contributing and conduct

Contributions, corrections, and suggestions are welcome. Keep changes focused, make sure the book still compiles, and explain non-obvious decisions in your pull request or commit message.

Be respectful and constructive. Harassment, discrimination, personal attacks, and other hostile behaviour are not acceptable in project discussions or contributions.