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).