fvtt-les-heritiers/QUICK_REFERENCE.md

Les Héritiers FoundryVTT System - Quick Reference

Quick Start

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)

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:

{{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

{
  "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

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)

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

Useful Commands

# 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
• Les Héritiers Books - 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+)