d10_cs_generator/FEATURES.md

217 lines
10 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.

# 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:
```markdown
## 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.
```