Campaign and Module Data File Overview

From Fantasy Grounds Wiki
Jump to: navigation, search

See the Data Files Overview topic for more information on general file locations, all campaign file listing, module installation and module packaging.

Campaign Data Files

Campaign data files are stored as XML in a db.xml file in the specific campaign folder. See below for the data file format shared by both campaign and module files.

Note: If you choose to edit the campaign db.xml files directly for any reason, we highly recommend you make a backup before editing to avoid data loss. A failed database load will load an empty database, which will then be saved on exit for that campaign.

Module Data Files

Every module requires a definition.xml file in the root of the module folder or the root of the .mod file. If any data is included in the module, it will be included in a db.xml file (for GM data) or a client.xml (for player data). Any images (handouts, maps) referenced by the XML data files will need to be included as well. Also, any image files included in a "tokens" subfolder within the module will be added to the GM token bag when loaded. Finally, a thumbnail.png file can be placed in the root of the module folder or the root of the .mod file to be displayed in the module activation interface.

Module Definition File Structure

The definition.xml consists of the following tags:

Root Element
<root> The main root node contains all the meta-data for module definition files.
Root Attributes
version The string matching the version number of the FG client version that uses this data format (Ex: "3.3")
release 3.5E:17|CoreRPG:3")
Root Sub-Elements
<name> The module name used to uniquely identify the module data and tokens. This name is used in all links to module data. As of v3.3.2, if no module name specified, then the file name will be used.
<displayname> Requires v3.3.2. The module display name to show users in the module activation interface. If no display name specified, then the module name will be used.
<category> The module category to group this module under in the Library.
<author> The module author to display in the module activation interface.
<ruleset> Multiple tags allowed. The rulesets for which this module can be used. If "Any" specified, then this module can be used in any ruleset. (Ex: token packs, map packs)
<replaces> Multiple tags allowed. Specifies any module names which this module overrides. Any links to the old module name will be redirected to this module, as long as the old module is not open.

Campaign and Module Data File Format

All data within Fantasy Grounds is stored as a tree structure, with a root node for the campaign and each module as the starting point. The root tag and any subtree child tags can have any number of additional child tags. A subtree node is a tag with no data type attribute, and can have child tags. A leaf node is a tag with a data type attribute, and can not have child tags. There is no defined limit on the amount of tags which can be nested in a data file.

Root Element
<root> The main root node contains all the meta-data for module definition files.
Root Attributes
version The string matching the version number of the FG client version that uses this data format (Ex: "3.3")
release 3.5E:17|CoreRPG:3")
Root or Child Tag Sub Elements
<category> This tag specifies that any children of this tag belong to a given category. This tag has a name attribute. By default, the module name is assigned as a category to all uncategorized module data.
<public> Internal tag, should not be used in modules. Makes the parent tag public to all users. The data will be sent to all player clients on connection to a campaign.
<holder> Internal tag, should not be used in modules. Makes the parent tag accessible to a specific user denoted by the name attribute of this tag. The data will be sent to the client with the given name on connection to a campaign. If the owner attribute is set to "true", then the player is also marked as the owner of this record, and can make changes. Only one player can own a record at a time, but the GM can always edit.
any other valid XML tag The root tag or any other subchild of the root tag can have any number of child tags
Child Tag Attributes
static If the child tag has the static attribute, then the database node corresponding to the child tag. This attribute is only valid for subtree nodes (i.e. no data type).
type If the child tag has a valid data type attribute, then the corresponding database node is considered a data value and a leaf node. The type attribute can be one of the following: number, string, formattedtext, image, token, dice, windowreference (link). If no type attribute is specified, then the corresponding database node is considered a subtree node. No child tags placed under this tag will be processed, unless they relate to the corresponding data type.

CoreRPG Data File Format

With the CoreRPG ruleset and those rulesets derived from it, the ruleset assumes that records are laid out within specific data paths within the data file. Each child of the corresponding paths is considered a complete record of that type. The individual subtree and leaf nodes within each record type vary dramatically by ruleset.

The best way to see an example of the data file format for a specific data type is to create a record of the desired type within a campaign, and view the campaign db.xml file in a text editor after saving the campaign.

Here are the standard CoreRPG data record paths for editable record data:

  • charsheet = PC data
  • notes = Notes data
  • encounter = Story data
  • storytemplate = Story template data
  • image = Image and map data
  • quest = Quest data
  • npc = NPC data
  • battle = Encounter data (i.e. NPC groups)
  • battlerandom = Random encounter data
  • item = Item data
  • treasureparcels = Parcel data (i.e. Item groups)
  • tables = Table data
  • modifiers = Modifier data
  • effects = Effect data
  • library = Library data

Additionally, the standard for modules within the CoreRPG ruleset is to specify the "reference" path as read only. Thus, the standard CoreRPG data record paths for read only data are:

  • reference.encounters = Story data
  • reference.storytemplates = Story template data
  • reference.quests = Quest data
  • reference.images = Image and map data
  • reference.npcs = NPC data
  • reference.battles = Encounter data (i.e. NPC groups)
  • reference.battlerandoms = Random encounter data
  • reference.items = Item data
  • reference.treasureparcels = Parcel data (i.e. Item groups)
  • reference.tables = Table data

Also, there are standard paths used within the CoreRPG ruleset to store tool data:

  • combattracker = Combat tracker data
  • partysheet = Party sheet data
  • calendar = Calendar data
  • export = Export data
  • options = Option data

CoreRPG Data Guides for Specific Cases

Some data records within CoreRPG have specific guides, since they are not handled by the standard export interface (such as reference manuals or pregen characters), or just because further documentation was found to be useful.

For building a reference manual within a module, see the Reference Manuals topic.

For adding pregen characters to a module, see the Pregens topic. The detailed structure of the PC data in the pregen records should match the PC data structure for the ruleset it is built for.

For understanding and modifying the way data is presented in the library for a module, see the Library Data topic. The presentation of the library data is done automatically for export modules, but is limited to links to lists of exportable record types.