Developer Guide - Rulesets - Database

From Fantasy Grounds Wiki
Jump to: navigation, search

Introduction

The campaign database is the location where all the campaign information about characters, adventures, monsters and other NPCs is stored. The data base is saved when a session is closed and loaded when a session is started. Each campaign has its own database. The data is physically stored in XML form in the file "db.xml" in the campaign folder.

File Structure

See the Campaign and Module Data File Overview topic for more details on the file structure.

Interface Interaction

Every window can be optionally assigned a database path. Many window classes used to build windows within a ruleset will assume that they are assigned a database path when opened (such as NPC records). Any window controls within a window can be database bound or unbound. If the window controls are database bound and part of a window which has a database path, then they will attach themselves to the child database nodes with the same name as the control under the window database path. If the child database node does not exist, then the database bound window control will create a new child database node with the same name. Window control types exist for all the matching database data types (string, number, formattedtext, dice, image, token, windowreference)

Database Paths

When referencing a specific database node from within a ruleset, the ruleset will use a database path string (sometimes referred to as a database node identifier string in the API docs).

Depending on the context where the database paths are used, they can be either absolute or relative. Absolute database path contexts look for the specified node under the root of the database. The most common uses for absolute database path contexts are database paths specified for window classes and window list controls. Relative database path contexts look for the relative path as a subpath under the current database path (which is context dependent). A common example of a relative database path context is the database path for a window control, which tries to find the named node under the window database path.

Absolute path contexts may have a database path under which a relative database path lookup could be performed. In this case, a dot character at the beginning of the identifier will cause a relative lookup instead. An example of this is the window list control database path. If a dot character is included at the beginning of a relative database path context, it will be the same as if it was defined without one.

Adding further dot characters after the first to the beginning of the identifier will cause a corresponding number of steps upwards in the tree structure. Steps deeper into the tree can be specified by separating successive node names with the dot character.

To differentiate between the campaign database and module databases, a special database path string syntax is used. First, database path strings for modules are formed exactly as above (specifying the path within the module database). Then, the path is prefixed with the at character ('@') and following with the complete name of the module.

Examples

Path Description
charsheet.id-00005.inventorylist.id-00001.name Absolute Path. Used as an API reference path. Points to a name of an item in the inventory of a PC sheet.
ac.totals.general Relative Path. Used as a number control source. Points to the general AC total score from a PC sheet database node.
.inventorylist Absolute Path, with relative override. Used as a window list control source.Points to the inventory database node from a PC sheet database node.
...spellset.set1.levels.level0.dc Relative Path. Used as a number control source. Given the current database node, traverse up two levels, then follow the "spellset.set1.levels.level0.dc" subpath.
[email protected] Basic Rules Absolute Module Path. Used as a window database path. Points to a class record within the "3.5E Basic Rules" module.