Building a FoundryVTT Game System, Part 1

2025-07-11

Note: This series of posts assumes you are using Foundry version 13.x

What is a Foundry game system?

From the point of view of a user, a game system is the ruleset you are using for a particular game. When you create a new game world in FoundryVTT, you are prompted to select a game system, such as Pathfinder Second Edition, GUMSHOE, or Dungeon World. The actual list is controlled by the server administrator, who chooses which systems to install.

Administrators can also install modules that contain additional content or functionality. Modules can be enabled (and configured) per-world, and you can create modules that support many systems. Some modules are also system-independent, modifying other parts of the FoundryVTT experience.

From the point of view of a developer building out support for a game system, the two are extremely similar, and one design decision you may be faced with is whether content should be in a module or the game system. An important thing to keep in mind is that a game world can only have one system, but many modules.

For these posts, I’m just going to focus on build building a small but complete system from scratch. The reason I’ve chosen this approach is because I want to focus in on the key concepts and build out from there. Once we’ve built the system, we can look at how we might extend it with a module.

Before we start

You should be comfortable with the basics of HTML, CSS, and JavaScript. We will also be looking at a lot of data in JSON format.

You should have FoundryVTT installed on your local computer, and know how to start it, create a game world, and be able to find your way around once you’ve joined a game (especially as the Gamemaster).

I’ll be mentioning the user data path a few times. You can find it in the Application Configuration dialog, where it is the value of the User Data Path setting.

When it starts up, Foundry looks for systems as subdirectories in the {user data path}/Data/systems directory. Some people find it simplest to simply create their system directly in this location. I prefer to work with my source code somewhere else and create a symlink inside the systems directory1.

The smallest thing that will work

We need to pick an ID that will uniquely identify our game system. It must be all lowercase, but can also include numbers and hyphens2. For this series of blog posts, I’m going to use the id tiny-sample-system.

Create or symlink a directory with this name inside the Data/systems directory. From now on we will be working inside our new directory.

mkdir tiny-sample-system
cd tiny-sample-system

There are only two files required for Foundry to recognise this as a valid system.

The first required file is a system manifest (which must be named, naturally enough, system.json) that defines the system and its contents. For now, we’ll just put in our system ID and a human-readable title3.

system.json

{
    "id": "tiny-sample-system",
    "title": "Tiny Sample System"
}

The second required file is a data template (which must be named template.json) that defines the system-specific data that we’ll use to define actors and items for this system. Rather than discuss those now, we’ll put in the smallest thing that make Foundry happy.

template.json

{
    "Actor":{
        "types":["miniActor"]
    },
    "Item": {
        "types":["miniItem"]
    }
}

Checkpoint

If you’ve done everything correctly, inside your Data/systems directory there is now a directory with the name tiny-sample-system, and it contains two files named system.json and template.json with contents as above.

  1. Start Foundry. Look on the Game Systems tab, where you should see Tiny Sample System show up in the list.
  2. Create a new game world, selecting Tiny Sample System as the game system.
  3. Start the world, and join the session as the Gamemaster (for a newly created world, there is no password until you set it via User Management in the world settings).
  4. Switch to the Actors tab and create an actor. You can optionally assign a token if you dislike the default.
  5. Switch to the Items tab and create an item.
  6. Switch to the Scenes tab and create a new scene. Activate the new scene.
  7. Switch back to the Actors tab, and drag-and-drop the actor onto the scene.

At this point you have a minimal, working system. This is a good time to commit your changes to source control4.

In Part 2, we’ll have look at Actor and Item types and what they mean for our system.