foundryvtt-system

FoundryVTT System Development Guide

This guide covers the fundamentals of building a game system or module for FoundryVTT v13. It provides patterns for project structure, data models, hooks, documents, settings, testing, and internationalization.

Note: This plugin is a community resource and is not affiliated with or endorsed by Foundry Gaming LLC.

System File Structure

A typical FoundryVTT system:

my-system/
+-- module/               # JavaScript source
|   +-- __tests__/        # Test files (Vitest)
|   +-- __mocks__/        # Test mocks for Foundry API
|   +-- my-system.js      # Entry point (registered in system.json)
|   +-- actor.js           # Custom Actor class
|   +-- item.js            # Custom Item class
|   +-- config.js          # System constants and lookup tables
|   +-- ...
+-- templates/            # Handlebars templates (.html)
+-- styles/               # SCSS/CSS stylesheets
+-- lang/                 # Translation files (en.json, de.json, etc.)
+-- packs/                # Compendium packs
|   +-- creatures/
|   |   +-- src/           # JSON source files (tracked in git)
|   +-- items/
|       +-- src/
+-- docs/                 # Documentation
+-- system.json           # System manifest
+-- template.json         # Data model definition

Data Model (template.json)

Defines the structure of Actor and Item data:

{
  "Actor": {
    "types": ["character", "npc"],
    "character": {
      "hp": { "value": 10, "max": 10 },
      "level": 1,
      "abilities": {
        "str": { "value": 10 },
        "dex": { "value": 10 },
        "con": { "value": 10 },
        "int": { "value": 10 },
        "wis": { "value": 10 },
        "cha": { "value": 10 }
      },
      "biography": ""
    },
    "npc": {
      "hp": { "value": 10, "max": 10 },
      "cr": 1,
      "description": ""
    }
  },
  "Item": {
    "types": ["weapon", "armor", "spell", "equipment"],
    "weapon": {
      "damage": "1d6",
      "attackBonus": 0,
      "equipped": false
    },
    "armor": {
      "ac": 10,
      "equipped": false
    },
    "spell": {
      "level": 1,
      "description": ""
    },
    "equipment": {
      "quantity": 1,
      "weight": 0,
      "description": ""
    }
  }
}