Compendium Packs


Compendium Sidebar Tab Screenshot

The Compendium Packs tab as seen by a gamemaster.

Compendium Packs exist to reduce the strain on worlds that have accrued a large number of actors, items, macros, playlists, rollable tables, or scenes. When these elements are not in use, but are not ready to be deleted, they should be stored in compendia. Compendium Packs help you keep your world organized, reduce clutter, and improve performance for all users.

Compendium packs are also used by Add-on Modules and Game Systems to store large amounts of content which can be unpacked and added to an existing game world, such as part of a premium or exclusive content pack.

With the exception of Adventure Documents, each Compendium can only contain one type of document: Actors, Items, Journal Entries, Macro Commands, Playlists, Rollable Tables or Scenes. Data contained in compendium packs are not loaded for users until they are needed, reducing the amount of data that a particular user must load when first joining a game.

When to use Compendium Packs

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

Using Compendium Packs

Compendium Packs are accessed from the @Article[sidebar] by clicking on the @Article[compendiums] tab. This will display a list of all Compendium Packs which are available to the current user. If the user is a gamemaster, they will also be able to create new Compendium Packs, modify or delete existing Compendium Packs, or hide specific Compendium Packs from users.

Locking Compendium Packs

You can only export folders or otherwise modify compendium packs which are unlocked. A Compendium Pack can be locked or unlocked by right-clicking on it from the Compendium Packs sidebar tab and choosing ( ) "Toggle Edit Lock". This will lock or unlock the chosen compendium.

Important: Users should be very careful not to edit the contents of Compendium Packs provided by Game Systems and Modules, as their changes will be lost when the module or system updates.

Creating A Compendium Pack

A new, empty, Compendium Pack can be easily created in any World (if you're interested in making a module with compendium packs check out our Content Packaging Guide):

  1. Navigate to the Compendium Packs sidebar tab ( ).
  2. Click the "Create Compendium" button.
  3. Enter a name for the new Compendium Pack.
  4. Choose the type of Document that will be stored in the Compendium Pack (such as Actors, Items, Journal Entries or more).

If you intend to use your compendium to provide a fully importable adventure with multiple types of document, please see Adventure Documents.

After your compendium has been created, clicking on its name in the sidebar will open a new window that will allow you to manage the content your compendium pack contains.

Compendium Context Menu Options
Compendium Pack Context Menu
The Gamemaster's context menu for compendia is accessed by right-clicking any compendium (hand, deck or pile) in the card directory.

All compendia in the Compendium Directory can be right-clicked to open up a context menu which allows for additional actions used to manipulate them.

Toggle Visibility ( )
Toggles whether the compendium can be seen by non-GMs.
Toggle Edit Lock ( )
Toggles on or off the ability to export content to the compendium. While locked the compendium cannot be chosen as an export source for documents.
Duplicate ( )
Creates a copy of the compendium in the directory. Duplicating stacks is disabled for hands and piles that contain compendia, requiring them to be reset first.
Import Data ( )
Imports data into the right-clicked compendium from a JSON file on your computer.
Delete ( )
Deletes the compendium, after accepting a confirmation prompt.

Managing Content

Within compendium packs that have been unlocked it is possible to add, remove, or edit Documents in order to provide an organized content structure for your users. Compendium packs are alphabetically sorted by default. There are two ways to add content to compendium packs:

Adding Individual Documents to Compendium Packs

Adding individual Documents to a compendium pack is an easy process, supported by a simple drag and drop workflow:

  1. Navigate to the Compendium Packs sidebar tab ( ).
  2. Open the compendium you wish to add content to.
  3. Be sure your compendium pack is not locked! It is not possible to modify a compendium that is locked.
  4. Navigate to the sidebar tab where your Documents are stored.
  5. Drag the Document you wish to add to your compendium from the sidebar into the compendium pack.

Adding individual documents to a compendium does not preserve its ID or merge with copies that may already exist in the compendium, each dropped Document will create a new copy in the Compendium Pack.

Adding Folders of Documents to Compendium Packs

If you have already organized content in your world into folders for easy management, it is simple to add that folder worth of content to a compendium pack. It's important to understand that compendium packs have no understanding of folders, however, so if you add multiple folders worth of content to the same compendium it will not retain its folder structure when imported back into your world.

To add a folder of Documents to your compendium:

  1. Be sure your compendium pack is not locked! It is not possible to modify a compendium that is locked.
  2. Navigate to the sidebar tab where your Documents are stored.
  3. Right-click on the folder you wish to add to your compendium.
  4. Choose "Export to Compendium" from the context menu.
  5. Choose the Compendium Pack that will be used to store your Documents.
  6. Optional: choose whether or not you wish to merge the documents with existing documents in the compendium by name, or whether or not you wish to keep the ID of your documents.
  7. Click Export Content.

Importing Compendium Content

If you have existing Compendium Packs and would like to import content from them, there are a variety of ways to do so. It is important to exercise some caution when importing everything a compendium pack might contain, especially if the compendium pack might be storing hundreds or thousands of Documents, as this will negatively impact performance in your world.

Once content has been imported into a game world it becomes a localized part of that world, and any changes made to the documents in said world will not be reflected in the compendium they came from unless you also export the content back to the compendium, or create a new compendium with the changed documents. This allows you to use compendia as a means to back up things like actors, items, journals, and scenes that you want to keep original, unaltered copies of for reuse later.

Importing Individual Documents From a Compendium

Perhaps the easiest way to import content is to choose individual items to import into your world.

  1. Navigate to the Compendium Packs sidebar tab ( ).
  2. Click on the Compendium Pack you wish to import from.
  3. Either:
    • Drag the Document you wish to import from the compendium into the appropriate Document Sidebar tab (for example, Actors go to the Actor tab.)
    • Right-click on the Document you wish to import and choose 'Import Entry'
    • Click on the document you wish to import, and click Import in the window header bar.

Importing Documents one at a time creates a new copy of that Document, and does not preserve the ID of the original Document. Importing an individual Document will not overwrite existing Documents of the same name.

Importing All Documents From a Compendium

Importing all documents from a Compendium is a great way to quickly add a large number of documents to your world. However, it is important to note that importing all documents from a Compendium can create a large volume of Documents in your world at once, so it should be used with some measure of caution. Importing all Documents allows you to optionally preserve the ID of the original Document, which will overwrite any Documents in the World which have the same ID.

  1. Navigate to the Compendium Packs sidebar tab ( ).
  2. Right-click on the Compendium Pack you wish to import from and click Import All Content
  3. .
  4. In the new dialog that appears, choose a folder name to import the content to.
  5. Optional: If you wish to overwrite existing Documents based on their ID (unique across all folders), choose "Keep Document IDs".
  6. Click Yes.
Merge By Name
When Merge By Name is checked Foundry VTT will overwrite existing documents that have the same name as one of your exported documents. When it's unchecked Foundry VTT will create new copies of those documents.

Moving Compendium Packs To Other Worlds

Compendia are limited the game world they are created within by default, but it is possible to move them to new worlds or create modules which contain compendium packs for use in other worlds. To learn how to do this, refer to the Content Packaging Guide.