bol/DATAMODELS_GUIDE.md

# Guide d'utilisation des DataModels BoL

## Exemples d'utilisation

### Accès aux données d'un acteur

```javascript
// Character
const character = game.actors.getName("Mon Héros");
console.log(character.system.attributes.vigor.value);
console.log(character.system.resources.hp.value);
console.log(character.system.xp.total);

// Encounter
const npc = game.actors.getName("Gobelin");
console.log(npc.system.chartype); // "tough"
console.log(npc.system.isundead);

// Horde
const horde = game.actors.getName("Horde de Zombies");
console.log(horde.system.hordesize);
console.log(horde.system.hasdamagerule);

// Vehicle
const ship = game.actors.getName("Navire Pirate");
console.log(ship.system.attributes.hull.value);
console.log(ship.system.vehicletype); // "boat"
```

### Accès aux données d'un item

```javascript
// Item (équipement)
const sword = game.items.getName("Épée");
console.log(sword.system.properties.weapon);
console.log(sword.system.quantity);
console.log(sword.system.worn);

// Feature (capacité)
const trait = game.items.getName("Vision nocturne");
console.log(trait.system.rank);
console.log(trait.system.description);
```

### Modification des données

```javascript
// Modifier les HP d'un personnage
await actor.update({
  "system.resources.hp.value": 10
});

// Modifier plusieurs valeurs en une fois
await actor.update({
  "system.attributes.vigor.value": 3,
  "system.attributes.agility.value": 2,
  "system.resources.hp.max": 15
});

// Modifier la quantité d'un item
await item.update({
  "system.quantity": 5,
  "system.worn": true
});
```

### Création d'acteurs avec DataModels

```javascript
// Créer un personnage
await Actor.create({
  name: "Nouveau Héros",
  type: "character",
  system: {
    chartype: "player",
    attributes: {
      vigor: { value: 2 },
      agility: { value: 1 },
      mind: { value: 0 },
      appeal: { value: 1 }
    },
    resources: {
      hp: { value: 10, max: 10 },
      hero: { value: 5, max: 5 }
    }
  }
});

// Créer une horde
await Actor.create({
  name: "Horde d'Orcs",
  type: "horde",
  system: {
    hordesize: 20,
    hordebasehp: 5,
    attributes: {
      vigor: { value: 2 },
      agility: { value: 1 }
    }
  }
});
```

### Création d'items avec DataModels

```javascript
// Créer une arme
await Item.create({
  name: "Hache de bataille",
  type: "item",
  system: {
    category: "weapon",
    quantity: 1,
    properties: {
      weapon: true,
      melee: true,
      "2H": true
    }
  }
});

// Créer un trait
await Item.create({
  name: "Berserker",
  type: "feature",
  system: {
    rank: 2,
    category: "trait",
    description: "<p>Rage au combat...</p>"
  }
});
```

## Ajout de méthodes personnalisées (Évolution future)

Les DataModels permettent d'ajouter des méthodes personnalisées. Exemple à ajouter dans `character.mjs` :

```javascript
export default class BoLCharacterDataModel extends foundry.abstract.TypeDataModel {
  // ... defineSchema ...
  
  /**
   * Calcul automatique des données dérivées
   */
  prepareDerivedData() {
    super.prepareDerivedData();
    
    // Calculer HP max basé sur Vigor
    const hpMax = 10 + (this.attributes.vigor.value * 2);
    if (this.resources.hp.max !== hpMax) {
      this.resources.hp.max = hpMax;
    }
    
    // Calculer la défense
    const def = this.attributes.agility.value + this.aptitudes.def.value;
    if (this.aptitudes.def.value !== def) {
      this.aptitudes.def.value = def;
    }
  }
  
  /**
   * Vérifier si le personnage est KO
   */
  isKnockedOut() {
    return this.resources.hp.value <= 0;
  }
  
  /**
   * Appliquer des dégâts
   */
  async applyDamage(amount) {
    const newHP = Math.max(0, this.resources.hp.value - amount);
    await this.parent.update({
      "system.resources.hp.value": newHP
    });
  }
}
```

## Validation des données

Les DataModels valident automatiquement les données :

```javascript
// ❌ Cette tentative échouera (vigor.value doit être un integer)
await actor.update({
  "system.attributes.vigor.value": "trois" // Erreur !
});

// ✅ Valide
await actor.update({
  "system.attributes.vigor.value": 3
});

// ❌ Cette tentative échouera (vigor.value max: 5)
await actor.update({
  "system.attributes.vigor.value": 10 // Erreur si max est 5 !
});
```

## Migration des données existantes

Les données existantes (créées avec template.json) restent compatibles car la structure est identique. Aucune migration de données n'est nécessaire.

## Debugging

Pour inspecter la structure d'un DataModel :

```javascript
// Afficher le schéma du DataModel
console.log(game.bol.models.BoLCharacter.defineSchema());

// Afficher les données d'un acteur
const actor = game.actors.getName("Mon Héros");
console.log(actor.system); // Instance du DataModel
console.log(actor.system.toObject()); // Données brutes
```

## Ressources

- [Foundry DataModel Documentation](https://foundryvtt.com/api/classes/foundry.abstract.DataModel.html)
- [Data Fields Reference](https://foundryvtt.com/api/modules/foundry.data.fields.html)
- Exemples dans `fvtt-cthulhu-eternal` et `fvtt-mournblade`