ravenous_roll20/ARCHITECTURE.md

20 KiB
Raw Blame History

Ravenous Roll20 architecture

Purpose

This document explains the system boundaries and implementation contracts needed to recreate the project. FEATURES.md is the portable behavioral specification; this file describes how authoritative data becomes deployable assets, how state moves through Roll20, and which names/interfaces must remain compatible.

System context

Pinned ravenous_typst data and rules
              |
              v
      Python build/conversion layer
       /          |            \
      v           v             v
Roll20 bundle  craft site    effects site
      |                           |
      +---------- JSON v1 --------+
                   |
                   v
          Roll20 Mod scripts
                   |
                   v
      characters, attributes, handouts

There are two trust boundaries:

  1. Build-time code trusts the pinned repository inputs but must still fail loudly on unsupported structure or missing required theme/data fields.
  2. Runtime JSON, chat commands, handout content, URL state, and browser storage are untrusted. Runtime importers validate shape, bounds, permissions, and destination before mutating state.

Architectural principles

  • Book data is authoritative. The sheet and companion sites adapt the pinned rulebook; they do not fork rules into generated assets.
  • Generation is deterministic. Same source revision and arguments imply byte-identical output. Check modes detect drift.
  • Templates are maintained; builds are disposable. src/ and generator code are edited. build/ directories are regenerated.
  • Stable storage is an API. Roll20 attributes and repeating-section names are a schema even though they are embedded in HTML.
  • Pure calculation before mutation. Validate/compute first, then write. Character replacement validates the entire payload before removing anything.
  • Least privilege. Sheet workers act only on their character. Mod scripts perform privileged/cross-object operations and recheck player permissions.
  • Manual mechanics are explicit. Assistance must not masquerade as rules automation. HP, armor integrity, costs, quantities, and prose effects remain manual at present.
  • No backend for companion sites. They build to static files and keep user state locally.

Repository map and ownership

Path Architectural responsibility
ravenous_typst/ Pinned upstream rulebook, configuration, themes, glossaries, TSV/YAML data, and nested monster DB. Do not edit for a sheet-only change.
src/ravenous.html Roll20 UI template, persistent attribute declarations, repeating schemas, roll template, and all sheet-worker runtime logic.
src/ravenous.css Roll20 CSE presentation template and generated-theme insertion points.
src/translation.json Roll20 translation payload.
src/sheet.json Roll20 sheet manifest.
tools/build.py Main compiler: source parsing, normalization, limited Typst translation, HTML/CSS/JS generation, theme generation, manifest, and stale check.
scripts/build.sh Reproducible sheet entry point; syncs dependencies and also generates/checks deterministic fixtures.
roll20_mod/ Optional privileged Roll20 API scripts for character, craft, and effect exchange/application.
tools/export_monsters.py SQLite-to-character-contract adapter.
tools/generate_character.py Seeded character-contract fixture generator.
tools/generate_crafts.py Deterministic craft-contract fixture generator.
docs/ Normative JSON schema, format semantics, and Roll20 macro usage.
craft_web/ Independently generated static craft application with its own local architecture/roadmap.
effects_web/ Independently generated static reusable-effects application.
tests/ Main generator/converter tests and Node Roll20 worker/Mod API simulations.
Jenkinsfile Cross-component orchestration, artifact archive, and guarded branch publication.

Nested AGENTS.md files override or refine component rules inside craft_web/ and effects_web/.

Build-time pipeline

Inputs

The main generator consumes:

  • data/src/character_sheet.yaml for sheet-visible skill hierarchy;
  • data/src/schools/*.tsv for techniques;
  • data/src/origines/*.yaml for origins and powers;
  • data/src/glossaries/*.yaml for labels/descriptions;
  • data/config/build.yaml for tier limit, trigrams, and default theme;
  • setup/theme/themes.typ for all palettes;
  • four hand-maintained templates under src/.

The monster converter separately consumes ravenous_typst/data/src/db/monsters.db. That database is a nested submodule.

Normalization and transformation

tools/build.py follows these conceptual stages:

  1. Parse build configuration, glossary labels, themes, sheet data, school TSVs, and origin YAML.
  2. Normalize human names to stable slugs/source keys. Flatten nested skills while retaining category, ancestry, depth, characteristic inheritance, and description.
  3. Translate a deliberately limited Typst subset into French plain text. Known difficulty/reference/weapon/area constructs have explicit renderers.
  4. Infer only conservative structured effect timing from translated French.
  5. Generate escaped HTML fragments, CSS category/theme rules, and line-bounded JavaScript literals.
  6. Replace uppercase {{MARKER}} slots and fail if any remain.
  7. Compute a content hash over the four Roll20 payload files and write build-info.json.

scripts/build.sh then writes deterministic example character and craft JSON beside the bundle. In check mode both the bundle and these examples are compared with fresh generation.

Outputs

The sheet output directory contains:

Artifact Consumer
ravenous.html Roll20 custom sheet HTML/worker/roll template panel
ravenous.css Roll20 custom sheet CSS panel
translation.json Roll20 translation panel
sheet.json Roll20 community-sheet metadata/future submission
build-info.json CI/operator diagnostics and fingerprint
example-character.json Character import test/example
example-craft-forge.json Attack/protection craft test/example
example-craft-alchemy.json Consumable/modifier craft test/example

The two companion generators have separate build/ directories and check modes. They may reuse parsing functions from the main builder, but their output is deployable independently.

Roll20 runtime architecture

Layer 1: declarative sheet state

Roll20 persists fields whose HTML names begin with attr_. Fixed attributes store character identity, characteristics, resources, settings, derived values, health, and worker summaries. Repeating fieldsets create dynamic row schemas.

The stable repeating sections are:

Section Purpose Important row fields
repeating_customskills User-defined skills name, characteristic, rank, temp, total
repeating_attacks Attacks/weapons name, roll controls, damage fields, defense thresholds, notes
repeating_protections Armor/shields active, protection, integrity, dodge/parry, effects
repeating_locations Extra body locations HP/protection/armor fields
repeating_consumables Food/potions/other kind, quantity, prose, timing/reminders
repeating_modifiers Active temporary effects active flag, prose, structured timing/reminders
repeating_sharedeffects Reusable effect library enabled/ID/type, prose, timing/reminders
repeating_techniques Acquired school techniques stable source_key, source metadata, linked effect IDs
repeating_powers Imported/custom origin powers stable source_key, origin/stage/type, linked effect IDs

Attribute and section renames require a migration because existing character objects store literal names such as repeating_attacks_<rowid>_base_damage.

Layer 2: sheet workers

The worker embedded in src/ravenous.html is event-driven JavaScript using the Roll20 sheet-worker API:

  • on subscribes to sheet open, field changes, and action-button clicks;
  • getAttrs and setAttrs read/write the current character;
  • getSectionIDs, generateRowID, and removeRepeatingRow manage repeating sections;
  • startRoll/finishRoll execute asynchronous rolls and publish computed values into the roll template.

Worker responsibilities are grouped conceptually into:

  • tab/theme/secret-roll state;
  • characteristic, derived, and skill recalculation;
  • protection/resistance/location summaries;
  • skill and attack workflows;
  • temporary-effect phase processing;
  • technique/power import, refresh, activation, and effect tracking;
  • reusable-effect lookup and offer-card construction.

Use silent writes for derived outputs to prevent event loops. Recalculate on sheet:opened because Mod imports create raw attributes without executing sheet workers.

The in-memory attackRolls map is deliberately ephemeral. It is keyed by roll ID and helps a defense follow-up calculate damage, but must not be treated as persistent character state.

Layer 3: roll template and chat actions

One ravenous roll template renders skills, attacks, defense, DMG/AB breakdowns, turn reminders, technique/power/consumable cards, and reusable effect offers. The per-character theme name selects generated template CSS.

Roll20 chat queries and targeted attributes are used when data belongs to a defender rather than the open attacker sheet. Template values are sanitized by removing braces before interpolation. Cross-character offer payloads are URI encoded but still considered untrusted by the receiving Mod script.

The mitigation location query transports two nonnegative integers through one numeric option using:

packed = dmg_mitigation * 10000 + ab_protection
dmg_mitigation = floor(packed / 10000)
ab_protection = packed % 10000

Values must remain below the packing factor or the encoding must be versioned and replaced.

Layer 4: Roll20 Mod scripts

Mod scripts execute in the game-level API sandbox and can access characters, tokens, attributes, abilities, players, and handouts. They are installed separately from the character sheet.

Script Responsibility
ravenous_import_name.js Minimal GM-only proof: create a character from JSON name.
ravenous_character_io.js Versioned full-character export, create, and in-place replacement.
ravenous_craft_import.js Strict craft import/export mapped to four repeating sections.
ravenous_effects_import.js Strict reusable-effect library import/export.
ravenous_shared_effects.js Apply a chat-offered reusable effect to an authorized target's active tracker.

Common importer sequence:

  1. recognize the exact API command;
  2. parse flags without evaluating input;
  3. resolve exactly one selected token or an explicit character ID;
  4. verify control of the destination;
  5. resolve direct JSON or a readable handout;
  6. decode Roll20's HTML-wrapped notes;
  7. validate the entire versioned payload and size limits;
  8. create rows or perform a replacement;
  9. whisper a result to the caller without leaking private data.

Player exports create player-readable/controlled handouts and store JSON in Notes. GM exports default to private handouts and GM Notes. Handouts may contain sensitive notes; privacy is part of the contract.

Persistent calculations and data flow

Character and skill totals

Permanent characteristics and manual temporary modifiers produce final characteristics. Derived movement/resource/health maxima intentionally use permanent values plus their own modifiers. Generated and custom skill totals combine the selected final characteristic, rank/base, and temporary modifier. Generated skills also expose a reserved effect-contribution attribute, but the current tracker does not populate it and recalculation keeps it at zero.

Exact game formulas live in the worker and must be verified against the pinned rulebook before reuse. Tests establish current implementation behavior but are not an independent rules authority.

Damage flow

attack roll + automatic successes
              |
              v
subtract defense successes (optional)
              |
              v
clamp >= 0, cap at RMax
              |
              v
base + (successes - 1) * per-success
              |
              v
- 2 * selected resistance
- valid armor/location protection and Force
              |
              v
display final DMG only (manual HP update)

AB is parallel: start from attack AB, subtract selected resistance once per point and only the first applicable protection value, then clamp at zero. Neither Force nor summed multiple armor values reduce AB.

Effect flow

Book techniques/powers may receive inferred timing at build time. A user can copy those, or a configured consumable, to repeating_modifiers. Start/end turn actions read active rows, emit phase-specific reminders, decrement matching turn counters, and mark expiration. No natural-language effect is executed.

Reusable effects follow a separate path:

book/static site/import -> repeating_sharedeffects (library)
                                  |
                        linked technique/power card
                                  |
                        authorized Mod button click
                                  |
                                  v
                         repeating_modifiers (active)

Keeping library and active state separate permits reuse and avoids treating an import as immediate application.

Versioned interchange contracts

Character v1

  • Discriminator: ravenous-roll20-character
  • Version: 1
  • Producer/consumer: character Mod, monster converter, seeded generator
  • Mutation modes: create (GM) or replace existing controlled character
  • Compatibility rule: additions require importer validation changes; breaking field changes require a new version or explicit migration.

Craft v1

  • Discriminator: ravenous-roll20-craft
  • Version: 1
  • Normative schema: docs/ravenous-craft-v1.schema.json
  • Payload: optional craft metadata plus 1–100 finalized items
  • Destinations: attacks, protections, consumables, active modifiers
  • Separation rule: recipe calculation is producer-side; importer only validates and maps finalized sheet values.

Effects v1

  • Discriminator: ravenous-roll20-effects
  • Version: 1
  • Normative schema: effects_web/schemas/ravenous-effects-v1.schema.json
  • Destination: reusable effect library only
  • Application to active state uses the separately authorized chat action.

Schemas and Mod validation must evolve together. JSON Schema helps external producers, but Mod scripts must retain their own validation because Roll20 does not execute the repository's schema files.

Companion static applications

Both sites use a small source-template plus Python-generator architecture:

book data + local schema + src/{html,css,js}
                  |
             tools/build.py
                  |
     static build/{html,css,js,catalog,metadata}

They require no server, account, runtime package registry, or external API. Generated catalogues contain normalized/versioned data. User-created state lives in local storage and exports only on an explicit action. Imported data is rendered via safe DOM text APIs.

The craft site's detailed intended calculation architecture is specified in craft_web/AGENTS.md; incomplete roadmap items remain in craft_web/TASKS.md. The effects site's tighter rules are in effects_web/AGENTS.md.

Verification architecture

Verification is layered because no local tool fully emulates Roll20:

Layer What it proves What it does not prove
Python unit tests deterministic generation, parsing, schemas, formulas represented in generation, converter/fixture shape browser layout, Roll20 dice parser, chat rendering
Node sheet-worker mock worker callbacks, attribute/repeating behavior, computed roll completion real Roll20 sandbox/parser/browser quirks
Node Mod API mocks commands, permissions, handouts, validation, object mutations production API timing and UI
--check modes output matches current inputs runtime correctness
Roll20/browser smoke tests actual persistence, targeting, macros, rendering, interaction exhaustive logic coverage

Primary commands from the repository root:

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/build.sh --check
uv run python craft_web/tools/build.py --check
uv run python effects_web/tools/build.py --check

The exact remaining manual matrix and dated evidence belong in TASKS.md, not in this architecture document.

CI and deployment topology

Jenkins initializes all submodules, provisions uv, verifies Python SQLite, builds the three deliverables, exports representative monsters, runs Python tests, conditionally runs Node Mod tests, performs deterministic checks, archives output, and publishes allowed branches.

Branch mapping is:

  • main/master: production names;
  • candlelight: _candlelight development names;
  • lighthouse: _lighthouse review names;
  • all other branches: archive only.

Every deploy helper resolves against a hard-coded directory allow-list below /mnt/assets/ravenous_roll20 before creating the resolved directory and using rsync --delete. The shared project asset root is never itself a deletion target. This pipeline no longer writes to or removes content from /mnt/books.

Change-impact guide

Change Required review/update
New/renamed sheet field HTML, worker readers/writers/events, repeating import/export mappings, fixtures, Node mocks, migration decision
Rule formula Pinned book citation, worker, tests, feature spec, Roll20 hand calculation
New book macro/data shape parser/translator, failure behavior, generation tests, companion generators if shared
New repeating section markup/CSS, worker lifecycle, character contract, generators, Mod round trip
JSON contract change schema, semantic docs, all producers/consumers, invalid cases, version/backward compatibility
Theme change Typst parser/mapping, sheet and chat CSS, both companion sites, contrast check
New Mod command permissions, target resolution, direct/handout parsing, validation limits, macro docs, API mock
New deployable component independent build/test/check, archive list, branch mapping, allow-listed deployment

Recreating the project in another repository

Implement in this order to minimize accidental coupling:

  1. Pin or otherwise version the authoritative rule/data source.
  2. Define stable normalized IDs and the three versioned interchange contracts.
  3. Build a deterministic compiler from source data plus hand-maintained templates; include a stale-output check and manifest.
  4. Implement the persistent character schema and pure calculation functions.
  5. Add event-driven recalculation, rolls, and repeating-row workflows.
  6. Add privileged import/export only behind explicit validation and permission boundaries.
  7. Add seeded/golden fixtures and layered test harnesses.
  8. Add static companion producers/consumers against the contracts.
  9. Add guarded archive/deployment automation.
  10. Run real-platform smoke tests and record what remains manual or unverified.

Equivalent behavior and contracts matter more than duplicating this repository's exact languages or file tree.