ravenous_roll20/AGENTS.md

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

Product and architecture documentation

Read FEATURES.md before designing or porting a feature. It is the portable behavioral specification: each feature records its user-visible outcome, invariants, automation boundary, implementation map, and acceptance criteria. Read ARCHITECTURE.md before changing persistent attributes, repeating sections, build inputs/outputs, JSON formats, Mod boundaries, companion sites, CI, or deployment.

These documents are maintained contracts, not retrospective summaries. In the same change as a feature:

  • update FEATURES.md whenever behavior, invariants, status, manual boundaries, or acceptance criteria change;
  • update ARCHITECTURE.md whenever a component boundary, data flow, persistent name, versioned interface, generated artifact, or deployment path changes;
  • update the appropriate README for user-facing installation/usage changes and TASKS.md for dated smoke-test evidence or remaining validation;
  • update a nested component's AGENTS.md when its local constraints change.

Write feature entries so an agent can reproduce the outcome in another repository without copying this repository's layout. Keep project-specific file locations in the implementation map, while making required behavior and acceptance criteria technology-independent. Never document an intended roadmap item as implemented.

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.
roll20_mod/ravenous_craft_import.js Permission-aware versioned import/export for crafted attacks, protections, consumables, and effects.
roll20_mod/ravenous_effects_import.js, roll20_mod/ravenous_shared_effects.js Reusable-effect library exchange and authorized application to a target character.
tools/export_monsters.py Converts the pinned SQLite monster database to that JSON format.
tools/generate_character.py, tools/generate_crafts.py Deterministic interoperability fixtures generated with the sheet bundle.
docs/ Normative JSON schemas, format semantics, and Roll20 macro documentation.
craft_web/, effects_web/ Independently generated static companion sites with nested agent guides and test suites.
FEATURES.md, ARCHITECTURE.md Portable product contract and system design/change-impact reference.
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:

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
node tests/test_craft_import.mjs
node tests/test_effects_import.mjs
node tests/test_shared_effects.mjs
uv run python -m unittest discover -s craft_web/tests -v
uv run python -m unittest discover -s effects_web/tests -v
./scripts/run-python-coverage.sh
./scripts/build.sh --check
uv run python craft_web/tools/build.py --check
uv run python effects_web/tools/build.py --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. The coverage command measures the Python generators, writes only ignored files below coverage/, and enforces the 85% line floor configured in .coveragerc. Badge renderer and temporary-root publication checks are part of the root Python test suite.

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

  • Eight tabs cover character statistics, skills, combat, health, consumables, schools, powers, and effects/turns. 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.
  • Reusable effects are stored separately from active temporary effects. Craft, character, and effect JSON are strict versioned interfaces; keep schemas, producers, Mod validators, fixtures, and documentation synchronized.

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. Update FEATURES.md and, for structural changes, ARCHITECTURE.md. Update user and component documentation affected by the change.
  5. 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.
  6. Commit after every completed small task or user request. Each commit must be a coherent, verified checkpoint containing only the work for that task; do not leave completed requested work uncommitted and do not include unrelated user changes. During a larger request, commit each independently complete increment as soon as it passes its relevant checks.

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.