# Vermine 2047 — Copilot Instructions

## Build & Development

```bash
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`.