d10_cs_generator/FEATURES.md

10 KiB
Raw Permalink Blame History

Portable feature catalogue

This file is the behavioral contract for the D10 Roll20 generator. Each section is intentionally written so it can be handed to an agent working in a different repository: port the intent and contracts, adapt names and layout to the destination, and prove the acceptance criteria there. Do not copy D10 game mechanics into another system unless that system uses the same rules.

When a feature is added or changed, update its dossier here in the same change. Record the user-visible behavior, persistent-data contract, source locations, runtime boundary, and tests. Add a new dossier when none of the existing ones fits.

F01 — Deterministic model-driven sheet generation

Intent. Build complete Roll20 artifacts from reviewed data and templates, without maintaining generated HTML or CSS by hand.

Contract. tools/build.py reads a versioned sheet model, a variant skill catalogue, theme data, shared CSS, optional worker JavaScript, and binary assets. It validates identifiers and cross-references before writing UTF-8 sheet.html, sheet.css, translation.json, sheet.json, and build-info.json. Identical inputs produce identical output. --check reports missing or stale output without rewriting it.

Porting recipe. Define explicit source data for every structural choice; escape all values inserted into HTML; reject duplicate or invalid identifiers; generate into an ignored directory; include a content digest and useful counts in build metadata; compare bytes in check mode.

Acceptance. Build twice and compare every byte; mutate one output and prove check mode fails; feed invalid identifiers, references, and colors and prove the builder fails before writing output.

F02 — Base and cyberpunk variants with stable storage

Intent. Generate two related sheets from one engine while retaining their different catalogues, layout, and mechanics.

Contract. Variant structure lives under variants in data/sheet_model.yaml. Each variant selects its own skill YAML. Stable Roll20 attribute names and repeating section identifiers are compatibility APIs. Base has generic combat fields and four skill subtabs; cyberpunk has categorized skills, localized health/armor, contacts, consumables, and weapon sections.

Porting recipe. Put shared behavior in the renderer and variant differences in data or narrowly scoped worker modules. Never infer a variant from a label. Document every renamed stored field as a migration.

Acceptance. Generate and inspect both variants; verify every roll attribute reference resolves to a declared field (apart from Roll20 built-ins); verify each repeating section occurs exactly once.

F03 — Persistent navigation and visual-only themes

Intent. Let users organize a large sheet and choose its appearance without altering game state or roll behavior.

Contract. Action buttons update hidden attributes through sheet workers. CSS sibling selectors show the selected page or subpage. Theme selectors save d10_theme_choice, copy it to d10_theme, and switch CSS custom properties. Base exposes parchment and night; cyberpunk exposes all validated palettes. Theme IDs remain stable even if labels change.

Porting recipe. Store navigation/theme state as ordinary attributes; keep theme values out of roll expressions; compile all allowed palettes into the same artifact; include fallbacks for retired tab values.

Acceptance. Execute worker click/change handlers in a local Roll20 mock; compare normalized HTML across themes; prove only CSS/theme defaults vary; test every variant and palette.

F04 — Fixed skills and repeating user content

Intent. Combine a curated skill catalogue with user-created skills, equipment, contacts, consumables, and weapons.

Contract. Fixed skills are generated from YAML with stable field stems. User content uses Roll20 repeating_<section> fieldsets. Parent skills may contribute to child thresholds. Labels are presentation; IDs are storage.

Porting recipe. Version and validate catalogue IDs, generate selectors from known characteristics, and keep section/field names stable. Test attribute references rather than only visible labels.

Acceptance. Reject duplicate skill IDs and invalid parents; verify fixed and repeating fields are unique; manually add, reorder, reopen, and roll a repeating row in the Roll20 Custom Sheet Sandbox.

F05 — Cyberpunk localized health and armor

Intent. Present health, protection, integrity, and integrity maximum by body location on readable diagrams.

Contract. Location IDs are head, body, left_arm, right_arm, left_leg, and right_leg. Existing Life_Points_*, Armor_Protection_Points_*, and Armor_Integrity_Points_* names are retained; maximum integrity adds _maximum. Source PNGs live in assets/, are copied to cyberpunk output, and default to the public HTTPS asset directory. A blank asset base URL creates a local-preview build.

Porting recipe. Keep image assets independent of stored fields, validate the URL scheme, include responsive fallback layout, and preserve the semantic location IDs even if art changes.

Acceptance. Compare copied assets byte-for-byte; verify each location field appears exactly once; test public and local URLs; inspect both wide and narrow layouts in Roll20.

F06 — Cyberpunk weapon actions

Intent. Support melee, single, burst, and automatic attacks; damage-only calculation; ammunition checks; and magazine reloads from repeating rows.

Contract. templates/cyberpunk-weapons.js owns the worker behavior and is included only in cyberpunk builds. Attack dice are prompted per action. Combat dice are d10 with cs1cf10. Rmax caps retained successes for melee/single and manual damage, but not burst/automatic fire. Multi-shot damage emits one value per successful bullet and never exceeds bullets fired. Reserve stores spare magazines, not rounds. Reload consumes one reserve magazine. Repeating action IDs avoid underscores for Roll20 compatibility.

Porting recipe. Keep formulas in one worker module, read a row snapshot before rolling, mutate ammunition only after validation, and use startRoll / finishRoll for computed results. Treat stored field names and action event names as separate compatibility surfaces.

Acceptance. Simulate every action with empty, partial, and full magazines; test zero/some/excess successes, natural 1 bonuses, Rmax, and reload; then run the same flows in the Custom Sheet Sandbox because a mock does not parse dice.

F07 — Versioned character JSON exchange

Intent. Back up, transfer, and restore complete D10 Roll20 characters, including repeating rows, without changing the sheet’s storage model.

User experience. Both sheet variants show Échanges JSON in the header. Exporter creates a handout containing readable JSON. Restaurer asks for a handout ID and replaces the current character in place, preserving its Roll20 ID and linked tokens.

Boundary. The sheet buttons only send chat commands. The separately installed Roll20 Mod script scripts/d10_character_io.js performs privileged object access. The feature is unavailable when that script is not installed.

Wire format. The top-level discriminator is {"format":"d10-roll20-character","version":1}. Required values are a non-empty name and an attributes array. Each attribute has string name, current, and max. Optional data includes abilities, bio, gmnotes, controlledby, and inplayerjournals. Unknown future versions are rejected. All attributes are transported generically, so fixed fields and repeating rows round-trip without a D10-specific mapping.

Commands. !d10-export uses one selected linked token; !d10-export --id CHARACTER_ID is used by the sheet. A GM may create a new character with !d10-import JSON or !d10-import --handout HANDOUT_ID. !d10-import --replace [--id CHARACTER_ID] --handout HANDOUT_ID restores into an existing controlled character. Handout input is preferred for large JSON.

Security and mutation rules. GMs may access all targets. Players may export or replace only characters they control and may read only shared/controlled handouts. Player exports omit GM notes; player restores cannot change GM notes, ownership, or journal visibility. New-character creation is GM-only. Payload shape, version, sizes, and scalar types are validated before mutation. Replace deletes existing attributes and abilities, then recreates them; it is destructive and should use a fresh export as a backup.

Porting recipe. Choose a repository-specific format and command prefix; keep the payload versioned; export generic Roll20 attributes; validate fully; separate create from replace permissions; decode Roll20 HTML/URI handout representations; add sheet buttons only after the Mod command is stable.

Acceptance. In a Roll20 API mock, round-trip current/max values, repeating attributes, abilities, bio, notes, and access lists; test GM creation, player replacement, HTML-escaped handouts, malformed/version-mismatched data, and unauthorized character/handout access. In Roll20, export each variant, restore it, reopen the character, inspect repeating rows, and retest rolls.

F08 — Reproducible publication

Intent. Publish one self-contained artifact set per variant from the same verified generator used locally.

Contract. tools/publish_builds.py creates RPG/d10_character_sheet/{base,cyberpunk} plus shared body assets. Jenkins starts from a clean checkout, installs Python dependencies, runs Python tests, runs JavaScript checks when Node is available, archives the tree, and deploys master to /mnt/books/RPG/d10_character_sheet/.

Porting recipe. Make local and CI publication call the same code; rebuild targets instead of merging stale files; archive only generated deliverables; gate deployment on branch and successful verification.

Acceptance. Assert the complete artifact tree and absence of retired directories; run builder check mode against published variants; verify deploy sentinels after synchronization.

Feature dossier template

Copy this block when introducing a portable behavior:

## FXX — Name

**Intent.** User problem and outcome.

**Contract.** Observable behavior and persistent/runtime interfaces.

**Boundary.** Which component owns privileged or external behavior.

**Porting recipe.** Minimal implementation sequence without game-specific assumptions.

**Acceptance.** Automated behavior checks plus any required live Roll20 checks.

**Migration.** Stored names or behavior that existing characters must preserve.