vermine2047/.github/copilot-instructions.md

Vermine 2047 — Copilot Instructions

Build & Development

npm run watch          # Watch SCSS + templates, proxy Foundry at localhost:30000 (requires Foundry running)
npm run buildStyle     # Compile SCSS once to css/vermine2047.css
npm run pullYAMLtoLDB  # Build LevelDB compendium packs from src/packs/ YAML → packs/
npm run pushLDBtoYAML  # Extract LevelDB packs to editable YAML in src/packs/
npx eslint module/     # Lint JavaScript (ESLint configured in .eslintrc.js)

There are no automated tests. Use npm run watch during development to live-reload SCSS and Handlebars templates via browser-sync.

Architecture

This is a FoundryVTT game system (system.json → system ID vermine2047), compatible with Foundry v11–v14. It implements the French post-apocalyptic TTRPG Vermine 2047.

Entry point: module/vermine2047.mjs — loaded as an ES module. On the init hook it registers custom document classes, sheet classes, combat classes, Handlebars helpers, settings, hooks, and preloads templates.

Actor types (4): character, npc, group, creature Item types (12): item, weapon, defense, vehicle, ability, specialty, background, trauma, evolution, rumor, target, rite

Key source files (module/system/):

File	Role
config.mjs	All game constants (CONFIG.VERMINE) — abilities, skills, totems, threat/role/pattern levels, traits, damage types
roll.mjs	VermineUtils class — d10 dice pool system with success counting, totem mechanics, rerolls, Dice So Nice integration
fight.mjs	Confrontation system (VermineFight), plus VermineCombat, VermineCombatant, VermineCombatTracker
group-link.mjs	GroupLink — bidirectional sync of members/encounters between group actors and character/NPC actors via Foundry hooks
hooks.mjs	All Foundry hook registrations (chat messages, hotbar drop, combat, preCreate, Dice So Nice)
settings.mjs	System settings (game mode: survie/cauchemar/apocalypse)
handlebars-manager.mjs	Template preloading paths + all Handlebars helpers (level config lookups, math, conditionals)
effects.mjs	Active effect management
dialogs/rollDialog.mjs	Advanced roll dialog (ability/skill selection, difficulty, totems, specialties, assist/pool bonuses)
applications.mjs	TotemPicker and TraitSelector applications

Data model: template.json defines the Actor/Item schemas (Foundry's template system). Derived data is computed in prepareDerivedData() in module/documents/actor.mjs and module/documents/item.mjs.

Sheet inheritance: VermineActorSheet (base) → VermineCharacterSheet, VermineNpcSheet, VermineGroupSheet, VermineCreatureSheet. Sheets expose CONFIG.VERMINE as context.config in template data.

Compendium packs: Stored in packs/ as LevelDB databases. Edit source data in src/packs/ as YAML, then npm run pullYAMLtoLDB to build. The CI release workflow runs this automatically.

Key Conventions

• All .mjs files: ES module syntax only. Foundry globals (game, Hooks, CONFIG, Actor, Item, ChatMessage, Roll, Handlebars, renderTemplate, foundry) are available but declared as readonly globals in .eslintrc.js.
• Code language: Source code and comments are in French. UI strings in lang/fr.json and lang/en.json. Use game.i18n.localize() for all user-visible text.
• Template naming: Actor sheets at templates/actor/actor-{type}-sheet.hbs, item sheets at templates/item/item-{type}-sheet.html (note: item sheets use .html, everything else uses .hbs). Chat card templates at templates/item/chatCards/{type}.hbs.
• Dice system: d10 pools with success counting (result ≥ difficulty). Totem dice (human/adapted) count double on success. Formula syntax: {N}d10cs>={threshold}[label]. Totem dice: (1d10cs>={threshold}[totem_label]*2).
• CSS: SCSS sources in scss/ compile to css/vermine2047.css. Organized by concern: _app.scss, item-sheet.scss, roll.scss, dialog.scss, etc.
• Data tools: The pushLDBtoYAML / pullYAMLtoLDB scripts use @foundryvtt/foundryvtt-cli to convert between LevelDB packs and editable YAML. When adding pack content, edit YAML in src/packs/ then rebuild.
• Actor updates: Use actor.update({...}) with dot-notation paths (e.g., 'system.adaptation.totems.human.value'). The GroupLink hooks system automatically syncs group memberships on actor changes.
• New template partials: Must be listed in preloadHandlebarsTemplates() in handlebars-manager.mjs for pre-compilation.
• Full architecture documentation: See docs/technical/ARCHITECTURE.md.