ravenous_roll20/AGENTS.md

7.3 KiB

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 141 skills and 275 techniques across 11 schools. 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:

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. 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.