Data Structure Overview and Best Practices

From Fantasy Grounds Wiki
Jump to: navigation, search


The database files generated by Fantasy Grounds (FG) are XML data files with FG-specific organization, structure, tags and attributes. There is no specific document definition for the FG database files, since the structure of the database is almost completely described by the ruleset used within FG. Since FG is a constantly evolving platform, the database file structure may change.

The specifics of the current FG database file structure are documented in this pseudo-XSD file.

Updated on September 2, 2016 using Fantasy Grounds v3.2.0.

Best Practices

Here are a few best practices to keep in mind when creating modules for Fantasy Grounds.

  • Unique records = When creating a record for a creature, item, etc. in your module, only create a single copy of the record within your data, and link accordingly.
  • Adventure vs. Rulebook = When creating modules, make sure to place adventure data in the campaign data path, and any rulebook data (such as bestiary, lookup tables, etc.) in the reference data path.
  • Separate Adventure Data = When a rulebook contains a sample adventure, create a separate module with the sample adventure data, and link from rulebook module.

Data Structure

Within the root database tag defined for each database file, the ruleset determines which tags are used to store information. In order to provide some consistency across game systems for easier tool creation and re-use of ruleset code, the following structural guidelines should be used for defining ruleset data structures. The subsequent section will document any known differences for popular rulesets.

Each record type has a specific base data path that is recommended for storing records of each type. If a ruleset has need of another record type, a similar data path should be defined and used. It is assumed that any records stored in the base data path are editable by the GM within his campaign.

For data modules, any data should be broken down into separate modules for reference/rulebook material vs. adventure material. Also, reference/rulebook data should be broken up into separate module files for player material (character options, etc.) and GM material.

Within each data module, all reference/rulebook material should be placed in an alternative data path marked with the static attribute to make the data read only, while the adventure material should be stored in the base data path. See below for specifics data paths recommended.

Please note that many DLC products on FG were created before these considerations were documented, so may or may not follow these guidelines. Our goal is to migrate products when possible to maximize compatibility. The only rulesets reviewed thus far are: CoreRPG, 3.5E, 4E, 5E, PFRPG, SavageWorlds, FateCore, Numenera, CallOfCthulhu, Castles and Crusades.

Data Paths - Adventure Module

or each record, there should be a single subchild for that record under the base data path for that record type defined below, with any additional fields for the record defined under that subchild. We recommend a "name" string field with denotes the name of the record. If the record supports an identification state, we also recommend a "nonid_name" string field which denotes the unidentified name of the record. If different types of each record need to be tracked, we recommend using a "type" string field to differentiate, instead of using additional data paths. All other fields can be defined by the ruleset as needed.

The following list details the base data path that is recommeded to be used for common RPG record types used by rulesets.

  • "battle" = Encounters (groups of NPCs)
  • "battlerandom" = Random Encounters (groups of NPCs with random numbers of each NPC)
  • "charsheet" = PCs (player characters)
  • "effects" = Effects
  • "encounter" = Stories (adventure material)
  • "image" = Images and Maps
  • "item" = Items
  • "modifiers" = Modifiers
  • "notes" = Player Notes
  • "npc" = NPCs (non-player characters)
  • "quest" = Quests
  • "storytemplate" = Story Templates (templates to generate story entries from tables and random numbers)
  • "tables" = Rollable Tables
  • "treasureparcels" = Parcels (groups of items)

Here are additional recommended base data paths used in specific rulesets.

  • "pregen" = Pregens (SW)
  • "spell" = Spells (5E, CnC)
  • "vehicle" = Vehicles (SW)

Here are any exceptions noted in existing rulesets, but are not recommended usage for new rulesets.

  • "combat" = Encounters (SW)
  • "modifier" = Modifiers (SW)
  • "effect" = Effect (SW)

Data Paths - Reference/Rulebook Module

Similar to above, this list details the alternate data paths recommended for read-only reference/rulebook material for common RPG record types. Generally, we recommend placing these records under a top-level reference tag marked as static, and using a similar subpath as the base data path.

  • "reference.battles" = Encounters
  • "reference.battlerandoms" = Random Encounters
  • "reference.items" = Items
  • "reference.npcs" = NPCs
  • "reference.quests" = Quests
  • "reference.tables" = Rollable Tables
  • "reference.treasureparcels" = Parcels
  • "reference.vehicles" = Vehicles

For other standard RPG record types, these are typically used for campaign/adventure material only ("battle", "charsheet", "encounter", "image", "notes", "quest", "treasureparcels").

Here are additional recommended reference data paths used in specific rulesets.

  • "reference.armor" = Items - Armor (3.5E, CnC, SW)
  • "reference.ammunition" = Ammunition (SW)
  • "reference.archetypes" = Archetypes and Pregens (SW)
  • "reference.classes" = Classes (3.5E, CnC)
  • "reference.edges" = Edges (SW)
  • "reference.feats" = Feats (3.5E)
  • "reference.hindrances" = Hindrances (SW)
  • "reference.humans" = Human NPCs (SW - Deadlands)
  • "reference.races" = Races (3.5E, CnC)
  • "reference.powers" = Powers (SW)
  • "reference.skills" = Skills (3.5E)
  • "reference.spells" = Spells (3.5E, CnC)
  • "reference.weapons" = Items - Weapon (SW)

Here are any exceptions noted in existing rulesets, but are not recommended usage for new rulesets.

  • "reference.backgrounddata" = Backgrounds (5E)
  • "reference.classdata" = Classes (5E)
  • "" = Items (3.5E, CnC)
  • "reference.equipmentdata" = Items (5E)
  • "reference.featdata" = Feats (5E)
  • "reference.magicitemdata" = Items (5E)
  • "reference.magicitems" = Items (3.5E, CnC)
  • "reference.monsterdata" = NPCs (CnC)
  • "reference.mundaneitems" = Items (SW)
  • "reference.npcdata" = NPCs (3.5E, 5E, CnC)
  • "reference.racedata" = Races (5E)
  • "reference.skilldata" = Skills (5E)
  • "reference.spelldata" = Spells (5E)
  • "reference.weapon" = Items (3.5E, CnC)
  • "spelldesc" = Spells (3.5E, CnC)