199 lines
9.5 KiB
Markdown
199 lines
9.5 KiB
Markdown
# 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
|
||
|
||
```text
|
||
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:
|
||
|
||
- `title` and a `skills` YAML filename;
|
||
- `attributes` and `resources`, each with stable `id` and display `name`;
|
||
- optional `combat`, `weapons`, and `health_locations`;
|
||
- `repeating` sections with stable section IDs and field IDs;
|
||
- exactly one navigation strategy: base `skill_tabs` or cyberpunk
|
||
`skill_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:
|
||
|
||
1. header identity, die, theme, and JSON exchange controls;
|
||
2. always-visible characteristics;
|
||
3. always-visible resources and optional cyberpunk body maps;
|
||
4. saved primary navigation;
|
||
5. Combat and Skills pages, plus cyberpunk Other;
|
||
6. roll templates;
|
||
7. one `text/worker` script.
|
||
|
||
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:
|
||
|
||
```json
|
||
{
|
||
"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:
|
||
|
||
1. Python unit tests validate source models and rendered artifacts across both
|
||
variants and every allowed theme.
|
||
2. `tools/build.py --check` proves a target exactly matches current sources.
|
||
3. `tests/test_tabs.mjs` simulates sheet-worker tab/theme/weapon behavior.
|
||
4. `tests/test_character_io.mjs` simulates Mod object access, permissions, and
|
||
JSON round trips.
|
||
5. Roll20 Custom Sheet Sandbox verifies browser layout, repeating controls,
|
||
dice parsing, chat output, saved state, and reopen behavior.
|
||
6. 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:
|
||
|
||
1. Create the directory map in section 2 and ignore generated/reference roots.
|
||
2. Define sheet-model version 1 with both variant field and repeating-section
|
||
IDs before writing presentation code.
|
||
3. Populate and validate both skill catalogues and the theme palette file.
|
||
4. Implement an in-memory deterministic builder with HTML escaping and check
|
||
mode; add invalid-input tests first.
|
||
5. Render the shared header, characteristics, resources, tabs, skills,
|
||
repeaters, and roll templates; assert every roll reference resolves.
|
||
6. Add saved navigation and theme workers, then their JavaScript simulation.
|
||
7. Add cyberpunk body maps and weapon worker behavior with formula-level tests.
|
||
8. Add the versioned JSON Mod boundary and permission/round-trip tests.
|
||
9. 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.
|