Developer Guide - Files Overview

Owned by Derek Batting
Last updated: Jun 12, 2023 by John Gregory
6 min read

Data Folder

The Fantasy Grounds data folder is specified in the FG Settings when installing FG.

The easiest way to access the data directory is to click the folder icon in the top right of the main FG startup screen. This will open a new file explorer window at the root of the data directory.

If you are content creator and you are considering adding Fantasy Grounds versions of your products for distribution or on a Kickstarter project, please read this FAQ first: 
https://fantasygroundsunity.atlassian.net/wiki/spaces/FGCP/pages/996639040

If you are a fan of a specific game system, please seek permission before using any names, images or other content protected by copyright before you even consider distributing anything.

The data folder contains the following subfolders:

  • cache = Campaign data for campaigns you join.

  • campaigns = Campaigns. Campaign data for campaigns you host.

  • characters = Character data for Manage Characters mode.

  • extensions = Extensions. Optional ruleset modifications. (themes, house rules, new features, etc.)

  • modules = Modules. Option ruleset data packages.

  • portraits = Portraits. Images for PC portraits.

  • rulesets = Rulesets. Game system definition packages.

  • tokens = Tokens. Images for map tokens.

  • utilities = Utilities distributed with Fantasy Grounds (if any)

Rulesets

Installation: To install a new ruleset, just place the ruleset directory or PAK file into the rulesets subfolder of the FG data folder.

Rulesets are a set of files that define how a specific RPG system looks and plays on the Fantasy Grounds tabletop.

Rulesets can be distributed as a directory containing the data files, or as a PAK file (a ZIP file renamed with a .pak extension that contains all the data files). Additionally, a logo.png and license.html file can be included with the ruleset files. Both files are used on the launcher campaign creation screen to provide more information on the game system supported by the ruleset.

If rulesets have the same name, then folders take precedence over PAK files, which take precedence over DLC vault files.

Rulesets require a base.xml file in the root of the folder or PAK file; but can contain additional XML files, Lua script files and graphic assets depending on what is defined in the base.xml file and any included XML files. Graphic assets can either be images (PNG, JPG) for custom icons and frames, or fonts (TTF, FGF) for custom fonts.

Troubleshooting: If the ruleset is not appearing on the launcher screen for Creating a New Campaign or Manage Characters, then make sure that a base.xml file exists in the root of the ruleset directory or PAK file.

Extensions

Installation: To install a new extension, just place the extension directory or EXT file into the extensions subfolder of the FG data folder.

Extensions are a set of files that can modify a specific ruleset. Extensions can be used to add new graphics (such as a desktop or window theme) or to modify behavior (such as house rules or new features). Extensions can be distributed as a directory containing the data files, or as an EXT file (a ZIP file renamed with a .ext extension that contains all the extension data files).

If extensions have the same name, then folders take precedence over EXT files, which take precedence over DLC vault files.

Extensions require an extension.xml file in the root of the folder or EXT file; but can contain additional XML files, Lua script files and graphic assets just like a ruleset.

Troubleshooting: If the extension is not appearing on the launcher screen when Creating a New Campaign or Manage Characters, then make sure that a extension.xml file exists in the root of the extension directory or EXT file. Also, make sure that the ruleset that the extension is supposed to be modifying is also installed and selected on the launcher screen.

Modules

Installation: To install a new module, just place the module MOD file into the modules subfolder of the FG data folder.

Modules are a set of files that define prepackaged campaign or reference data for a specific RPG system. Additionally, modules can also contain token data. Modules can be distributed as a MOD file (a ZIP file renamed with a .mod extension that contains all the module data files). Modules can be activated for a given campaign through the Library window (or the Module Activation window). By default, modules are not loaded automatically.

For most rulesets, there is a Data Module Activation window available through the Library (for modules that contain data) and a Token Module Activation Window available through the Token Box (for modules that contain tokens). Modules that contain both data and tokens will be visible in both activation windows.

If modules have the same name XML tag, then folders take precedence over MOD files, which take precedence over DLC vault files.

Modules require an definition.xml file in the root of the folder or MOD file. To add data to a module, one or more of the following additional XML files must be included: db.xml (for GM data), or client.xml (for player data). Any images (handouts, maps) referenced by the XML files will need to be included as well. Also, any image files included a "tokens" subfolder within the module will be added to the GM token bag when loaded.

We recommend that all images included in modules do not exceed 2048 pixels in either width and height for maps and handouts. For tokens, we recommend keeping tokens around 100x100 for Medium size tokens. Large quantities and extreme image sizes can cause lag, and in some rare cases, memory issues on the player clients.

Portraits

Installation: To install new portraits, just place the PPK file or the image files into the portraits subfolder of the FG data folder. Portraits can be placed in folders for additional organization.

Portraits are image files that can be used to define how a PC is portrayed on the tabletop and for chat messages. Portraits are separate from the map token used for a PC. Portraits can be distributed as a PPK file (a ZIP file renamed with a .ppk extension that contains all the portrait files).

Any standard image file format can be used. The default portraits are 63x63 pixels. While any image file size can be used, larger image files can increase player connection times and network lag, and the extra resolution will not be used.

Tokens

GM Token Installation: To install new GM-only tokens, just place the image files into the tokens/host subfolder of the FG data folder. Tokens can be placed in folders for additional organization.
Shared Token Installation: To install new shared tokens, just place the image files into the tokens/shared subfolder of the FG data folder. Tokens can be placed in folders for additional organization.

Tokens are image files that can be used on maps to indicate tactical positioning of PCs and/or NPCs. Tokens are separate from the portraits used for a PC.

Any standard image file format can be used. Most people use tokens at 50x50 pixel size. While any image file size can be used, larger image files can increase player connection times and network lag. This is especially true for shared tokens, since the shared token library is synchronized with the player cache on every session connect.

Campaign

The campaign folder is where FG stores all the information specific to each campaign. Each campaign will have it's own folder within the campaigns subfolder of the FG data folder. Generally, there is very little need to access the campaign folder, except to add images/maps.

The campaign folder contains the following subfolders:

  • drawings = Data files about any drawings placed on a campaign image.

  • images = This is where images and maps can be added to a campaign. Any image files placed here are automatically added to the campaign. This folder is accessible from the Images and Maps campaign list within many rulesets.

  • maskedimages = Data files about any mask layers placed on a campaign image.

  • moduledb = Data files to track any changes made to module data for this campaign.

  • portraits = Data files to track portrait image selections for PCs.

  • temp = Used during FG play to share assets

  • usersettings = User specific settings (i.e. GM hot keys)

The campaign folder contains the following files:

  • campaign.xml = Campaign meta data (Ruleset used and GM name)

  • chatlog.html = Output of chat log for entire campaign.

  • db.xml = Campaign data file

  • db.restore.xml = Backup of campaign data file created at session start. If computer or FG crashes, then this file will be saved to a db.backup.*.xml file on next FG launch.

  • db.backup.*.xml = See above.

  • db.script.*.xml = Some rulesets need to migrate campaign data when upgrading features. The original data file before migration is saved in this way.

  • extensionstate.xml = Tracks which ruleset extensions are used with this campaign.

  • modulestate.xml = Tracks which the permission and active state of available ruleset modules for this campaign.

  • windowstate.xml = Tracks the last position of windows within the campaign.