66 lines
4.3 KiB
Markdown
66 lines
4.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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`.
|