d10_cs_generator/ARCHITECTURE.md

199 lines
9.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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.