ravenous_roll20/FEATURES.md

30 KiB
Raw Permalink Blame History

Ravenous Roll20 feature catalogue

How to use this document

This is the portable product specification for the repository. Use it when an equivalent feature must be implemented in another project, even if that project uses a different language, framework, or directory layout. Each feature states observable behavior, invariants, source-of-truth inputs, the implementation in this repository, and acceptance criteria.

This document deliberately does not duplicate every attribute or function. Those integration details live in ARCHITECTURE.md. The pinned ravenous_typst submodule is authoritative for game rules and source data. If this document and the book disagree, verify the pinned book and update this document rather than preserving an accidental implementation detail.

Feature status terms:

  • Implemented means the code and local automated checks exist.
  • Roll20-verified means the interaction has also been exercised in Roll20.
  • Manual by design means the sheet presents or calculates information but intentionally does not mutate the corresponding resource.
  • Pending smoke test means local mocks cover the logic but the remaining real-platform scenarios are tracked in TASKS.md.

Product boundary

The product is a French Ravenous character-management suite with four parts:

  1. a generated Roll20 Custom Sheet Enhancement (CSE) character sheet;
  2. optional Roll20 Mod scripts for validated JSON exchange and cross-character actions;
  3. deterministic converters and example-payload generators;
  4. two dependency-free static companion sites for crafting and reusable effects.

The suite assists play; it is not an autonomous rules engine. HP, armor integrity, technique costs, consumable quantities, and mechanical consequences of effects remain manual unless a future feature explicitly changes that decision.

F01 — Book-driven deterministic sheet build

Status: Implemented.

Outcome. Generate a deployable Roll20 bundle from hand-maintained templates and the pinned Ravenous rulebook data. A rebuild with identical inputs produces byte-identical output, and a check mode detects stale artifacts.

Required behavior and invariants:

  • Read skills, nested specializations, school techniques, origins, powers, glossary labels, build limits, trigrams, and themes from the pinned book.
  • Import only school tiers strictly below build.max_tier_exclusive.
  • Exclude resistance definitions from the generated skill list because the sheet models them as dedicated resistance fields.
  • Translate only the supported Typst subset. Resolve known references and macros; do not silently invent semantics for unsupported game markup.
  • Escape generated HTML and JavaScript safely, prevent literal </script> termination, and keep generated JavaScript data split over bounded lines for the Roll20 editor.
  • Fail if an uppercase template marker remains unresolved.
  • Emit the HTML, CSS, translations, manifest, and a build manifest containing source counts, selected limits/theme, a theme list, and a content hash.
  • --check compares expected generated content without rewriting it.

This repository: tools/build.py, src/ravenous.html, src/ravenous.css, src/translation.json, src/sheet.json, and scripts/build.sh. Generated artifacts belong in build/ and are never edited directly.

Acceptance: build twice and compare bytes; run ./scripts/build.sh --check; verify the expected source counts and absence of unresolved markers/raw known Typst constructs with tests/test_build.py.

F02 — Responsive, persistent, themed character sheet shell

Status: Implemented; themes are Roll20-verified.

Outcome. Present the character through eight compact pages: Chasseur, Compétences, Combat, Santé & résistances, Cuisine & alchimie, Écoles, Pouvoirs, and Effets & tours. Navigation and user choices persist as Roll20 attributes.

Required behavior and invariants:

  • Use Roll20 CSE mode with Legacy Sanitization disabled.
  • Keep tabs in one sheet document and switch them through a persisted hidden tab attribute and action buttons; do not rely on page reloads.
  • Adapt grids for narrower screens without dropping fields.
  • Generate all palettes from the book theme file. Persist the per-character theme and apply it to both the sheet and chat cards.
  • Permit a build-time initial/fallback UI theme without removing other themes.
  • Retain readable system font fallbacks when the optional Google font cannot load.
  • Include public/GM-only roll selection and compact JSON exchange shortcuts in the header.

This repository: page markup and sheet workers are in src/ravenous.html; responsive styles and CSS custom properties are in src/ravenous.css; palette parsing and generated selectors/rules are in tools/build.py.

Acceptance: switch every page, reopen the sheet, select at least two themes, and inspect both sheet and chat output at desktop and narrow widths. Confirm all book palettes occur in the generated selector and CSS.

F03 — Character characteristics, resources, and derived values

Status: Implemented; core calculations are Roll20-verified.

Outcome. Track eight characteristics, temporary modifiers, resources, and derived movement/health statistics with immediate worker recalculation.

Required behavior and invariants:

  • Track Force, Agilité, Perception, Intelligence, Volonté, Psy, Chance, and Charisme as permanent values plus temporary modifiers and displayed totals.
  • Calculate derived statistics from permanent characteristics and explicit derived-value modifiers. Temporary characteristic modifiers affect final characteristics and skill totals, but not derived base formulas.
  • Track current and maximum Jauge, Fatigue, Toxicité, Satiété, Sang, and Actions as appropriate; maximum formulas can have explicit modifiers.
  • Recalculate on sheet open and every governing input change using silent writes where cascading events would otherwise loop.
  • Preserve stable attribute names because existing Roll20 characters store state under those names.

This repository: fixed fields and the recalculate worker in src/ravenous.html; formula assertions in tests/test_build.py and behavior checks in tests/test_worker.mjs.

Acceptance: test base and temporary changes independently, all max-value modifiers, stage boundaries, and sheet reopen. Compare formulas with the pinned rulebook before porting them.

F04 — Generated and custom skills with roll outcomes

Status: Implemented; critical-failure boundary awaits Roll20 retest.

Outcome. Expose every sheet-visible book skill in category subtabs, support nested specializations and custom skills, and resolve single-die threshold checks into an outcome and margin.

Required behavior and invariants:

  • Generate stable skill IDs and distinct stored attributes. Nested entries inherit their parent characteristic, include ancestry in their ID/full name, and appear indented under the parent.
  • Allow the characteristic association, rank, and temporary modifier to contribute to a skill total. The generated internal effect slot is currently reserved and remains zero; do not claim active-effect automation.
  • Custom repeating skills choose a characteristic and use the same total and roll semantics.
  • Let users select the die size. A roll is a critical success on natural 1, a critical failure on the maximum face, a normal success below the threshold, and otherwise a failure. Margin is threshold - rolled.
  • Respect the character's public/secret-roll choice.

This repository: skill normalization and HTML generation in tools/build.py; totals and performSkillRoll in src/ravenous.html.

Acceptance: verify unique IDs, category membership, nested indentation, custom-row persistence, and rolls at natural 1, just below threshold, exactly at threshold, and the maximum die face for both public and secret settings.

F05 — Attack, defense, damage, and mitigation workflow

Status: Implemented locally; targeted-token edge cases remain a pending Roll20 smoke test.

Outcome. Model arbitrary attacks as repeating rows, roll successes, offer chat follow-ups for defense and damage, and show damage/armor-break results after a targeted defender's selected mitigations.

Required behavior and invariants:

  • An attack stores name, default pool, threshold, temporary threshold modifier, optional automatic successes, whether dice are rolled, base damage, damage per extra success, armor break, maximum counted successes, three defense thresholds, and notes.
  • Attack dice count successes against the attack threshold and add automatic successes. Follow-up context is cached by the original roll ID when available.
  • Defense prompts for a defender token and a defense type. Dodge and parry add only the targeted defender's corresponding skill and temporary skill value to the attack's defense threshold; reposition uses its fixed threshold.
  • After defense, remaining successes are clamped to zero and capped by RMax. Zero final successes deal zero damage. Otherwise: damage = base + (final successes - 1) * damage per success.
  • Manual Dégâts accepts remaining successes when cached context is absent.
  • Subir prompts for remaining successes and a defender token, reads that defender's selected resistance and protection/location query, and displays the breakdown. Each selected resistance point removes 2 DMG and 1 AB. Protection mitigation and the first protection used for AB follow the rules described in F06.
  • Results never subtract HP or armor integrity; that remains manual by design.
  • Cache loss after worker restart must degrade to prompted/manual input rather than corrupting a character.

This repository: attack repeating rows, attackRolls, attackDamage, and four attack action handlers in src/ravenous.html; roll-template branches in the same file.

Acceptance: test zero/one/many successes, automatic-only attacks, RMax, defense greater than attack, all three defense types, public/secret defender rolls, absent cached context, and hand-calculated DMG/AB with a targeted second character.

F06 — Health locations, resistances, and protection selection

Status: Implemented locally; complete combat matrix remains a pending Roll20 smoke test.

Outcome. Track health and armor per body location, accumulate selected damage resistances, and make active armor or a chosen location available to the damage workflow.

Required behavior and invariants:

  • Provide fixed head, torso, left/right arm, and left/right leg rows plus custom repeating locations. Each row keeps HP, HP maximum, protection, current armor integrity, and maximum integrity.
  • Track the full sheet resistance set, while only damage-applicable physical and elemental types participate in the current attack reduction selector.
  • Multiple checked resistances accumulate. A clear action resets all checks.
  • An active repeating protection contributes only while current integrity is greater than zero. Sum protection for DMG, count active valid rows, and retain the first valid protection in repeating-row order for AB.
  • Current-selection DMG mitigation is total active protection plus final Force if at least one valid protection exists. For a fixed/custom location, use its protection plus Force only when its armor integrity is above zero.
  • AB reduction uses selected resistance points and the first protection value, never Force. Clamp displayed final values at zero.
  • Encode both DMG mitigation and AB protection into one Roll20 query value so a single location prompt can transport both integers through the dice parser.

This repository: health fields, DAMAGE_RESISTANCES, FIXED_LOCATIONS, PACK_FACTOR, and recalculation workers in src/ravenous.html.

Acceptance: cover no armor, depleted armor, one and multiple active protections, row reorder, each fixed location, a custom location with macro punctuation in its name, multiple resistance checks, and zero clamping.

F07 — Consumables and structured turn-effect tracker

Status: Implemented.

Outcome. Store free-form consumables and temporary effects, publish them to chat, copy consumable/technique/power effects into a tracker, and guide manual turn processing with reminders and expiration.

Required behavior and invariants:

  • Consumables store kind, name, quantity, display duration, description, and optional structured timing/reminders. Publishing does not consume quantity.
  • Active effects store an active flag, name, display duration, description, duration type, remaining count, countdown phase, and start/end/application/ removal reminders.
  • Supported duration types are manual, N turns, until next start, until next end, combat, and a reserved actions mode. Unknown or legacy timing defaults to manual behavior.
  • Start/end actions publish reminders for that phase, decrement only matching turn counters, mark expired effects inactive, and announce removals. They do not apply prose mechanics or change HP/resources.
  • Cleanup removes only inactive effect rows and reports how many were removed.
  • Copying from a consumable preserves configured timing. Copying from a technique or power copies text and any inferred timing, without interpreting arbitrary prose at runtime.
  • Build-time reminder inference is conservative: recognize explicit French start/end phrases, next-start/next-end, finite turn counts, and combat end; leave uncertain duration manual.

This repository: effect markup and worker handlers in src/ravenous.html; effect_reminder_metadata in tools/build.py.

Acceptance: test every duration type at both phases, inactive rows, a multi-turn countdown to zero, no-reminder phases, cleanup, and each copy source. Confirm no resource is automatically changed.

F08 — School technique catalogue and acquisition

Status: Implemented; Roll20-verified.

Outcome. Import eligible school techniques from book TSVs, let users add them individually to an editable repeating list, prevent duplicates, and show their cards/effects in chat.

Required behavior and invariants:

  • Group selector choices by school and label them with configured trigrams, tier, name, and level.
  • Carry school, tier, type, costs, other requirements, translated effect text, and inferred reminder metadata into the acquired row.
  • Use a stable source key to prevent adding the same generated technique twice; do not block user-created rows without that key.
  • On sheet open, backfill updated generated content/reminder metadata into rows with recognized source keys while preserving ownership and user linkage data.
  • Activation creates a themed chat card and optionally offers linked reusable effects. Tracking copies the technique into the temporary-effect tracker.
  • Do not automatically spend Sang/Jauge or execute the mechanical effect.

This repository: school ingestion and selector generation in tools/build.py; repeating rows and worker handlers in src/ravenous.html.

Acceptance: add one technique, reject its duplicate, add a custom row, reopen, activate, track as effect, and inspect text for unresolved Typst syntax.

F09 — Origin selection and staged powers

Status: Implemented; Roll20-verified.

Outcome. Select an origin, import its powers in stage batches, preserve existing/custom powers across origin changes, and activate or track powers.

Required behavior and invariants:

  • Generate origins and powers from YAML, translating supported book markup.
  • Persist both the origin key and human-readable origin name.
  • Selecting an origin alone adds nothing. The user chooses a stage and requests the batch for the currently selected origin.
  • Stable keys include origin, stage, and source position. Skip existing keys to prevent duplicates while leaving unrelated/custom rows untouched.
  • On sheet open, refresh recognized imported rows from current generated data.
  • Activation produces a themed chat card with optional linked reusable effects; tracking creates a temporary effect. No prose mechanics are automated.

This repository: origin parsing in tools/build.py; UI and workers in src/ravenous.html.

Acceptance: import the same stage twice, add another stage and a custom power, switch origin, reopen, activate, and track. Existing rows must survive and generated duplicates must not appear.

F10 — Reusable effect library and cross-character offers

Status: Implemented.

Outcome. Maintain reusable effect definitions separately from active effects, attach their IDs to technique/power chat cards, and let an authorized player copy an offered effect to a controlled target character.

Required behavior and invariants:

  • Library rows have a stable effect ID, enabled flag, constrained type, name, duration, description, structured timing, and four reminders.
  • Techniques/powers link by comma/space/semicolon-separated IDs. Only enabled, exactly matching IDs appear on a chat card.
  • Offer buttons carry a URI-encoded JSON payload and explicitly target a character through Roll20's target prompt.
  • The separate Mod action validates payload fields and bounds, verifies the clicking player controls the target, and creates an active temporary-effect row. It must not trust chat payloads or allow writes to another player's character.
  • Library JSON import/export targets reusable rows, not active effect rows.

This repository: library/link handling in src/ravenous.html; cross-character application in roll20_mod/ravenous_shared_effects.js; versioned exchange in roll20_mod/ravenous_effects_import.js and effects_web/schemas/ravenous-effects-v1.schema.json.

Acceptance: offer zero, one, and multiple effects; ignore disabled or unknown IDs; apply to a controlled target; reject an uncontrolled target and malformed/oversized payloads; round-trip a library through a handout.

F11 — Versioned character backup, restore, and creation

Status: Implemented; core workflow is Roll20-verified.

Outcome. Serialize a Roll20 character into a versioned JSON document and either create a new character or replace the sheet data of an existing one.

Required behavior and invariants:

  • Format identifier is ravenous-roll20-character, version 1.
  • Preserve name, sheet attributes, abilities, bio, GM notes, journal access, and control lists in exports, subject to caller visibility.
  • GM creation makes a new character. Replacement retains the destination object/ID, linked tokens, avatar, ownership, and GM-only notes while replacing name, bio, attributes, and abilities.
  • Validate the complete incoming document before deleting any destination attributes or abilities. Reject unknown fields, invalid types, unsafe sizes, duplicates where prohibited, and inaccessible inputs.
  • Players may export/replace only characters they control and read only shared handouts. GM handouts use GM Notes; player exports use visible Notes and grant that player access.
  • Support direct JSON for small payloads and decoded HTML handout content for larger payloads. Sheet header commands target the current character ID.
  • Reopening the sheet after import allows workers to recompute derived values.

This repository: roll20_mod/ravenous_character_io.js, header actions in src/ravenous.html, and tests/test_character_io.mjs.

Acceptance: round-trip all scalar/repeating attributes, abilities, Unicode, HTML-sensitive text, bio/notes, and permissions; test GM creation, GM replace, player replace, inaccessible handout, uncontrolled target, malformed JSON, and validation failure without partial deletion.

F12 — Monster database conversion

Status: Implemented.

Outcome. Convert a monster from the book's pinned SQLite database into the character JSON contract while retaining information that has no faithful sheet equivalent.

Required behavior and invariants:

  • Read the nested monsters.db submodule and select one/all master-visible creatures deterministically.
  • Map compatible characteristics, locations, attacks, and powers to stable character/repeating attributes.
  • Treat capabilities with damage as attacks and others as powers. Preserve source descriptions and damage notation in row notes.
  • Leave unknown dice pools/thresholds/mechanical values neutral for GM review; never fabricate a rule conversion.
  • Embed all raw database rows, including phases and unmapped fields, in GM notes as JSON so conversion is loss-aware.

This repository: tools/export_monsters.py and tests/test_monster_export.py.

Acceptance: convert every master-visible database entry, validate each against the character importer, verify representative locations/attacks/powers, and ensure raw source rows remain recoverable.

F13 — Craft JSON exchange

Status: Implemented locally; real Roll20 import smoke test remains pending.

Outcome. Exchange finalized crafted attacks, protections, consumables, and temporary effects through a strict versioned JSON envelope without coupling a crafting calculator to Roll20 internals.

Required behavior and invariants:

  • Format identifier is ravenous-roll20-craft, version 1. The normative schema is docs/ravenous-craft-v1.schema.json; semantics are documented in docs/craft-json-v1.md.
  • Accept 1–100 typed items with only the fields allowed for their destination. Reject unknown fields, invalid kinds, non-finite numbers, and oversized text.
  • Import creates new repeating rows; it never overwrites existing rows, equips protection, consumes ingredients, changes resources, or recalculates recipes.
  • Imported protection is inactive by omission and must be selected manually.
  • Export reads compatible repeating rows into a private/shared handout according to caller permissions.
  • Players can operate only on controlled characters and readable handouts; GMs can use explicit IDs or token selection.

This repository: roll20_mod/ravenous_craft_import.js, schema/docs under docs/, and deterministic examples from tools/generate_crafts.py.

Acceptance: import/export every item type, mixed item collections, inline and handout payloads, player/GM paths, every validation failure class, and reopen the destination sheet to confirm persistence.

F14 — Deterministic interoperability fixtures

Status: Implemented.

Outcome. Produce stable, adversarial example documents that exercise import contracts in local tests and CI.

Required behavior and invariants:

  • A seeded character generator covers fixed and repeating sheet sections, attributes, abilities, permissions, Unicode, and markup-sensitive strings.
  • Identical seeds produce byte-identical UTF-8 JSON; different seeds vary.
  • Craft generators deterministically cover forge (attack/protection) and alchemy (consumable/modifier) destinations.
  • Fixture generation is part of the normal build wrapper and check mode compares regenerated fixtures with output.
  • Fixtures are examples and test vectors, never authoritative game data.

This repository: tools/generate_character.py, tools/generate_crafts.py, scripts/build.sh, and their Python tests.

Acceptance: reproducibility tests, contract validation, coverage assertions, and successful import through the Mod API mock.

F15 — Static craft workshop companion

Status: Functional prototype; full five-discipline rule parity, finalized Roll20 mapping, QR sharing, and complete browser accessibility checks are not implemented. The exact roadmap is in craft_web/TASKS.md.

Outcome. Provide an account-free static application for browsing authoritative craft components, assembling single-discipline recipes, warning about basic limits, keeping personal data locally, and exchanging provisional recipe/output files.

Required behavior and invariants:

  • Production output is static HTML/CSS/JavaScript/catalog data with no backend, tracking, runtime CDN, or mandatory Node build.
  • Normalize all current craft TSV and Forge equipment entries with stable IDs, typed searchable/filterable values, source provenance, and a catalogue fingerprint.
  • Provide accent-insensitive search, discipline/stage and numeric filters, stable sorting, one-discipline composition, basic live totals/warnings, personal ingredients, undo/redo, local recipe/backup storage, editable recipe exchange, print output, and provisional Roll20 download/clipboard output.
  • Keep editable workshop recipes distinct from finalized Roll20 craft exports. Recalculate rather than trusting stored totals.
  • Treat imports and URL/local-storage state as untrusted. Use text DOM APIs, validate bounds, and keep recipes private unless the user explicitly exports.
  • Clearly label Forge compatibility/statistics, trap adjudication, repeated-effect cases, and any unported discipline calculation as manual/GM review. A provisional export must not be presented as rules-validated.
  • Preserve accessibility, responsive, print, offline-static, and theme goals, but consult craft_web/TASKS.md before claiming a goal is complete.
  • Rule/calculation scope and current limitations are authoritative in craft_web/AGENTS.md; do not claim roadmap items as implemented.

This repository: craft_web/ with its own sources, generator, schema, tests, README, task list, and nested agent guide.

Acceptance: deterministic static build/check, no external runtime dependencies, complete normalized-source catalogue, persistence/import/export round trips for implemented functions, and visible manual-review warnings. Discipline parity and browser-quality checks become required as their backlog items are implemented.

F16 — Static reusable-effects companion

Status: Implemented static catalogue/export foundation.

Outcome. Browse book alterations, assemble private reusable-effect sets, add custom entries, and export F10-compatible JSON without an account or server.

Required behavior and invariants:

  • Source book alterations from the pinned glossary and reuse sheet translation, theme, and conservative timing inference.
  • Generate a dependency-free static application and versioned catalogue.
  • Persist private sets/custom effects only in browser local storage and render untrusted text without HTML injection.
  • Export ravenous-roll20-effects v1 targeting the reusable library, not the active tracker. Unknown durations remain manual.

This repository: effects_web/, especially tools/build.py, static sources, the JSON schema, tests, and nested AGENTS.md.

Acceptance: deterministic build/check, catalogue translation and schema tests, local set round trips, hostile-text rendering checks, and import into repeating_sharedeffects through the Mod simulator.

F17 — CI build, archive, and guarded publication

Status: Implemented.

Outcome. Rebuild and validate all three static deliverables and fixtures, archive them with fingerprints, and publish only named branches to allow-listed directories.

Required behavior and invariants:

  • Initialize recursive submodules, use Python 3.11+ through pinned uv dependencies, and ensure SQLite support for monster tests.
  • Build/test/check the sheet, craft site, and effects site independently.
  • Run Mod simulator tests when Node is available; lack of Node is currently an explicitly reported optional skip in CI.
  • Archive all generated bundles and examples.
  • Measure Python generator line coverage with the pinned coverage tool and reject results below 85%. Generate version, test, and coverage SVGs for every build, archive exactly those badges, and publish them only from main below /mnt/assets/coverage/Ravenous/ravenous_roll20/main.
  • Finalize badges during Jenkins cleanup so failed main builds replace stale passing status and incomplete measurements with a neutral coverage badge.
  • Deploy production, development, and review branches to distinct allow-listed paths below /mnt/assets/ravenous_roll20. Create the resolved product directory when absent. Use deletion only inside that product subdirectory; never at the shared project asset root.
  • Other branches build and archive without deployment.

This repository: Jenkinsfile, .coveragerc, the badge/coverage scripts, and the three build entry points.

Acceptance: test an ordinary branch (no deployment), each mapped publication branch, a stale artifact, a test or coverage-floor failure, badge renderer and publisher rejection cases, and rejection of an unexpected product target path.

Cross-feature non-goals and compatibility rules

  • Generated files are outputs, not editable sources.
  • The sheet is French-first; stable machine identifiers remain ASCII where the current contracts require it.
  • Existing Roll20 attribute names, repeating section names, generated source keys, and versioned format fields are compatibility APIs. Rename them only with an explicit migration.
  • Browser/sheet workers cannot call privileged Roll20 APIs. Cross-character writes, handouts, permissions, and character creation belong in Mod scripts.
  • Chat cards communicate and calculate; they do not grant authority to mutate a target. Every Mod command independently validates payload and permissions.
  • String-presence tests prove generation shape, not Roll20 parser/rendering behavior. Interactive changes require a real Roll20 smoke test record.
  • Counts from the current pinned book are diagnostics, not permanent product requirements. Derive expectations from source inputs where possible.

Adding or porting a feature

For a new feature in this repository, update this catalogue in the same change:

  1. add or amend the feature's observable outcome, invariants, manual boundaries, implementation map, and acceptance criteria;
  2. update ARCHITECTURE.md if a boundary, data flow, persistent name, contract, build artifact, or deployment component changes;
  3. add focused automated checks and record real Roll20/browser validation or the precise untested scenario in TASKS.md;
  4. update the relevant public README and nested component guide when user instructions or component-local constraints change.

For a port to another repository, implement the Outcome, Required behavior and invariants, and Acceptance sections. The This repository paragraph is a navigation aid, not a mandated target architecture.