diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..d7cb652 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,105 @@ +# Copilot Instructions — fvtt-mournblade-cyd2 + +## Project overview + +This is a **FoundryVTT game system** (v13+) for the French tabletop RPG *Mournblade CYD 2.0* by Titam France/Sombres Projets. The system ID is `fvtt-mournblade-cyd2`. There is no build step — JavaScript ES modules are loaded directly by FoundryVTT. All user-visible strings are in French. + +## No build / test / lint tooling + +There is no `package.json`, `Makefile`, or test suite. Development is done by placing the repository inside FoundryVTT's `Data/systems/` directory and reloading the application. The only files the engine processes are those declared in `system.json`. + +## Architecture + +### Entry point and lifecycle + +`modules/mournblade-cyd2-main.js` is the sole ES module declared in `system.json`. It: +- Registers all document classes and actor/item sheets in the `init` hook +- Calls `MournbladeCYD2Utility.init()`, `MournbladeCYD2Automation.init()`, `MournbladeCYD2TokenHud.init()` in `init` +- Loads compendium skills into created actors, imports a default scene, and posts a welcome message in `ready` +- Exposes `game.system.mournbladecyd2` with `{ MournbladeCYD2Utility, MournbladeCYD2Automation, config: MOURNBLADECYD2_CONFIG }` + +### Module responsibilities + +| File | Class | Role | +|---|---|---| +| `mournblade-cyd2-actor.js` | `MournbladeCYD2Actor` | Extends `Actor`. All game logic: stat derivation, weapon preparation, roll helpers, adversity/soul management | +| `mournblade-cyd2-actor-sheet.js` | `MournbladeCYD2ActorSheet` | Extends `foundry.appv1.sheets.ActorSheet`. Sheet for `personnage` | +| `mournblade-cyd2-creature-sheet.js` | `MournbladeCYD2CreatureSheet` | Sheet for `creature` (NPC/monster) | +| `mournblade-cyd2-item.js` | `MournbladeCYD2Item` | Extends `Item`. Assigns default icon per type on creation | +| `mournblade-cyd2-item-sheet.js` | `MournbladeCYD2ItemSheet` | Single sheet class for all item types | +| `mournblade-cyd2-utility.js` | `MournbladeCYD2Utility` | Static utility class: Handlebars helpers, chat listeners, compendium loading, roll execution, socket messages | +| `mournblade-cyd2-roll-dialog.js` | `MournbladeCYD2RollDialog` | Extends `Dialog`. Roll configuration dialog (choose d10/d20, modifier, difficulty) | +| `mournblade-cyd2-combat.js` | `MournbladeCYD2Combat` | Extends `Combat`. Custom initiative via `actor.getInitiativeScore()` | +| `mournblade-cyd2-automation.js` | `MournbladeCYD2Automation` | Parses automation expressions on items, validates on-drop requirements | +| `mournblade-cyd2-hud.js` | `MournbladeCYD2TokenHud` | Extends TokenHUD with adversity (bleue/rouge/noire) sub-menu | +| `mournblade-cyd2-config.js` | `MOURNBLADECYD2_CONFIG` | Exported plain object with all select-option lists (difficulty, ranges, bonus/malus, etc.) | +| `mournblade-cyd2-commands.js` | `MournbladeCYD2Commands` | Chat command handler (currently stubbed) | +| `macro-replace-images.js` | — | Standalone utility macro for bulk image replacement on items/actors | + +### Data model (template.json) + +**Actor types:** +- `personnage` — player character; templates `biodata` + `core` +- `creature` — NPC/monster; templates `core` + `biodata` + `ressources` + +**Core attributes** (all at `system.attributs..value`): +`adr` (Adresse), `pui` (Puissance), `cla` (Clairvoyance), `pre` (Présence), `tre` (Trempe) + +**Key actor resources:** +- `system.sante.vigueur` / `.etat` / `.nbcombativite` — health track +- `system.ame.nbame` / `.max` / `.etat` / `.seuilpouvoir` — soul points +- `system.bonneaventure.base` / `.actuelle` — Bonne Aventure (luck resource) +- `system.adversite.bleue` / `.rouge` / `.noire` — three adversity tracks +- `system.balance.loi` / `.chaos` / `.aspect` / `.marge` — Law/Chaos alignment +- `system.combat.*` — initiative/defense/attack bonuses, mounted state + +**Item types:** `talent`, `historique`, `profil`, `competence`, `arme`, `protection`, `monnaie`, `equipement`, `ressource`, `don`, `pacte`, `rune`, `runeeffect`, `tendance`, `traitchaotique`, `traitespece` + +All item data lives under `item.system.*`. Equipment items share the `basequip` template (`prixpo`, `prixca`, `prixsc`, `rarete`, `quantite`, `equipped`). Items that support automation have `system.isautomated` and `system.automations[]`. `competence` items have `system.predilections[]` (an array of predilection objects used for reroll bonuses, handled in the item sheet and chat listeners). + +**Other actor fields:** `system.subactors[]` — an array for linked sub-actors (defined in the `core` template but managed at the sheet level). + +## Key conventions + +### Foundry API usage +- Actor/item data is always accessed via `actor.system.*` and `item.system.*` (Foundry v10+ data model). +- Deep clone with `foundry.utils.duplicate()`, merge with `foundry.utils.mergeObject()`. +- Render Handlebars templates with `foundry.applications.handlebars.renderTemplate(path, data)`. +- Enrich HTML (rich text fields) with `foundry.applications.ux.TextEditor.implementation.enrichHTML(text, { async: true })`. +- Register/unregister sheets via `foundry.documents.collections.Actors` and `foundry.documents.collections.Items`. + +### Roll data pattern +Rolls pass a `rollData` plain object through the dialog, the roll function, and into the chat message. The object is stored on chat messages as a flag: `message.getFlag("world", "mournblade-cyd2-roll")`. Chat click handlers retrieve this flag to re-roll or apply damage. + +### Sheet `getData()` pattern +Both actor sheets build a `formData` object in `getData()` that flattens actor data for the template — calling `this.actor.getWeapons()`, `getTalents()`, etc. (all defined on the Actor class) and passing `game.system.mournbladecyd2.config` as `config`. Always add new derived/display data in `getData()`, not directly in templates. + +### Handlebars templates +- Templates live in `templates/` and are path-referenced as `systems/fvtt-mournblade-cyd2/templates/.html`. +- Partials must be listed in `MournbladeCYD2Utility.preloadHandlebarsTemplates()` to work as `{{> partial-name}}`. +- Custom Handlebars helpers are registered in `MournbladeCYD2Utility.init()`: `count`, `includes`, `upper`, `lower`, `upperFirst`, `notEmpty`, `mul`. + +### Assets and paths +- All asset references inside JS/HTML use the runtime path `systems/fvtt-mournblade-cyd2/assets/...`. +- Item default icons are defined in `defaultItemImg` in `mournblade-cyd2-item.js`, keyed by item type. + +### Compendium access +Load compendium contents with `MournbladeCYD2Utility.loadCompendium("fvtt-mournblade-cyd2.")`. Pack names match the `name` fields in `system.json` (e.g., `skills`, `armes`, `pnj-creatures`). + +### Automation system +The `automation` item template (`system.isautomated`, `system.automations[]`) supports three **event types** processed by `MournbladeCYD2Automation.processAutomations(event, item, actor)`: +- `on-drop` — validates attribute/competence prerequisites when an item is dropped onto an actor +- `prepare-roll` — modifies roll data before a roll is made +- `bonus-permanent` — applies a standing bonus (e.g., `bonusname: "bonus-defensif"`) checked in `actor.getBonusDefenseFromTalents()` + +Each automation entry's effect uses the expression format parsed by XRegExp in `mournblade-cyd2-automation.js`: +``` +:() {