Introduction to System Development

Overview

This page provides an overview and tutorial of the basic steps required to create an entire Game System from scratch as a module which can be used for your homebrew games or shared with other players.

As an example of a fairly feature-complete game system implementation - please feel free to examine the D&D5e system which has open source code: https://github.com/foundryvtt/dnd5e

Before you Begin

Game system development in Foundry Virtual Tabletop is both rewarding and challenging. If you are considering this process, we encourage you to consider the following advice:

• Building a game system in FVTT requires a few skills: at least some basic knowledge of JavaScript, HTML, and CSS are required. You do not need to be an expert web developer, but understanding the basics of these languages is critical.
• The development process will (probably) take longer than you think. Even game systems that seem simple or basic often have underlying portions of game mechanics which are overlooked. Building a system does not take days; it will certainly take weeks, and in some cases for more complex systems, months to develop. Try to remain focused on the long-term objective and do not let slow progress in the short term discourage you.
• Make progress one piece at a time. A game system is comprised of many component parts both within and outside of Foundry VTT. We recommend starting with the data model in the template.json file - but don't worry about adding every attribute at first - you can always expand the data model later. Consider starting with a simple model which captures the minimum and most important pieces of Actor or Item data. Breaking your system down into smaller pieces will make the construction process easier and less overwhelming.
• Consider using the "Simple Worldbuilding" system as a stop-gap while your own system is still under development. This will allow you and your players to enjoy using the Virtual Tabletop while you work on completing your own system. When the time comes, the data for your World can be moved to your completed system.

System File Structure

Each game system is a subdirectory within the {userData}/Data/systems path of your Foundry Virtual Tabletop user data location. When developing a new system, we recommend creating your git repository directly within this location for ease of development and testing. Within this directory there are two required files: system.json and template.json which are each explained below. You are free to use your own naming conventions for subdirectories and files within your game system, but we encourage you to use lower-case hyphen-separated file and folder names as a best practice.

A standard example file structure for a minimal system might look like this:

{userData}/Data/systems/mysystem/
system.json
template.json
scripts/
	system-script.js
	system-module.mjs
styles/
	system-styles.css
packs/
	monsters/
	items/
lang/
	en.json

There are three ways to share a created system with others:

1. Manual Install: You may package the system directory directly into a .zip file which users can extract within their own systems folder.
2. Manifest Install: Instead of transacting the .zip file directly, you can host that file in a publicly accessible location and provide users with the URL to the system manifest file, which can automate the installation process.
3. Foundry Package Browser: You can also configure your system to appear within the in-app system browser which will allow Foundry VTT users to install your system with a single click. This requires the package to be submitted to our website listing.

The System Manifest

Each game system must include a system.json file which provides the system specification. This file is required and must be included at the root level of your system folder. The system folder itself must match the "id" attribute designated within the specification file. For example, if we create a game system with the name mysystem, then we would create the file {userData}/Data/systems/mysystem/system.json.

{
  "id": "mysystem",
  "title": "Minimal World Building",
  "description": "A human-readable description of your system.",
  "version": "1.0.0",
  "compatibility": {
    "minimum": "10",
    "verified": "11",
    "maximum": "11"
  },
  "authors": [
    {
      "name": "me",
      "url": "YOUR WEBSITE ADDRESS HERE",
	  "email": "YOUR EMAIL ADDRESS HERE",
	  "discord": "YOUR DISCORD USERNAME HERE"
    }
  ],
  "scripts": [
    "scripts/system-script-1.js",
    "scripts/system-script-2.js"
  ],
  "esmodules": [
    "scripts/system-module-1.mjs"
  ],
  "styles": [
    "styles/system-styles-1.css",
    "styles/system-styles-2.css"
  ],
  "packs": [
    {
      "name": "monsters",
      "label": "My Monsters",
      "type": "Actor"
    },
    {
      "name": "items",
      "label": "My Items",
      "type": "Item"
    }
  ],
"languages": [
    {
      "lang": "en",
      "name": "English",
      "path": "lang/en.json"
    }
  ],
  "socket": false,
  "initiative": "1d20",
  "gridDistance": 10,
  "gridUnits": "ft",
  "primaryTokenAttribute": "resources.health",
  "secondaryTokenAttribute": "resources.power",
  "url": "https://your/hosted/system/repo/",
  "background": "systems/mysystem/assets/splash.webp",
  "manifest": "https://your/hosted/system/repo/system.json",
  "download": "https://your/packaged/download/archive.zip"
}

"compatibility": {
	"minimum": 9,
	"verified": "11"
	"maximum": "11"
}

You can learn more about the fields supported in a package manifest file on the BasePackage and BaseSystem API documentation pages.

The Data Template

In addition to the System Specification file described above, each game system must include a Data Template file named template.json at the root-level of the system folder. For example, if we create a game system with the name mysystem, then we would create and include the file {userData}/Data/systems/mysystem/template.json.

The data template defines a data model which is used by Actor and Item documents within this game system. Normally, Documents in Foundry Virtual Tabletop have strictly defined data schemas - but the system template.json file allows for game systems to extend that schema to contain additional system-specific data attributes.

You can learn more about Data Models and how they work in our article on System Data Models.

The basic structure of the data template provides top-level objects which define schema for each of the Actor and Item document types. Within a single document block, the following keys are supported:

types

An array of string sub-types for different varieties of Actor or Item document which may be used. Each document type can have its own different schema.

templates

An object of named data templates which define modular and reusable sets of fields which can be included in the schema for multiple types. Consider defining a named template for sets of attributes which are reused across multiple types of Actor or Item documents.

{type}

An object block for each sub-type which defines their unique attributes as well as any included template blocks. For attributes which are unique to a single type - you can declare those attributes directly within this block without the need to define a template.

Fields within the data model may have any of the primitive types of string, number, or boolean, or provide an inner Array or Object structure. The provided value defines both the default value for new documents as well as the data type for the field. here is no limitation on the depth or structure of the template - however we encourage logical grouping of similarly themed attributes within named objects as this tends to help with organization and maintainability.

The following provides an example template.json file which uses these tools to define a system template that includes three Actor types: hero, pawn, and villain - as well as two Item types: weapon, and spell. Note how certain templates like resources are included for each Actor type, while certain actor types have additional attributes which only apply to that type.

{
"Actor": {
  "types": ["hero", "pawn", "villain"],
  "templates": {
    "background": {
      "biography": "",
      "hairColor": "blue"
    },
    "resources": {
      "health": {
        "min": 0,
        "value": 10,
        "max": 10
      },
      "power": {
        "min": 0,
        "value": 1,
        "max": 3
      }
    }
  },
  "hero": {
    "templates": ["background", "resources"],
    "goodness": {
      "value": 5,
      "max": 10
    }
  },
  "pawn": {
    "templates": ["resources"]
  },
  "villain": {
    "templates": ["background", "resources"],
    "wickedness": {
      "value": 5,
      "max": 100
    }
  }
},
"Item": {
  "types": ["weapon", "spell"],
  "templates": {
    "rarity": {
      "rarity": "Common",
      "price": 20
    }
  },
  "weapon": {
    "templates": ["rarity"],
    "damage": 5
  },
  "spell": {
    "templates": ["rarity"],
    "cost": 2
  }
}
}

Resource Attributes

Specific attributes will be recognized by the game system as a "resource" if (and only if) they contain keys which define a value and a max. In the above example, health, power, and goodness would be detected as eligible resources for hero type characters.

How the Data Model is Applied

When a new Document is created in a game using this system, it will automatically have it's own internal data populated to conform to the schema defined in the system template. For example, when using this system, if we were to execute the following code:

const item = await Item.create({name: "Test Weapon", type: "weapon"});
console.log(item); // The created item data structure

We would observe that the item was created and assigned an ID, and the system field contained within the item matches the expected contents defined by the game system template.

{
  "_id": "e6c7US1VK2cqejVJ",
  "name": "Test Weapon",
  "permission": {
    "default": 0
  },
  "system": {
    "rarity": "Common",
    "damage": 5
  },
  "flags": {},
  "type": "weapon",
  "img": "icons/svg/sword.svg"
}

Data Model Migrations

Often, during the course of system development, changes to the template data structure are needed. In such cases, if you increment the version number in your system manifest file any existing Actors or Items will be automatically migrated to the latest template data specification when a World that uses the system is next loaded. During this migration process - any newly added data attributes will be added to existing documents, however old attributes which are no longer required by the template are not removed in case that data needs to be migrated.

To apply additional migration rules, the recommended approach is to provide client side logic which detects whether a migration is necessary and uses the client side API to facilitate additional changes.