9.5 KiB
D10 Roll20 generator architecture
This document is the construction map for the repository. Together with
FEATURES.md, it should let another agent recreate the generator and its
observable behavior without relying on generated files or undocumented Git
history.
1. System boundary
The repository produces two Roll20 Custom Sheet bundles: base fantasy D10 and cyberpunk D10. It also contains optional Roll20 Mod scripts. The sheet runs in Roll20’s browser/sheet-worker environment; Mod scripts run separately in the campaign API sandbox and are never embedded into generated HTML.
Authoritative inputs are the YAML model/catalogues, CSS and worker templates,
binary assets, and generator code. build/ and RPG/d10_character_sheet/ are
derived output. agent_models/ is a local, ignored research area and is not an
input, dependency, or distributable.
2. Repository map
| Path | Responsibility |
|---|---|
data/sheet_model.yaml |
Versioned variant structure, stable attributes, resources, repeating sections, and tab composition. |
data/base_skills.yaml |
Base fixed-skill catalogue. |
data/cyberpunk_skills.yaml |
Cyberpunk fixed-skill catalogue and equipment-category mapping. |
data/themes.yaml |
Named theme palettes with display names and five required colors. |
templates/sheet.css |
Shared Roll20 CSE layout, component, responsive, and roll-template CSS. |
templates/cyberpunk-weapons.js |
Cyberpunk-only repeating weapon sheet-worker behavior. |
assets/*.png |
Original cyberpunk body-map images. |
tools/build.py |
Validation, HTML/CSS/worker rendering, artifact writing, and stale-output checking. |
tools/publish_builds.py |
Canonical two-variant publication tree builder. |
scripts/d10_character_io.js |
Optional current Mod feature for versioned character JSON exchange. |
scripts/change.js, scripts/crit.js |
Unvalidated historical Mod scripts; not generator dependencies. |
tests/test_build.py |
Model validation and generated artifact contracts. |
tests/test_tabs.mjs |
Sheet-worker navigation and cyberpunk weapon simulation against published output. |
tests/test_character_io.mjs |
Roll20 API mock for JSON exchange permissions and round trips. |
build.sh |
Local publication entry point, with optional cleanup. |
Jenkinsfile |
Clean checkout, verification, archive, and master-only deployment. |
3. Build data flow
sheet_model.yaml ─┐
skills YAML ──────┼─> validate() ─> render() ─> sheet.html
themes.yaml ──────┤ ├───────> sheet.css
sheet.css ────────┤ ├───────> translation.json
weapon worker ────┤ ├───────> sheet.json
assets/*.png ─────┘ └───────> build-info.json + copied PNGs
build(variant, theme, output, check, asset_base_url) is the central API.
It selects the requested variant and its skill catalogue, restricts base to
the two base themes, validates all inputs, renders complete strings in memory,
and either writes them or compares them byte-for-byte with an existing target.
Validation happens before output creation.
publish_builds.publish() is the deployment-level API. It recreates each
variant target, builds its default parchment entry artifact (which contains a
runtime theme selector), checks it, and copies shared public assets.
4. Model contracts
The top-level sheet-model version is 1. Each variant defines:
titleand askillsYAML filename;attributesandresources, each with stableidand displayname;- optional
combat,weapons, andhealth_locations; repeatingsections with stable section IDs and field IDs;- exactly one navigation strategy: base
skill_tabsor cyberpunkskill_category_tabs.
Skill YAML contains sections, each with groups. Groups may contain fixed
skills or identify a repeating equipment section. Fixed skill IDs must be
valid Roll20 identifiers and unique within the generated namespace. A child’s
parent must refer to an earlier skill in the same group.
Every theme requires background, panel, ink, accent, and border as
six-digit hex colors. Names and colors are data; theme mechanics are not.
Storage names are public compatibility interfaces. An attr_ name in HTML is
stored without that prefix by Roll20. A repeating_<id> fieldset creates names
such as repeating_<id>_<row-id>_<field>. Changing any of these identifiers
requires an explicit migration plan.
5. Generated sheet composition
render() creates one .sheet-theme-shell containing a saved theme state and
one .sheet-d10 variant root. The visible order is:
- header identity, die, theme, and JSON exchange controls;
- always-visible characteristics;
- always-visible resources and optional cyberpunk body maps;
- saved primary navigation;
- Combat and Skills pages, plus cyberpunk Other;
- roll templates;
- one
text/workerscript.
Fixed skill rows are built from catalogue data. Repeating blocks are built from the model. Specialized cyberpunk weapon rows share stable fields with ordinary repeaters but receive action buttons and worker logic. HTML data is escaped at generation time.
CSS uses only classes, saved hidden-input sibling selectors, and custom color properties. Roll template styles share the selected compiled palette. The responsive breakpoint collapses grids and keeps body maps usable on a narrow sheet.
6. Roll20 runtime model
Ordinary roll buttons interpolate Roll20 attributes and use the
d10skillcheck template. Navigation and theme controls are type="action"
buttons handled by on("clicked:...") or change handlers that call setAttrs.
Cyberpunk weapon actions use getAttrs, getSectionIDs, startRoll, and
finishRoll from the sheet-worker API.
The local JavaScript harness implements only the subset of that API needed by the workers. It proves event routing, reads/writes, and computed-result logic; it does not reproduce Roll20’s dice parser, DOM rendering, persistence timing, or sandbox permissions. Those remain explicit live-test responsibilities.
7. Character JSON exchange boundary
The generated header sends !d10-export and !d10-import commands. It cannot
read or create Roll20 characters itself. scripts/d10_character_io.js, when a
GM separately installs it as a Mod script, handles chat:message, permission
checks, handout encoding/decoding, validation, and Roll20 object mutation.
The payload is versioned independently of the sheet model:
{
"format": "d10-roll20-character",
"version": 1,
"name": "Character name",
"attributes": [
{"name": "Life_Points", "current": "7", "max": "10"}
],
"abilities": []
}
The generic attribute list is deliberate: it transports both variants and all repeating sections without teaching the Mod script the model. Import validation has bounded counts/text sizes and exact format/version checks. Replace is a full attribute/ability replacement, while player-level replacement protects GM-only metadata and ownership.
8. Verification layers
Use all applicable layers, in order:
- Python unit tests validate source models and rendered artifacts across both variants and every allowed theme.
tools/build.py --checkproves a target exactly matches current sources.tests/test_tabs.mjssimulates sheet-worker tab/theme/weapon behavior.tests/test_character_io.mjssimulates Mod object access, permissions, and JSON round trips.- Roll20 Custom Sheet Sandbox verifies browser layout, repeating controls, dice parsing, chat output, saved state, and reopen behavior.
- A campaign with the Mod script installed verifies real character/handout permissions and JSON export/restore.
Never label layers 1–4 as a live Roll20 test.
9. Publication architecture
./build.sh calls the publisher and optionally deletes local generated roots
first. Jenkins repeats the Python tests and publication from a clean checkout.
When Node exists, it runs both JavaScript suites; Python generation remains
publishable on agents without Node. Successful artifacts are archived under
RPG/d10_character_sheet/. Only master deploys, using rsync --delete, to
the matching server path.
The optional Mod scripts are source-distributed from scripts/; they are not
embedded into or automatically installed by the artifact tree.
10. Reconstruction sequence
To recreate this repository from the contracts:
- Create the directory map in section 2 and ignore generated/reference roots.
- Define sheet-model version 1 with both variant field and repeating-section IDs before writing presentation code.
- Populate and validate both skill catalogues and the theme palette file.
- Implement an in-memory deterministic builder with HTML escaping and check mode; add invalid-input tests first.
- Render the shared header, characteristics, resources, tabs, skills, repeaters, and roll templates; assert every roll reference resolves.
- Add saved navigation and theme workers, then their JavaScript simulation.
- Add cyberpunk body maps and weapon worker behavior with formula-level tests.
- Add the versioned JSON Mod boundary and permission/round-trip tests.
- Add publication, artifact-tree tests, Jenkins archive/deploy stages, and the documented live Roll20 checklist.
At every step, generated files remain disposable and existing stored IDs remain
stable. FEATURES.md is the source for observable behavior and porting
acceptance; this file is the source for component ownership and data flow.