fvtt-mournblade-cyd-2-0/.github/copilot-instructions.md

# 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.<key>.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/<name>.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.<packname>")`. 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`:
```
<effectType>:<objectType>(<objectPath>) <value> {<label>}
```
Example: `modifier:Actor(attributs.adr) 2 {Bonus Adresse}`. Top-level effect types: `modifier`, `cost`, `provide`.

### Localization
Only `lang/fr.json` exists. Keys follow the structure `TYPES.Actor.*`, `TYPES.Item.*`, and `MOURNBLADE.ui.*`. All game text is French.

### Socket
The system registers `game.socket.on("system.fvtt-mournblade-cyd2", ...)` for GM-side operations. Socket messages are dispatched/handled in `MournbladeCYD2Utility.onSocketMesssage()` (note the triple-s typo — keep it consistent).