Compendium Packs are used to store Entities of all types in a way that reduces the impact on the game while still keeping the information accessible.

Introduction

Compendium Packs exist to reduce the strain on worlds that have been running for a long period of time, or which may have accrued a large number of entities that, while not active, should not be deleted. Compendium Packs should be used to help you keep your world organized and reduce clutter.

Each Compendium can only contain one type of Entity such as Actors, Items, Journal Entries, Macro Commands, Playlists, Rollable Tables or Scenes. Data contained in compendium packs are not loaded until needed, reducing the amount of data that a particular user must load when first joining a game.

Creating and Using Compendium Packs

A Compendium can be easily created in any World. First, navigate to the Compendiums Sidebar Tab, and then click the "Create Compendium" button. Enter the name of the Compendium (for example "Player Characters") and choose the correct type of Entity from the Entity Type dropdown. After your Compendium has been created, clicking upon the Compendium name in the Sidebar will open a new window that will allow you to drag and drop from a Sidebar Tab into the Compendium.

Compendium Packs are automatically sorted alphabetically.

Do I need a Compendium?
Storing unused Entities in a Compendium greatly reduces the time it takes to load your world. Even though each Actor, Item, or other entity may be small, as their numbers start to rise into the hundreds the amount of data that gets transferred to each of your players when they join can cause your world to slow down over time. It is a best to practice good organization.

Exporting Packs

Though it is presently one of the more technical export processes due to the need to manually edit JSON files, Compendium Packs can be exported for use in other worlds, or for distribution as a custom content module. This allows you to share your Actors, Items, Scenes, and more with your friends or the wider Foundry VTT community.

Best Practices for Exporting Compendium Modules

It is important to observe certain practices if you are intending to distribute your Compendium as a module. Module packs do not automatically store image or sound files when dropped into the Compendium window. Building a compendium for export requires a little more planning than building a compendium for storage.

Asset Files
You must ensure that any images such as Scene backgrounds, Actor portraits or Token pictures, Item icons, or Journal images point to the location of that file in your module folder. Failure to do so will result in the module not being able to find the file when it is imported to another user's Foundry VTT installation. This also applies to Sound Files.
File Sizes
Give consideration to file types and sizes. As a general rule, asset files should be the lowest possible file sizes they can be. Favour WebP or JPG for image files, WebM for animations, and OGG for audio.
File Structure
Files intended to be exported with your compendium module should adhere to web-hosting standards. That means they should not contain any spaces or special characters in their filenames (including folders). Ideally, filenames should be standardized for distribution, capitalized the same way, and stored in an organized and easy to reference fashion to make your own job of setting them up easier.

Creating Your Compendium Module

This section of the article provides a very rudimentary step-by-step process for creating a Compendium Module for export.

Step 1 - Preparation

module.json Example


		{
			"name": "mymodulename",
			"title": "My Module Name",
			"description": "A module containing a compendium pack",
			"author": "My Name",
			"version": "1.0.0",
			"minimumCoreVersion": "0.6.0",
			"compatibleCoreVersion":"0.7.0"
			"packs": [
    					{
      					"name": "myscenedatabasename",
      					"label": "The Human-Readable Name for My Compendium",
      					"path": "packs/my-scenes-right-here.db",
      					"entity": "Scene",
      					"module": "MyModuleName"
						}
					]
		  }
		

Compendium Pack JSON Definition

To define a valid Compendium pack in a JSON manifest file include the following object structure inside the packs array.

"packs": [
    {
      "name": "pack-name",
      "label": "Pack Title",
      "system": "system-name",
      "path": "./packs/pack-name.db",
      "entity": "Item"
    },
]

The elements of this data structure are defined as follows:

name

The compendium pack name - this should be a unique lower-case string with no special characters.

label

The compendium pack label - this should be a human readable string label which is displayed in the Compendium sidebar in-game.

system

Since you are creating compendium content specifically for your system, be sure to reference that the content inside each compendium pack requires the system by providing the system name that you chose.

module

The module attribute of each compendium pack designates which content module provided the pack, since this pack is coming from the system itself we can once again provide the system name.

path

The path for each compendium pack should designate a database file with the .db extension. As a best practice, I recommend placing these database files within the packs subdirectory. You do not need to create these files yourself. If a system includes a compendium pack, the database file for that pack will be created automatically when the system is loaded, if it does not already exist.

entity

Each compendium pack must designate a specific Entity type that it contains. Compendiums can contain any type of Entity, including: Actors, Items, Journal Entries, Macro Commands, Playlists, Rollable Tables or Scenes.

system

Each compendium pack may optionally specify a string or Array of strings which identifies the game system or systems for which its included content is appropriate.

Bulk Importing of Compendium Content

A relatively common desire for module or system developers is to bulk import external content to create a compendium pack. There are several ways to do this, but the recommended approach is to use the API to handle creation of your compendium entries from structured data. The following code block provides an example of importing Actor data from an external JSON file and using that data to populate a compendium pack.

// Reference a Compendium pack by it's callection ID
const pack = game.packs.find(p => p.collection === `${moduleName}.${packName}`);

// Load an external JSON data file which contains data for import
const response = await fetch("worlds/myworld/data/import.json");
const content = await response.json();

// Create temporary Actor entities which impose structure on the imported data
const actors = Actor.createMany(content, {temporary: true});

// Save each temporary Actor into the Compendium pack
for ( let a of actors ) {
  await pack.importEntity(a);
  console.log(`Imported Actor ${a.name} into Compendium pack ${pack.collection}`);
}