20 KiB
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:
- Build-time code trusts the pinned repository inputs but must still fail loudly on unsupported structure or missing required theme/data fields.
- 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.yamlfor sheet-visible skill hierarchy;data/src/schools/*.tsvfor techniques;data/src/origines/*.yamlfor origins and powers;data/src/glossaries/*.yamlfor labels/descriptions;data/config/build.yamlfor tier limit, trigrams, and default theme;setup/theme/themes.typfor 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:
- Parse build configuration, glossary labels, themes, sheet data, school TSVs, and origin YAML.
- Normalize human names to stable slugs/source keys. Flatten nested skills while retaining category, ancestry, depth, characteristic inheritance, and description.
- Translate a deliberately limited Typst subset into French plain text. Known difficulty/reference/weapon/area constructs have explicit renderers.
- Infer only conservative structured effect timing from translated French.
- Generate escaped HTML fragments, CSS category/theme rules, and line-bounded JavaScript literals.
- Replace uppercase
{{MARKER}}slots and fail if any remain. - 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:
onsubscribes to sheet open, field changes, and action-button clicks;getAttrsandsetAttrsread/write the current character;getSectionIDs,generateRowID, andremoveRepeatingRowmanage repeating sections;startRoll/finishRollexecute 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:
- recognize the exact API command;
- parse flags without evaluating input;
- resolve exactly one selected token or an explicit character ID;
- verify control of the destination;
- resolve direct JSON or a readable handout;
- decode Roll20's HTML-wrapped notes;
- validate the entire versioned payload and size limits;
- create rows or perform a replacement;
- 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, measures the Python generators with
an 85% line-coverage floor, performs deterministic checks, archives output, and
publishes allowed branches.
Branch mapping is:
main/master: production names;candlelight:_candlelightdevelopment names;lighthouse:_lighthousereview 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.
Badge state has an independent cleanup-time publication path. Build-numbered
markers distinguish tests and measurements completed by the current build from
stale workspace files. Jenkins cleanup renders exactly three ignored SVGs,
archives them, and publishes only main through the non-recursive atomic-copy
script to /mnt/assets/coverage/Ravenous/ravenous_roll20/main. The version is
read from pyproject.toml; coverage data and its JSON summary are temporary.
The product deploy helpers never write inside the shared coverage hierarchy.
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:
- Pin or otherwise version the authoritative rule/data source.
- Define stable normalized IDs and the three versioned interchange contracts.
- Build a deterministic compiler from source data plus hand-maintained templates; include a stale-output check and manifest.
- Implement the persistent character schema and pure calculation functions.
- Add event-driven recalculation, rolls, and repeating-row workflows.
- Add privileged import/export only behind explicit validation and permission boundaries.
- Add seeded/golden fixtures and layered test harnesses.
- Add static companion producers/consumers against the contracts.
- Add guarded archive/deployment automation.
- 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.