Index of pages
Introduction
Resources
Windows and Controls
The Data Base
Scripting
Templates
Extensions



The campaign data base is the location where all the information about characters, adventures, monsters and other NPCs is stored. The data base is persistent, i.e. it is saved when a session is closed and loaded when a session is started.

Each campaign has its own data base. The data is physically stored in XML form in the file "db.xml" in the campaign folder.

Tree structure

All data in the data base is formed out of nodes. A node is either an internal node containing no values, but having any number of child nodes, or a value node containing one value of a specific type, having no child nodes.

The structure forms a tree with the value nodes at the ends of branches. Internal nodes typically represent successive levels of categorization or containment.

One typical structure involves content specific categorization on every odd numbered tree level, and an identifier enumeration on every even numbered level. An example of such a structure might be charsheet.id-00005.inventorylist.id-00001.name. Here, "charsheet", "inventorylist" and "name" refer to the name string of an item in the inventory of a character sheet. The identifier "id-00005" refers to a particular character sheet among many character sheets, and "id-00001" refers to a particular entry in the inventory.

Each node in the database, regardless of type, must have a name. Child node names must be unique in the scope of the parent node, i.e. an internal node cannot have multiple children with the same name.

Data base nodes implement the databasenode script interface.

Value node types

Value nodes are created automatically when a window containing value field controls is opened. They can also be created using the scripting interface. Each value node has a specific type.

Numbers

Number values contain a decimal number.

Strings

String values contain a string of text characters. The length of the string is not limited, but long texts may benefit from being represented as formatted text, instead.

Formatted text

Formatted text is a block of text comprised of paragraphs of different types and formatting elements.

Paragraph types available are normal text, title text, chat frames (usable as prewritten dialogue entries), lists and links (containing a window reference). Formatting options include bold face, italicized and underlined text.

Dice

Die value nodes contain a set of dice. The set can contain any number of dice of any type.

Tokens

Token values contain a reference to a token prototype. A prototype identifies a particular type of token, as opposed to a token instance, representing one of possibly several instances of a particular token in use on maps and images.

Images

Image values contain a bitmap representation of a drawing or an image. Image values containing an image bitmap can have a mask defining the portions of the image revealed to connected clients. All image values can contain drawing data on a layer separate from the image layer. Image values may also contain only drawing data.

An image can contain a grid overlay. Visualization tools called pointers are also available for image values, and take the form of arrows, cones, circles or squares. Image values can contain token instances.

Token instances, pointers, the grid setting and any mask or drawing layer data is stored in the data base for each image value.

Window references

Window reference values contain information needed to identify a window instance. They are typically used to store the information needed to open a window with particular data. They can also be used to refer to the data inside a window.

A window reference contains two string values. The first string identifies the window class used. The second string contains a node identifier (see below) referring to the window data source.

Module data

The data for each active module resides in its own data base tree. This allows more flexible data preparation for module design, and guarantees that interlinking data inside modules and between modules works predictably.

Global level node listings (such as those found in ordinary windowlist listings) include module data from the corresponding module trees as well, if such data is present. E.g. a windowlist that takes its data from the "images" node would also receive all child nodes of any "image" nodes under all activated modules.

Node identifiers

A particular node in the data base tree is identified using a data base node identifier string.

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

Absolute contexts may have a data source under which a relative lookup could be performed. In such a case, a dot character at the beginning of the identifier will cause a relative lookup instead. An example of this is the window list data source. Identifiers in a relative context may also include the dot character, but it will be synonymous with the case without it.

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 nodes with the dot character.

Examples of node identifiers

The following is an absolute identifier pointing to a name of an item in the inventory of a character sheet.

charsheet.id-00005.inventorylist.id-00001.name

The following is a relative identifier, pointing to the general AC total score from a character sheet node, used as a control data source.

ac.totals.general

The following, used as a window list data source, makes the identifier explicitly relative, and looks for the "inventorylist" node under the current data context.

.inventorylist

The following might be contained in a control on the spell list entry window class on the d20 ruleset's character sheet. It retrieves the save DC of a particular spell by traversing the database three levels up, then going into the "spellset" node for details on spells of a particular level for a particular class.

...spellset.set1.levels.level0.dc

Identifiers in modules

To access a particular node in the module data bases, a special identifier string syntax is used. Node identifier strings for module data are formed by following the procedure above, prefixing the identifier with the at character '@' and following with the complete name of the module.


'Fantasy Grounds' is a trademark of SmiteWorks Ltd. All other trademarks are the property of their respective owners.
2004-2010 SmiteWorks Ltd. ALL RIGHTS RESERVED.
Privacy policy