My RPG Blog - Create your own RPG for computer or tabletop.


1- Creating A New System For Foundry VTT: Getting Started

1- Creating A New System For Foundry VTT: Getting Started

Starting a new System for Foundry VTT isn't easy.  Where do you even start?  What kinds of tools do you need?  I'll explain how to get started creating new Foundry VTT Systems in this article.

Creating A New System For Foundry VTT Part 1: Getting Started

Hi!  My name is Frank Succardi, known in some places on the Internet as, "CyborgPrime".  I'm the owner and lead designer at CyborgPrime Games.

I have a homebrew Sci-fi system based loosely on the Traveller science-fiction RPG and I'd like to convert it to Foundry VTT.

I'm also interested in converting all my existing VTT content from the Roll20 App to Foundry VTT.

It's not that easy though - foundry requires you to be familiar with HTML, JavaScript, CSS, and JSON.

I have pretty extensive experience in all of these, but I mainly write utility programs to help with gaming tables and calculators.  I have never written JavaScript modules or used the Handlebars HTML dynamic templating system.

This will also be the most extensive use of JSON I've ever done for a project.

I will try to keep everything in regular layman's terms so the articles will be accessible to the widest audience.

Since Foundry VTT Systems are new to me, I expect I will make mistakes along the way, but I will document them and correct them, so hopefully, you can learn from my mistakes.


What Is A 'System'?

In Foundry VTT, a System is a set of templates, scripts, style sheets, and Foundry VTT Compendiums that define a game system and its entities.

A System is a named folder containing the following:

  • system.json (The System Manifest) - this provides the system specification and setup, any system dependencies, and defines any helper files required.
  • template.json - This file defines the actor and item data templates.
  • scripts folder - This folder should contain all your custom JavaScript files
  • styles folder - This folder should contain all your custom style sheets
  • packs folder - This folder should contain any compendiums required


My Toolbox

I have a set of tools and reference items I like to use when doing Foundry VTT development.

You are going to need a text editor to create all the files. 

Any editor you like is OK, but I suggest using one that has the following features:

  • Code folding/collapsing
  • Bracket matching
  • Code formatting to consistently style code
  • Intellisense autocomplete

My preference is Visual Studio Code edition, but Sublime Text or even Notepad++ would be fine.

You are also going to need some reference documents with examples.  I like W3 Schools for most references.

JSON Editor

JSON Editor Online

Programming Editors

Programming References

Other Resources

Foundry VTT System Development Resources

Because of the way JSON files can nest and become easily unmanageable, I find it useful to create my JSON in a tool like JSONonline which shows me what the data structure I am making looks like and lets me switch back and forth between code and visual design.  Super useful!


Practice Version Control To Avoid Headaches

I recommend starting simple and getting one common example of each thing you are trying to working before moving on to the next thing or building complexity.

Be sure to practice version control so you can go back to a previously working version if you mess something up.

Using automated version control software like GitHub or any other common SVN is recommended.

I use Git - you can find Git here.

Of course, you can just use version numbers in your filenames to do basic version control.  For instance, the current version could be template.json, but previous versions could be called template-1.json, template-2.json, etc.  If you mess up you just reload the highest number version in your archive.


The Way Forward

I will be approaching the System development in a modular manner, starting out simple and expanding the System as I go.

My general plan of attack:

  • Create a System Manifest
  • Create a Data Template
    • Create a simple Actor Template to hold player data
    • Create a simple Item template to hold item data for things you can carry in your pockets

Future Expansion:

  • Create additional Item Templates
    • Create a Skill Template to hold data for various skills
    • Create a Weapon Template to hold data for weapons
    • Create an Armor Template to hold data for armor and protective gear
  • Create additional Actor Templates
    • Create an Animal Template to hold data for alien flora and fauna
    • Create a simple Ship template to hold data for ships
    • Create a simple Vehicle template to hold data about vehicles


System File Structure

Each System requires the following two files:

  1. The Manifest File- system.json
  2. The Data Template- template.json

The System files must be on the root level of a folder whose name matches the NAME attribute in the Manifest File exactly.

Any additional folders can follow whatever naming convention and organizational style you choose.

The file System Structure should look like this:



The sample file structure looks like this:



Making It FutureSpace

For FutureSpace, the file structure looks like this:


You can use your text editor to create empty dummy files and the folder structure, then edit or add to it later.

For my example, I created a futurespace folder then made folders inside that for scripts, styles, and packs.  Then I created blank system.json and template.json text files.

The structure looks like this:

futurespace foundry vtt system directory structure

OK, we are ready to get started. 

Check out the next article in this series: Creating A New System For Foundry VTT Part 2: The System Manifest


Your Turn: What Do You Do?

Do you have a custom system you want to create in Foundry VTT?

Are you an experienced System Developer with tips for beginners?

Tell me about it in the Comments Section.  I'm interested in what you have to say about Foundry System Development.


E-mail Notification Opt-in

Do you want to receive email notifications when we add new game design content?

Sign up on our private mailing list.

YES! Notify me of new game design posts!

Comments powered by CComment

Related Articles


Make your own RPG in your spare time with minimal skills.

Join me on my journey to create my own RPGs to play online or share with my friends.

I'm an RPG maker and game designer who builds tabletop and electronic RPGs for fun in my spare time.

Contact me if you have questions or suggestions.