How to Create and Distribute a Compendium Module

Table of Contents

Introduction

In this guide, we explain step-by-step how to create a compendium module, almost completely from scratch. This guide assumes that you understand what Bazaar packages are. If you are unsure on what a Bazaar package is, or what type of package your content might be, we recommend you read through the linked guide above first.

This guide also assumes you have a basic level of understanding with Foundry Virtual Tabletop- to a level where you know how to create entities like actors, scenes, and items within Foundry. Foundry VTT offers a knowledge base here if you do not, and the Youtube channel Encounter Library has several high quality videos in a Foundry VTT Basics playlist.

Owing to the complexity of this topic, and the many ways a creator can bundle their content, we only explain common methods of package creation for users who may not be technologically proficient, or knowledgeable in coding. Software module developers, as well as system developers should reach out to The Forge via email, as the process for distributing this content and configuring the Bazaar package listing is only slightly different than typical Foundry distribution.

What is a Compendium Module?

Compendium modules are modules with a primary emphasis on containing content within a readily accessible compendium in Foundry Virtual Tabletop, once installed. Compendiums are basically folders for content within Foundry. Compendiums help organize content, allow users to store content for later without slowing down Foundry, and serve as a useful method for using content between worlds, or distributing content to others.

A lot of different content can be stored in compendiums. Map compendium modules are the most common premium content on The Forge. Creators will prepare a map image on a “scene” in Foundry Virtual Tabletop, lining it up appropriately on the grid, and setting up dynamic lighting/any other needed or desired effects for the map. The scenes are then moved to a compendium, which is then redistributed within a “module” to other users, allowing them to receive the map already prepared for Foundry Virtual Tabletop!

The same can be done for any kind of “entity” in Foundry Virtual Tabletop- Actors (commonly known as character sheets, or PCs/NPCs), Items, Journal Entries, Macros, Playlists, Rollable Tables, and as mentioned before, Scenes.

A single compendium can contain one type of these entities, and can reasonably contain hundreds of entities without significant issue. A module can be used to distribute several compendiums at once, allowing creators to distribute any amount of different compendiums and their “entities”.

Does this sound confusing? To make this simple, imagine Foundry is a computer, and compendiums are its file system. The computer (Foundry) will receive this module, and once installed read some prepared instructions within it, telling it that these are folders it can access.

We promise, setting up a compendium module is easier than it sounds!

Making a Compendium Module

First, you’ll need to own and have installed Foundry Virtual Tabletop on your own machine. Open the program, and navigate to Configuration on the Setup Menu:

You will want to look for your user data path, circled above. This is where Foundry stores the information that it creates- and where you will be storing your content!

If you are on Windows, you can quickly access your user data path by right clicking on Foundry in the taskbar while it is open, and selecting “Browse User Data”. If this is not available to you, you will need to do the following:

  • Copy the User Data Path highlighted above.
  • Open your operating system’s file browser, and then click the address path on the top.
  • Paste the file path you copied from Foundry.

From here, navigate to and go inside the “data” folder. From there, go inside the “modules” folder.

Within the modules folder, create a new folder. This will be the folder that contains your compendium module. Name the folder something simple and descriptive- it is recommended that the name be short, and it must contain no symbols. Instead of spaces within the folder name, use hyphens or underscores. The name should be non-generic, and unique, so as to prevent conflict with existing modules. In this example, we will call the folder “forge_example”.

Before we go forward, we will want to create a folder within the module to contain any media (images, audio, videos) that is used within our compendiums. This is so that people receiving the module will be able to access the media that the module uses. By bundling it within the module, you ensure that users will receive the media.

In this example, we will call the folder “media”. This folder name does not have to be individualistic in-name, but it should still be kept simple. From here, you can place all the media files inside that you will need for the module. Creating sub-folders within your media folder to help organize these files is acceptable, and will not greatly complicate the creation process- it may in fact help you keep it organized. In this example module, I will create an “audio” folder, a “token” folder, and a “map” folder, to help organize my media. In this example, we’ll move media to the folders ahead of module creation, as I already know what media will be needed for the module.

Once we’re done placing any necessary media within the module folder, we can create the module.json!

Editing a Module.json File

Note: The Forge uses the Package Manifest+ format developed by the League of Developers. This means that The Forge can parse more data within a module.json, and display useful information (such as creator websites or social media) automatically!

A “JSON”, or JavaScript Object Notation file is far less scary in complexity than the name sounds. To simplify things, it’s just a fancy text file- and in this situation, the module.json is the file that tells Foundry that “this folder is a module”.

You can technically use most text editing programs to make and edit a .json- but we recommend using Notepad++ for editing- it is a common program for this kind of usage, and the one that will be used in this tutorial.

Once you have chosen your text editor of choice, you can download an example module.json to edit here. Place the module.json in your compendium module folder, and then we can begin editing it.

Again, editing this may look scary- but a lot of the work has already been done, and there are only a few parts that need edited for your own personal usage. This guide will go step-by-step to explain it.

Above: Screenshot of the module.json

Under the name field, you will see in quotation marks “example_module_name”. Without deleting the quotation marks, edit the name inside to match the name of your compendium module folder. The name field represents the name of the folder, and must therefore match it. This will not be the name that appears for your user. In this example, we named our folder “forge_example”, and so we’ll replace “example_module_name” with “forge_example”.

Under the title field, you will see in quotation marks “Human Readable Title”. This is where you can put the actual title of your module, for users to read when they’re viewing the module in the Setup menu, or in-game under the module management menu. This can have as many spaces and symbols as you want. In this example, we’ll replace “Human Readable Title” with “Forge Example Module”.

Under the description field, you will see in quotation marks “Some kind of nice description here, as…”. This is the description that users will see when browsing through their modules in the Setup menu for Foundry Virtual Tabletop. They will also see the description while browsing through the “Manage Modules” interface in a world (see below). We recommend using a short, one line description.

There is both an author field and an authors field in this module.json. Foundry VTT does not recognize the authors field, but The Forge does- as many packages submitted to The Forge have multiple creators. If there is only one author associated with the package, you can delete the entire authors section, as is highlighted below (You should not, however, delete the author field.):

Under the author field, edit the text that says “If one author, include here”, and state the title/nicknames associated with the creators here, or the name of the associated business (whichever you prefer). This will ensure they are listed if users operate your module outside of The Forge. You can also edit under the authors field “Example Author 1”, and “Example Author 2”, replacing it with your text of choice. If there are more than two creators/authors associated with the product, add a comma to the end of the second name field, and copy the name field below, like so:

In this example, we will be deleting the authors field, as there is only one creator/company associated with the package- “The Forge VTT”.

The version field does not need to be changed- this is merely the version number of your compendium module. Updating and managing an uploaded package will be discussed in a future forum guide.

The minimumCoreVersion and the compatibleCoreVersion fields merely describe what Foundry version users need to be on, in order to use the module. These fields are typically more relevant with software-modifying modules, but are still slightly relevant with compendium modules- scene data, and actor data can vary wildly from earlier versions of Foundry Virtual Tabletop. When in doubt, specify the latest stable version of Foundry Virtual Tabletop in these fields. For this example, we will leave the fields untouched, as the entities we are working with are already compatible with the versions stated within the module.json. In the future, this may not be true, so make sure to verify!

The url field is recognized by The Forge, and used to point toward the package’s associated website. You can use this field to point to your package’s Git page, if you use one- or you can use it to point to a Patreon website, or social media, or any other website associated with the package in question. For this example, we will edit “IncludewebsiteURLhere if you want” to instead say “ forge-vtt.com/ ”.

The manifest field will necessarily need to be edited later, but is one of the most important parts for publishing on The Bazaar. The download field is similarly important, and will also need to be edited later.

So far, your module.json should look something like the following:

Finally, we get to pack creation. Packs are Foundry’s “backend” name for compendiums. Specifying a pack exists here, even if it has not been made yet, will ensure that upon the module being enabled, a pack will be created. This is a fast way of setting up the compendiums for the module!

Before we can start, you’ll want to make a “packs” folder within your module. This will be explained later.

Some further notes before we start editing the pack field-

  • If there is only one compendium associated with the module (for example, if you’re making a map pack for distribution to Foundry users), you can delete the first pack mentioned, including the comma- see the highlighted section below:

image

  • If you wish to add additional compendiums, like we will in this example, duplicate one of the packs, and then paste it below the last one. Make sure there is a comma at the end of each pack, except for the last one. An example screenshot is below:

image

Once you know the number of packs/compendiums you will require for the module, we can begin editing them.

  • The name field is how Foundry references the packs/compendiums from the software backend. Under the name field, retain the quotation marks, and make a simple name for the compendium- it should be all lowercase, with no special symbols or spaces.
  • The label field specifieds the name of the compendium, as it is seen in-game by users. We recommend making the label descriptive enough that users can tell at a glance that this compendium contains content from your module.
  • The system field is intended for packs/compendiums containing system-specific data. This is especially relevant for Actor and Item packs, which may contain very specific data that is not compatible with all systems. In these cases, you should specify the technical name of the system within the quotation marks. For the most commonly played system on Foundry (Dungeons and Dragons 5th edition) this would be “dnd5e”. If your pack/compendium is not system specific, you can delete this field. Remember that if a scene contains tokens with actor data from a particular system, you will want to specify the scene compendium is system specific, despite scenes normally being system-agnostic.
  • The path field is the file location of your compendiums, and why we created the “packs” folder earlier. The path should look something like “./packs/your_module_entitytype.db”. Replace “your_module_entitytype” with any lowercase name without special symbols or spaces- but we recommend making it descriptive of the compendium. This will be the actual file that is the compendium- the one that Foundry will automatically create, once the module is enabled. Bear in mind it has to end with .db, as “compendiums”, or packs are database files.
  • The entity field specifies the kind of content the compendium/pack contains. They can be the following entity type: “Actor”, “Item”, “JournalEntry”, “Macro”, “Playlist”, “RollTable”, and “Scene”.

Once you are done editing these, the .json will almost be done. All that is left to do is validate the JSON! Validating a .json file is simple, and means making sure that it is in the right format- if it is not, it will not work. To begin validating, copy the entire text of your .json, and paste it into a website that verifies your .json is in the right format. In this example, we will use https://jsonlint.com. If you did everything right, JSONLint, or your JSON validator of choice should say something like the following:

If you did not do everything correct, such as accidentally misplacing a comma, the validator will generally inform you of the mistake, like so:

The final JSON file should look like the following, with some differences in the naming:

The manifest URL and download URL will need edited at the end- for now, we will begin working on the actual content of your compendium module!

With the module.json mostly complete, and the folders and appropriate media brought in, your module folder should look like the following:

If everything seems right, you should launch Foundry Virtual Tabletop. If the module.json was created correctly, and placed in the right file location, you should see your module show up under the module menu, like so:

If it doesn’t show up, then it means that a mistake was made at some point during the creation process. Check for the following common errors:

  • Is the module.json in the correct file location?
  • Is the module folder in the correct file location?
  • Is every folder path specified in the module.json valid?
  • Is there a typo, or mistake with the module.json?
  • Was Foundry restarted after the module.json was completed?

Once the module shows up in the setup menu, we can begin adding the actual content to your compendium modules!

Adding Content to a Compendium Module

First, create a new world in Foundry VTT. If your compendium module will contain system-specific data, like items or actors, make sure the world is the same system as the intended content.

Once you have created a new world, navigate to the Game Settings tab, and select “Manage Modules”.

Scroll through the menu as needed, until you find your compendium module. Select it, and then click “Save Module Settings”. This will enable access to the module in the world, and let you begin editing it.

Once enabled, you should see the compendiums from the module in-world, and they should display that they are from the module:

Right click on each compendium from your module, and select “Toggle Edit Lock”. This will allow you to import content into the compendiums. Non-world compendiums have editing locked by default, to ensure users will not have their content overwritten by module or system updates- however, in this case you are the “developer” providing the updates.

Once all of this is done, you can begin creating your entities, and adding them into the compendiums! Just create them normally, edit them, remember to select any associated media from the module folder when using Foundry’s file picker, and once completed, drag them into the relevant compendium.

Once every entity has been edited and added to the compendiums, you’re ready to begin preparing the module for distribution! See, it wasn’t that hard to create a compendium module, once the module itself was created!

Distributing Your Compendium Module

To set up distribution, you will need a host or cloud provider that will consistently allow downloads of your module, and your manifest file (this will be explained later). The Forge supports this, but we recommend against this approach for compendium modules- due to the lack of fine-tuned control over the process, and because past a certain storage limit, you will need to pay us to host your data, which is cheaper to do elsewhere.

In this guide, we will use Dropbox as an example. Warning: Dropbox has a 20GB bandwidth limit, and 100,000 download limit per day for free accounts, and a 200 GB bandwidth limit for paid accounts.

Dropbox is, however, a simpler platform to use for this purpose, and if you exclusively offer your module through The Forge, it will be an extremely unlikely issue (The Forge saves packages uploaded to its service, and installs it for users with its own internal storage). If you have the package and its updates available outside of The Forge, however, it is something to keep in mind if you have a significant audience, or large modules.

Other cloud platforms and hosting services will generally work, though they will need to support sharing file downloads, in the form of including a file extension at the end of the download URL (Google Drive does not do this by default, and requires some manual work to produce the URL). Generally, the more a service supports a stable URL, the better the experience for your users.

Create a folder for your module, in your cloud file hosting service of choice. From here, zip up your module folder (do not delete it from your local Foundry- we still need it). WinRAR and 7zip will both work equally well, but it must be contained within a .zip file. Upload the zip file to the cloud service, within the module folder you created there.

Now, obtain the file link to the zip folder. With Dropbox on Desktop, you can right-click the zip file within Dropbox, select “Share”, and then obtain a shareable link in the bottom right corner of the menu. If you are using Dropbox, edit the “dl=0” at the end of the link to instead say “dl=1”- this is necessary for it to work from Dropbox.

(Note: Once you have selected “Share” in Dropbox, avoid deleting linked files- only overwrite them, as deleting them will update the shared link.)

Go back to the module.json in the original folder location, and edit the “download” field. Replace “DownloadURLhere” with the file location of your zip file. Save these changes. You now have a working download link for your module!

There is one more thing to do- creating a manifest file. You already have everything you need to send the module to others- but for users to easily install a module, they will need a manifest. You will also need one if you wish to upload your module to share with others on The Forge as well.

Thankfully, this is simple to do- your module.json will be your manifest!

  1. Copy your module.json to the module folder in your cloud service.
  2. From there, obtain the link to the module.json, following the same process that you did for your zip file.
  3. Now, edit the “manifest” field in the module.json located in your cloud service. Replace “ManifestURLhere” with the link to your module.json in the cloud module folder.
  4. Copy the module.json from your cloud folder, and replace the one located in your local modules folder (this will helpfully update your module.json for the future).

With this, you only have one more thing to do- overwrite the zip file in your cloud folder with a newly zipped version of your module. This is because your zipped module still contains the old data from your module, which is missing the download link and manifest URL. Without these, your module will not update correctly. Once this is done, you should be complete, and your module is now ready to be distributed!

For an example of a working module, complete with the module.json edited for release, you can install the Forge Example Module on your local Foundry installation with the following manifest link: https://www.dropbox.com/s/8b6a0gxje4lrd09/module.json?dl=1. Feel free to browse through it, pour over the contents, and see how you can edit your own module!