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