fvtt-les-heritiers/QUICK_REFERENCE.md

# Les Héritiers FoundryVTT System - Quick Reference

## Quick Start

```bash
npm install              # Install once
npm run watch           # Development watch (LESS → CSS)
npm run build           # Build once (production)
```

## System at a Glance

| Item | Details |
|------|---------|
| **ID** | `fvtt-les-heritiers` |
| **Version** | 13.0.7 |
| **Foundry** | v13+ (AppV2, DataModels) |
| **Language** | French only |
| **Architecture** | ES6 modules, Foundry TypeDataModel |

## Core Actors (2 types)

- **`personnage`** - Player Character (full biodata + core mechanics)
- **`pnj`** - NPC (same structure, simplified UI)

### Actor Data Structure
- **Characteristics** (8): agi, con, for, prec, esp, per, pres, san
- **Ranks** (4): tricherie, feerie, masque, heritage
- **Combat**: esquive, parade, initiative, corpsacorps, tir, resistances
- **Profiles** (6): aventurier, roublard, combattant, erudit, savant, gentleman + magic

## Core Items (14 types)

**Combat**: arme, protection  
**Equipment**: equipement, accessoire  
**Character Building**: competence, profil, contact, avantage, desavantage  
**Powers**: pouvoir, capacitenaturelle, atoutfeerique, fee  
**Magic**: sort  

## Project Structure

```
modules/
  ├─ heritiers-main.js       # Foundry init, hook setup
  ├─ heritiers-actor.js      # Actor class
  ├─ heritiers-item.js       # Item class
  ├─ heritiers-config.js     # HERITIERS_CONFIG (enums)
  ├─ heritiers-utility.js    # Static utilities, Handlebars helpers
  ├─ heritiers-commands.js   # Chat commands
  ├─ heritiers-combat.js     # Combat class
  ├─ models/                 # DataModels for each type
  │  └─ personnage.mjs, pnj.mjs, arme.mjs, ...
  └─ applications/sheets/    # AppV2 Sheets
     └─ personnage-sheet.mjs, arme-sheet.mjs, ...
templates/                   # 27 Handlebars templates
lang/fr.json                # Localization (minimal, type names only)
less/heritiers.less         # LESS compilation entry
styles/heritiers.css        # Compiled CSS (generated)
packs/                      # 11 LevelDB compendium packs
system.json                 # Manifest
template.json.backup        # Data schema reference
```

## Key Classes & Exports

### Actor Classes
- **`HeritiersActor`** extends `Actor`
  - Custom creation: auto-adds utility skills for `personnage`
- **PersonnageDataModel**, **PnjDataModel** extend `foundry.abstract.TypeDataModel`

### Item Classes
- **`HeritiersItem`** extends `Item`
- **14 DataModels**: ArmeDataModel, CompetenceDataModel, etc.

### Sheets (AppV2 - Foundry v13+)
- **`HeritiersPersonnageSheet`**, **`HeritiersPnjSheet`** extend ActorSheetV2
- **`HeritiersArmeSheet`**, **`HeritiersCompetenceSheet`**, etc. (14 item sheets)
- All use `HandlebarsApplicationMixin`
- Registered in `heritiers-main.js` with `foundry.documents.collections.[Actors|Items].registerSheet()`

## Adding a New Item Type

1. Add schema to `template.json.backup`
2. Create `modules/models/[typename].mjs` (DataModel)
3. Create `modules/applications/sheets/[typename]-sheet.mjs` (AppV2 Sheet)
4. Create `templates/item-[typename]-sheet.hbs` (Handlebars template)
5. Export from `modules/models/index.mjs`
6. Export from `modules/applications/sheets/_module.mjs`
7. Register in `heritiers-main.js` (+ other registrations)
8. Add to `lang/fr.json` TYPES.Item
9. Optionally: add config constants to `heritiers-config.js`

## Key Constants (heritiers-config.js)

```javascript
HERITIERS_CONFIG = {
  caracList,           // 8 characteristics
  competenceProfil,    // 6 profiles + magic
  seuilsDifficulte,    // 30-level difficulty scale
  baseTestPouvoir,     // feerie, masque, autre
  resistancePouvoir,   // physical/psychic active/passive
  typePouvoir,         // actif, passif, metamorphose
  // ... 30+ more enums
}
```

## Handlebars Template Patterns

**File Naming**:
- `actor-sheet.hbs` → Personnage sheet
- `actor-pnj-sheet.hbs` → NPC sheet
- `item-[type]-sheet.hbs` → Item sheet
- `partial-*.hbs` → Reusable components
- `chat-*-result.hbs` → Chat results
- `editor-*.hbs` → Editor components

**Data Access**:
```handlebars
{{actor.name}}                       <!-- Actor name -->
{{system.caracteristiques.agi.value}}  <!-- Nested field -->
{{#each system.items as |item key|}} <!-- Loops -->
{{#if system.magie}} ... {{/if}}     <!-- Conditionals -->
{{eq kind "physical"}}               <!-- Custom helper -->
```

**Custom Helpers** (60+):
- Comparison: `eq`, `ne`, `lt`, `gt`, `gte`, `lte`
- String: `upper`, `lower`, `upperFirst`
- Array: `includes`, `count`, `notEmpty`
- Math: `mul`, `add`, `sub`, `and`, `or`

## Localization

**Single File**: `lang/fr.json`
```json
{
  "TYPES": {
    "Actor": { "personnage": "Personnage", "pnj": "PNJ" },
    "Item": { "arme": "Arme", "competence": "Compétence", ... }
  }
}
```

**Strategy**: Minimal i18n
- Type labels in TYPES
- Field labels in DataModel schema (French initial values)
- Config constants in heritiers-config.js (French)
- Template text hardcoded (French)

**No game.i18n calls** - all text is French-only

## Dice & Combat

- **Initiative**: 1d10 (decimal)
- **Bonus/Malus**: -6 to +6
- **Roll Storage**: `HeritiersUtility.rollDataStore` (socket-aware)
- **Defender Tracking**: `HeritiersUtility.defenderStore`

## Socket Communication

**Channel**: `"system.fvtt-les-heritiers"`  
**Handler**: `HeritiersUtility.onSocketMesssage(data)`  
**Use Cases**: Roll updates, multi-client sync

## Recent Changes (v13.0.7)

- ✅ AppV2 sheet migration (from legacy v1)
- ✅ DataModels adoption
- ✅ ES6 modules (.mjs) throughout
- ✅ Jan 21: arme, competence, capacitenaturelle, pouvoir, protection updates
- ✅ Rank calculation fixes

## Common Edits

### Add a new characteristic?
1. Update `template.json.backup` → `caracteristiques`
2. Update `PersonnageDataModel` → `caracteristiques` SchemaField
3. Update `HERITIERS_CONFIG.caracList`
4. Update templates that reference characteristics

### Add a new compendium pack?
1. Add to `system.json` → `packs` array
2. Create directory in `packs/[packname]/`
3. Add `.db` file via Foundry UI or scripts

### Add a new roll type?
1. Add dialog template: `templates/roll-dialog-*.hbs`
2. Add result template: `templates/chat-*-result.hbs`
3. Add handler in `heritiers-utility.js` or `heritiers-commands.js`
4. Emit via socket if multiplayer: `game.socket.emit("system.fvtt-les-heritiers", data)`

### Change UI layout?
1. Edit `templates/actor-sheet.hbs` or `item-*.hbs`
2. Update LESS: edit `less/heritiers.less`
3. Run `npm run build` or watch with `npm run watch`
4. CSS reloads automatically via hotReload

## Testing Changes

```bash
npm run watch
# Open FoundryVTT on http://localhost:30000
# Open system's world
# Make edits (files auto-reload)
# Check browser console for errors
# Test in UI
```

## Git Workflow (Development)

```bash
git status
git add -A
git commit -m "Description of change"
git push
# Check recent commits: git log --oneline
```

## Useful Commands

```bash
# Count lines of code
wc -l modules/*.js modules/**/*.mjs

# Search for string in code
grep -r "searchterm" modules/

# List all item types
grep '"type":' packs/*/[file].db | head -20

# Check template syntax
npm run build 2>&1 | grep error
```

## Documentation

- **DEVELOPER_INSTRUCTIONS.md** - Comprehensive guide (this repo)
- **README.md** - Project overview & credits
- **system.json** - Manifest (metadata, packs, compatibility)
- **template.json.backup** - Data schema reference
- [FoundryVTT Docs](https://foundryvtt.com/articles/)
- [Les Héritiers Books](https://titam-france.fr) - Game rules

## Notes

- All code is French (variable names in French, labels in French)
- No English strings in UI
- Single language system (French)
- Heavy use of camelCase following Foundry conventions
- AppV2 is the only supported sheet architecture (v13+)