461 lines
20 KiB
Markdown
461 lines
20 KiB
Markdown
# Ravenous Roll20 architecture
|
||
|
||
## Purpose
|
||
|
||
This document explains the system boundaries and implementation contracts
|
||
needed to recreate the project. [FEATURES.md](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
|
||
|
||
```text
|
||
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:
|
||
|
||
```text
|
||
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
|
||
|
||
```text
|
||
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:
|
||
|
||
```text
|
||
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:
|
||
|
||
```text
|
||
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:
|
||
|
||
```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
|
||
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`: `_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`.
|
||
|
||
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:
|
||
|
||
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.
|