d10_cs_generator/ARCHITECTURE.md

9.5 KiB
Raw Permalink Blame History

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:

  • 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:

{
  "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.