Copilot Instructions — fvtt-chroniques-de-l-etrange

FoundryVTT v13 game system for Les Chroniques de l'Étrange (Antre-Monde Éditions). The codebase is entirely in ES modules ("type": "module") bundled with esbuild. There are no tests.

Build commands

npm run build          # compile LESS → CSS and bundle src/system.js → dist/system.js
npm run build:css      # LESS only
npm run build:js       # esbuild bundle only
npm run build:watch    # rebuild on file changes
npm run build:full     # compile compendiums then build

npm run pack:compile   # compile packs-src/ → packs/ (LevelDB)
npm run pack:extract   # extract packs/ → packs-src/ (YAML source)

The built output goes to dist/system.js (sourced via the unbuilt src/system.js in system.json esmodules).

Architecture

The entry point is src/system.js, which wires up all FoundryVTT hooks (init, ready, renderChatLog, etc.).

Layer structure

Layer	Path	Purpose
Config	`src/config/`	Constants, i18n pre-localization, runtime config, settings
Data Models	`src/data/`	`TypeDataModel` subclasses defining actor/item schemas
Documents	`src/documents/`	`CDEActor`, `CDEItem`, `CDEMessage` — thin document class overrides
UI / Sheets	`src/ui/sheets/`	ApplicationV2 sheets for actors and items
UI / Apps	`src/ui/apps/`	Standalone apps: `CDELoksyuApp`, `CDETinjiApp` (singletons)
UI / Core	`src/ui/`	Rolling engine, dice registration, Handlebars helpers, initiative

Key domain concepts

Wu Xing cycle: Five aspects (metal, water, earth, fire, wood) drive all dice resolution. Each aspect maps to two d10 faces (see ASPECT_FACES in constants.js). WU_XING_CYCLE maps an active aspect to the five result categories: successes / auspicious / noxious / loksyu / tinji.
Loksyu / Tin Ji: Persistent world-level counters stored in game settings (loksyuData, tinjiData). Managed via CDELoksyuApp / CDETinjiApp singleton apps; updated from roll results in ui/apps/singletons.js.
Three Treasures (threetreasures): The character's Hei-Yang and Hei-Yin pools plus dice-level branches — used as the primary/secondary token attribute.
Magics: Five schools (internalcinnabar, alchemy, masteryoftheway, exorcism, geomancy), each with five specialities. Fully defined in MAGICS constant.

Data model pattern

All data models live in src/data/ and extend foundry.abstract.TypeDataModel. Schema fields are defined with local factory helpers (numberField, stringField, boolField, htmlField) — prefer reusing these helpers when adding new fields.

Sheet pattern

Actor and item sheets extend HandlebarsApplicationMixin(ActorSheetV2) via CDEBaseActorSheet (src/ui/sheets/actors/base.js). Key conventions:

static DEFAULT_OPTIONS with form: { submitOnChange: true } — forms auto-save on every change.
Tab state is manually restored in _onRender by iterating this.tabGroups and calling this.changeTab() (AppV2 does not persist tab state natively).
Sheet actions (create/edit/delete item, editImage) are static private methods registered in DEFAULT_OPTIONS.actions.
_prepareContext() exposes both system and systemData (same reference) for template compatibility.

Compendium source

Human-editable compendium content lives in packs-src/ as YAML. Use npm run pack:compile before building when pack content has changed, and npm run pack:extract after importing new data in Foundry.

Key conventions

All user-visible strings go through i18n with the CDE. prefix namespace. New labels must be added to lang/fr-cde.json.
Handlebars templates live in templates/ and are referenced by their full system path (systems/fvtt-chroniques-de-l-etrange/templates/...). Partials are pre-registered from TEMPLATE_PARTIALS in constants.js.
The system ID constant (SYSTEM_ID = "fvtt-chroniques-de-l-etrange") is used everywhere — never hardcode the string.
CSS is authored in LESS (css/cde-theme.less) and compiled to css/cde-theme.css. Do not edit the .css file directly.
Global macro access is via game.cde (exposes CDELoksyuApp and CDETinjiApp).
The dist/ directory is generated — do not commit it manually; it is rebuilt by npm run build.

4.3 KiB Raw Permalink Blame History