Developer Guide - Files Overview

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: 
License to produce Fantasy Grounds modules

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.

Images

Installation: To install new images, just place the image files into the images subfolder of the FG data folder or FG campaign folder. Tokens can be placed in folders for additional organization.

Image files can be used to show any graphical asset file within FG. Typically, images contain any image assets, which are not portraits or tokens (see below).

Any standard image file format can be used. While any image file size can be used, larger image files can increase player connection times and network lag. Here are the recommended token image file types and sizes.

Developer Guide - Product Guidelines

Portraits

Installation: To install new portraits, just place the PPK file (renamed ZIP file) or the image files into the portraits subfolder of the FG data folder or FG campaign 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; though a token is automatically generated from the portrait if no token otherwise defined.

Any standard image file format can be used. The default portraits are 100x100 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.

Developer Guide - Product Guidelines

Tokens

Installation: To install new tokens, just place the image files into the tokens subfolder of the FG data folder or FG campaign 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. While any image file size can be used, larger image files can increase player connection times and network lag. Here are the recommended token image file types and sizes.

Developer Guide - Product Guidelines

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:

• images = This is where images and maps can be added to a campaign. Any image files placed here are available in the campaign. This folder is accessible from the Assets window; and must be refreshed via the Assets window if file added while running a campaign session.

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

• portraits = Data files to track portrait image selections for PCs are stored here. Also, portrait image files can be added to this subfolder for the Assets window, just like images subfolder above.

• tokens = Token image files can be added to this subfolder for the Assets window, just like images subfolder above.

• 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.