Chapitre 1 - Le Manifeste system.json

Rôle du system.json

Le fichier system.json est le manifeste de votre système. C'est le premier fichier lu par FoundryVTT lors du chargement. Il définit :

Métadonnées : nom, version, auteurs, description
Fichiers à charger : scripts JavaScript, feuilles de style
Types de documents : sous-types d'Actor et d'Item supportés
Compendiums : packs de données inclus
Compatibilité : versions de FoundryVTT supportées

💡 Emplacement

Le fichier system.json doit être à la racine du dossier de votre système, par exemple : Data/systems/mon-systeme/system.json

Champs obligatoires

Ces champs sont requis pour que votre système soit reconnu :

Champ	Type	Description
`id`	string	Identifiant unique. Doit correspondre au nom du dossier. Caractères : `a-z`, `0-9`, `-`
`title`	string	Nom affiché dans l'interface Foundry
`version`	string	Version au format SemVer (ex: `1.0.0`)
`compatibility`	object	Versions de FoundryVTT supportées

{
  "id": "mon-systeme",
  "title": "Mon Super Système de JDR",
  "version": "1.0.0",
  "compatibility": {
    "minimum": "13",
    "verified": "13"
  }
}

⚠️ Important

L'id doit correspondre exactement au nom du dossier contenant votre système. Si votre dossier s'appelle mon-systeme, l'id doit être "mon-systeme".

Champs optionnels importants

Champ	Type	Description
`description`	string	Description du système
`authors`	array	Liste des auteurs avec `name`, `url`, `email`, `discord`
`url`	string	URL du projet (GitHub, site web)
`manifest`	string	URL vers le manifeste pour les mises à jour automatiques
`download`	string	URL de téléchargement du zip
`license`	string	Licence ou URL vers le fichier de licence
`bugs`	string	URL pour signaler des bugs

{
  "id": "mon-systeme",
  "title": "Mon Super Système de JDR",
  "description": "Un système complet pour jouer à Mon JDR préféré",
  "version": "1.0.0",
  "authors": [
    {
      "name": "Mon Nom",
      "url": "https://mon-site.com",
      "discord": "monpseudo#1234"
    }
  ],
  "url": "https://github.com/moncompte/mon-systeme",
  "manifest": "https://raw.githubusercontent.com/moncompte/mon-systeme/main/system.json",
  "download": "https://github.com/moncompte/mon-systeme/releases/download/v1.0.0/mon-systeme.zip",
  "license": "LICENSE",
  "bugs": "https://github.com/moncompte/mon-systeme/issues"
}

Section compatibility

Cette section définit les versions de FoundryVTT avec lesquelles votre système fonctionne.

{
  "compatibility": {
    "minimum": "13.347",
    "verified": "13",
    "maximum": "13"
  }
}

Champ	Effet
`minimum`	Le système ne se chargera pas si la version est inférieure
`verified`	Affiche un indicateur vert dans le setup
`maximum`	Empêche le chargement sur des versions plus récentes (rare)

💡 Conseil

Utilisez "minimum": "13" et "verified": "13" pour cibler la dernière version majeure. Mettez à jour verified après chaque test sur une nouvelle version de FoundryVTT.

Section documentTypes

C'est ici que vous déclarez les sous-types de documents supportés par votre système. C'est une section cruciale introduite dans FoundryVTT v11.

Syntaxe de base

{
  "documentTypes": {
    "Actor": {
      "character": {
        "htmlFields": ["biography"]
      },
      "npc": {
        "htmlFields": ["biography", "notes"]
      },
      "monster": {}
    },
    "Item": {
      "weapon": {
        "htmlFields": ["description"]
      },
      "armor": {
        "htmlFields": ["description"]
      },
      "spell": {
        "htmlFields": ["description"]
      },
      "feat": {
        "htmlFields": ["description"]
      }
    }
  }
}

Options par type

Option	Type	Description
`htmlFields`	string[]	Chemins des champs contenant du HTML enrichi
`filePathFields`	object	Chemins des champs contenant des chemins de fichiers

Types de documents supportés

Actor - Personnages, PNJ, créatures
Item - Objets, sorts, capacités
ActiveEffect - Effets actifs
ChatMessage - Messages de chat
JournalEntryPage - Pages de journal
RegionBehavior - Comportements de région

💡 Lien avec les DataModels

Les types déclarés ici doivent être associés à des DataModels dans votre code :

// Dans le hook init
CONFIG.Actor.dataModels = {
  character: CharacterData,  // Correspond à "character" dans documentTypes
  npc: NPCData,              // Correspond à "npc" dans documentTypes
  monster: MonsterData       // Correspond à "monster" dans documentTypes
};

Section packs (Compendiums)

Les compendiums sont des collections de documents préchargées : monstres, sorts, équipements, etc.

{
  "packs": [
    {
      "name": "monsters",
      "label": "Monstres de Base",
      "system": "mon-systeme",
      "path": "packs/monsters",
      "type": "Actor",
      "ownership": {
        "PLAYER": "OBSERVER",
        "ASSISTANT": "OWNER"
      }
    },
    {
      "name": "spells",
      "label": "Sorts",
      "system": "mon-systeme",
      "path": "packs/spells",
      "type": "Item"
    },
    {
      "name": "equipment",
      "label": "Équipement",
      "system": "mon-systeme",
      "path": "packs/equipment",
      "type": "Item",
      "private": true
    }
  ]
}

Champs de pack

Champ	Type	Description
`name`	string	Identifiant unique du pack
`label`	string	Nom affiché dans l'interface
`path`	string	Chemin relatif vers le dossier des données
`type`	string	`Actor`, `Item`, `JournalEntry`, `RollTable`, `Scene`, `Macro`, `Playlist`
`system`	string	ID du système propriétaire
`private`	boolean	Si `true`, masqué par défaut aux joueurs
`ownership`	object	Permissions par rôle

Organiser les packs avec packFolders

{
  "packFolders": [
    {
      "name": "Créatures",
      "color": "#8B0000",
      "packs": ["monsters", "npcs"]
    },
    {
      "name": "Objets",
      "color": "#006400",
      "packs": ["equipment", "spells"],
      "folders": [
        {
          "name": "Magiques",
          "color": "#4B0082",
          "packs": ["magic-items"]
        }
      ]
    }
  ]
}

Autres sections utiles

esmodules et styles

Fichiers JavaScript et CSS à charger :

{
  "esmodules": ["mon-systeme.mjs"],
  "styles": ["mon-systeme.css"]
}

languages

Fichiers de traduction :

{
  "languages": [
    {
      "lang": "en",
      "name": "English",
      "path": "lang/en.json"
    },
    {
      "lang": "fr",
      "name": "Français",
      "path": "lang/fr.json"
    }
  ]
}

grid

Configuration par défaut de la grille :

{
  "grid": {
    "distance": 5,
    "units": "ft"
  }
}

primaryTokenAttribute

Attribut affiché sur la barre principale des tokens :

{
  "primaryTokenAttribute": "attributes.hp"
}

socket

Activer la communication WebSocket :

{
  "socket": true
}

Exemple complet minimal

Voici un manifeste minimal mais fonctionnel pour démarrer :

{
  "id": "mon-systeme",
  "title": "Mon Système de JDR",
  "description": "Un système personnalisé pour FoundryVTT",
  "version": "1.0.0",
  "compatibility": {
    "minimum": "13",
    "verified": "13"
  },
  "authors": [
    {
      "name": "Votre Nom"
    }
  ],
  "esmodules": ["mon-systeme.mjs"],
  "styles": ["mon-systeme.css"],
  "documentTypes": {
    "Actor": {
      "character": {
        "htmlFields": ["biography"]
      },
      "npc": {}
    },
    "Item": {
      "item": {
        "htmlFields": ["description"]
      },
      "weapon": {
        "htmlFields": ["description"]
      },
      "spell": {
        "htmlFields": ["description"]
      }
    }
  },
  "languages": [
    {
      "lang": "en",
      "name": "English",
      "path": "lang/en.json"
    }
  ],
  "grid": {
    "distance": 5,
    "units": "ft"
  },
  "primaryTokenAttribute": "attributes.hp"
}

Erreurs courantes

⚠️ Validation du manifeste

FoundryVTT valide votre manifeste au chargement. Voici les erreurs les plus fréquentes :

ID invalide
L'id doit correspondre exactement au nom du dossier
Version manquante
Le champ version est obligatoire
Compatibility manquante
minimum doit être défini dans compatibility
Chemins inexistants
Les fichiers référencés (esmodules, styles) doivent exister
Types non enregistrés
Les types dans documentTypes doivent avoir un DataModel associé dans le code
JSON invalide
Vérifiez les virgules manquantes ou en trop !

💡 Astuce de débogage

Utilisez un validateur JSON en ligne comme JSONLint pour vérifier la syntaxe de votre fichier.

🎯 Exercice : Créez votre premier system.json

Créez un manifeste pour un système de JDR fictif avec ces caractéristiques :

Nom : "Héros & Dragons Lite"
ID : hd-lite
Types d'Actor : hero, monster
Types d'Item : weapon, armor, skill, spell
Un compendium de monstres
Support pour le français et l'anglais

Voir la solution

{
  "id": "hd-lite",
  "title": "Héros & Dragons Lite",
  "description": "Version simplifiée de Héros & Dragons pour FoundryVTT",
  "version": "1.0.0",
  "compatibility": {
    "minimum": "13",
    "verified": "13"
  },
  "authors": [
    {
      "name": "Votre Nom"
    }
  ],
  "esmodules": ["hd-lite.mjs"],
  "styles": ["hd-lite.css"],
  "documentTypes": {
    "Actor": {
      "hero": {
        "htmlFields": ["biography"]
      },
      "monster": {
        "htmlFields": ["description", "tactics"]
      }
    },
    "Item": {
      "weapon": {
        "htmlFields": ["description"]
      },
      "armor": {
        "htmlFields": ["description"]
      },
      "skill": {
        "htmlFields": ["description"]
      },
      "spell": {
        "htmlFields": ["description"]
      }
    }
  },
  "packs": [
    {
      "name": "monsters",
      "label": "Monstres",
      "system": "hd-lite",
      "path": "packs/monsters",
      "type": "Actor"
    }
  ],
  "languages": [
    {
      "lang": "en",
      "name": "English",
      "path": "lang/en.json"
    },
    {
      "lang": "fr",
      "name": "Français",
      "path": "lang/fr.json"
    }
  ],
  "grid": {
    "distance": 1.5,
    "units": "m"
  },
  "primaryTokenAttribute": "attributes.hp"
}