ravenous_roll20/AGENTS.md

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.