# Copilot Instructions for foundryvtt-mgt2

## Project Overview

This is a [Foundry VTT](https://foundryvtt.com) game system implementing Mongoose Publishing Traveller 2nd Edition (MGT2). It runs entirely in the browser within the FoundryVTT platform — there is no Node.js runtime or backend server to develop against.

The distributed entry point is `mgt2.bundle.js` (pre-bundled from `src/`). CSS is compiled from `src/sass/` to `styles/mgt2.min.css`. No build tooling (package.json, webpack, etc.) is committed to the repo, so bundling is done externally.

## Architecture

### Entry Point & Initialization

`src/module/core.js` is the main module. It runs in the FoundryVTT `init` hook and:
- Registers all Actor/Item document classes
- Registers all TypeDataModel schemas (`datamodels.js`)
- Registers sheets (actor and item)
- Preloads Handlebars templates

### Document Classes

| Class | File | Purpose |
|---|---|---|
| `TravellerActor` | `actors/actor.js` | Extends `Actor`; delegates character logic to `ActorCharacter` |
| `ActorCharacter` | `actors/character.js` | Static methods for character-specific actor logic |
| `TravellerItem` | `item.js` | Extends `Item` |
| `MGT2Combatant` | `actors/actor.js` | Extends `Combatant` |

### Sheets

- **`TravellerActorSheet`** (`actors/character-sheet.js`) — character sheet. Uses `templates/actors/actor-sheet.html`. `getData()` returns `context.data` (not the full context).
- **`TravellerItemSheet`** (`item-sheet.js`) — item sheet. Template is dynamically resolved as `templates/items/{item.type}-sheet.html`.
- **`VehiculeSheet`** (`actors/vehicule-sheet.js`) — vehicle actor sheet.

### Data Models

All schemas are TypeDataModels defined in `src/module/datamodels.js`. Actor types: `character`, `vehicule`. Item types: `contact`, `career`, `disease`, `item`, `equipment`, `talent`, `armor`, `weapon`, `computer`, `container`, `species`.

The `CharacterData` model uses a helper `createCharacteristicField()` for the 12 characteristics (strength, dexterity, endurance, intellect, education, social, morale, luck, sanity, charm, psionic, other). Each characteristic has `.value`, `.max`, and `.dm` fields.

### Config Constants

`src/module/config.js` exports `MGT2` — a set of frozen objects mapping internal keys to i18n strings (e.g., `MGT2.Difficulty.Average`). Accessible at runtime via `CONFIG.MGT2`.

### Templates

Handlebars templates live in `templates/`. Paths always use the FoundryVTT-relative prefix `systems/mgt2/templates/...`. Partial templates (used across sheets) live in `templates/items/parts/`.

### Styles & Theming

SASS source is in `src/sass/`. The active theme is a CSS class applied to every sheet element — e.g. `["mgt2", game.settings.get("mgt2", "theme"), "sheet", ...]`. Available themes: `black-and-red`, `mwamba`, `blue`.

### Localization

All user-facing strings go through `game.i18n.localize()`. Keys follow the pattern `MGT2.Section.Key`. String definitions are in `lang/en.json` and `lang/fr.json`.

### Chat Cards

`ChatHelper` (`chatHelper.js`) hooks into `renderChatMessage` to attach button listeners. Chat card templates are in `templates/chat/`.

## Key Conventions

- **`getData()` returns `context.data`** — the character sheet's `getData()` calls `super.getData()` then returns `context.data`, not `context` itself. Keep this pattern for character sheet overrides.
- **Actor logic delegation** — `TravellerActor` is thin; type-specific logic lives in static methods on `ActorCharacter`. Follow this pattern for new actor types.
- **Settings keys** — always namespaced as `game.settings.get("mgt2", "settingName")`. Settings are registered in `settings.js`.
- **`vehicule` spelling** — the actor type and related files use the French spelling `vehicule` (not `vehicle`). Do not rename.
- **Template paths** — always use the full FoundryVTT path `systems/mgt2/templates/...` in JS; never relative paths.
- **i18n keys in config** — `config.js` stores i18n key strings (not translated text). Actual translation happens at render time via `game.i18n.localize()`.
- **`life` is the primary token attribute** — configured in `system.json` as `primaryTokenAttribute: "life"`.