129 lines
7.4 KiB
Markdown
129 lines
7.4 KiB
Markdown
# Agent guide: Ravenous Roll20 sheet
|
|
|
|
## Purpose and current state
|
|
|
|
This repository builds a French Roll20 character sheet for Ravenous from the
|
|
`ravenous_typst` rulebook submodule. The sheet is an early working version:
|
|
generation and structural tests pass, but its interactions still need validation
|
|
in a real Roll20 game. Treat the book data and rules as authoritative; do not
|
|
infer a game rule from a field label or an existing formula without checking it.
|
|
|
|
## Where to work
|
|
|
|
| Path | Role |
|
|
| --- | --- |
|
|
| `src/ravenous.html` | Hand maintained sheet markup, roll template, and sheet worker JavaScript. `{{...}}` uppercase markers are filled at build time. |
|
|
| `src/ravenous.css` | Hand maintained styling template for Roll20's current CSE mode. Theme variables are filled at build time. |
|
|
| `src/translation.json`, `src/sheet.json` | Translation metadata and Roll20 manifest. |
|
|
| `tools/build.py` | Reads book data, converts a subset of Typst markup, generates skill rows and technique choices, and writes artifacts. |
|
|
| `ravenous_typst/` | Git submodule containing the book and source game data. Avoid editing it as part of a sheet-only change. |
|
|
| `tests/test_build.py` | Build and generated-output assertions; mostly structural checks. |
|
|
| `roll20_mod/ravenous_import_name.js` | Optional Mod proof of concept: create a character from a JSON name. It is installed separately from the sheet. |
|
|
| `roll20_mod/ravenous_character_io.js` | GM Mod script for versioned JSON character export/import via private handouts. |
|
|
| `tools/export_monsters.py` | Converts the pinned SQLite monster database to that JSON format. |
|
|
| `build/` | Generated output for Roll20. Do not hand edit it; it is currently ignored by Git. |
|
|
|
|
The main inputs are `ravenous_typst/data/src/character_sheet.yaml`,
|
|
`ravenous_typst/data/src/schools/*.tsv`, `ravenous_typst/data/src/origines/*.yaml`, glossary YAML, and
|
|
`ravenous_typst/data/config/build.yaml`. Only school tiers below
|
|
`build.max_tier_exclusive` are imported. At the pinned submodule revision the
|
|
build reports 126 sheet skills and 275 techniques across 11 schools. The 15
|
|
resistance definitions remain in the book data but are represented by the
|
|
dedicated resistance fields instead of being duplicated in the Skills tab.
|
|
The monster database is a nested submodule at
|
|
`ravenous_typst/data/src/db/monsters.db`; initialize it with
|
|
`git -C ravenous_typst submodule update --init data/src/db` before converter tests.
|
|
|
|
## Build and verify
|
|
|
|
From the repository root, with Python 3.11+ and `uv` available:
|
|
|
|
```sh
|
|
git submodule update --init --recursive
|
|
./scripts/build.sh
|
|
uv run python -m unittest discover -s tests -v
|
|
node tests/test_worker.mjs
|
|
node tests/test_mod_import.mjs
|
|
node tests/test_character_io.mjs
|
|
./scripts/build.sh --check
|
|
```
|
|
|
|
If `uv` cannot write its default cache in a restricted environment, set
|
|
`UV_CACHE_DIR` to a writable temporary directory for these commands. The build
|
|
writes `build/ravenous.html`, `ravenous.css`, `translation.json`, `sheet.json`,
|
|
and `build-info.json`. `--check` compares those files with freshly generated
|
|
content; it does not exercise Roll20 behavior. The tests themselves rebuild
|
|
`build/`. The Node tests run the generated worker against a small mock of
|
|
Roll20's attribute API. `./scripts/test-worker-container.sh` runs those tests
|
|
in a network-isolated Podman container after the build, if Podman is available.
|
|
Neither path simulates Roll20's dice parser, browser, or chat.
|
|
|
|
Use `./scripts/build.sh --list-themes` to inspect book themes and
|
|
`./scripts/build.sh --theme steel --output-dir build-steel` to export a separate
|
|
Roll20 bundle. Palettes are read from the submodule's `setup/theme/themes.typ`;
|
|
the default is selected by `data/config/build.yaml`.
|
|
|
|
For a Roll20 test, copy the generated HTML, CSS, and translation JSON into a
|
|
custom sheet or sheet sandbox. Use current CSE mode with Legacy Sanitization
|
|
disabled. The editor preview is insufficient for sheet workers and repeating
|
|
sections. Test with two characters and a targeted defender token when checking
|
|
the attack card's **Défendre** and **Subir** actions.
|
|
|
|
## How the sheet works
|
|
|
|
- Seven tabs cover character statistics, skills, combat, health, consumables,
|
|
schools, and powers. Built-in skills, technique choices, and origins are generated from book data;
|
|
custom skills, attacks, protections, locations, consumables, effects, and
|
|
acquired techniques, and powers are repeating sections.
|
|
- Sheet workers calculate characteristic totals, derived statistics, skill
|
|
totals, selected damage resistance, and active protection summaries. Most
|
|
persistent values are Roll20 attributes. Keep attribute names and generated
|
|
option values stable when possible because existing characters store them.
|
|
- Skill and attack rolls use the `ravenous` roll template and `startRoll` /
|
|
`finishRoll`. Attack follow-ups prompt for a defender token. The attack
|
|
result cache (`attackRolls`) lives only in worker memory, so test follow-up
|
|
behavior after reopening a sheet as well as immediately after rolling.
|
|
- **Subir** displays calculated DMG and AB after checked resistances and
|
|
protection. It does not subtract HP or armor integrity from attributes.
|
|
Consumables, temporary effects, and techniques display chat cards; they do
|
|
not apply costs or mechanical effects automatically.
|
|
- Techniques are added one at a time from the generated selector. The importer
|
|
translates only the Typst syntax handled by `translate_typst`; inspect newly
|
|
imported descriptions when the book data or macros change.
|
|
- Origin powers are generated from YAML and added in batches by stage for the
|
|
selected origin. Existing imported and custom powers remain if the origin
|
|
changes. Source keys prevent duplicate import.
|
|
- Character JSON export preserves sheet attributes, abilities, bio, GM notes,
|
|
and access lists. Monster conversion maps compatible fields and keeps all
|
|
raw database rows in GM notes; monster attack dice and damage need GM review.
|
|
|
|
## Change workflow
|
|
|
|
1. Locate the governing rule or source data in the pinned submodule. For sheet
|
|
presentation and interaction changes, edit `src/`; for import behavior,
|
|
edit `tools/build.py`. Do not edit generated files directly.
|
|
2. Preserve existing Roll20 attribute names and repeating section names unless
|
|
a migration is planned. Check all related worker events, roll buttons, and
|
|
templates when changing a field.
|
|
3. Build, run the tests, and run `--check`. Add focused assertions for changed
|
|
generation logic, but do not treat string presence as proof of working
|
|
Roll20 interaction.
|
|
4. For interactive changes, manually exercise the affected flow in Roll20:
|
|
open and reopen the sheet, change inputs, add and reorder repeating rows,
|
|
roll from chat, and check results on a targeted defender token. Record what
|
|
was actually tested and what could not be tested.
|
|
|
|
## Known gaps and priorities
|
|
|
|
The Python tests confirm artifact shape and selected generated strings. The
|
|
Node tests execute worker callbacks against a minimal mock, but do not parse
|
|
Roll20 macros or render chat. Follow the concrete smoke test and remaining
|
|
work in [TASKS.md](TASKS.md). Verify formulas against the current rulebook,
|
|
especially defense and damage edge cases. Document decisions about whether HP,
|
|
integrity, technique costs, and temporary effects should remain manual before
|
|
automating them.
|
|
|
|
The README covers installation, update, and deployment details. Jenkins builds,
|
|
tests, archives, and deploys only designated branches; avoid changing its
|
|
deployment behavior as part of an ordinary sheet fix.
|