217 lines
10 KiB
Markdown
217 lines
10 KiB
Markdown
# 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.
|
||
```
|