Extensions are packages that modify or customize the operation of a ruleset, or add
additional functionality to one. They are separately installed. The user can activate any number of available
extensions per campaign.
An extension consists of files identical to those found in a ruleset, with the exception of the entry point
file extension.xml, which is described in more detail below.
Contain ruleset files
The process of activating extensions happens in the following order:
- The ruleset files are parsed and processed.
- The extension files are parsed and processed, in dependency order.
- Templates are processed.
- Controls such as desktop elements are created.
- Global ruleset script blocks are initialized.
- Extension script blocks are initialized, in dependency order.
This means that extensions can override resources such as graphics and window classes. Templates in extensions
affect the controls using them in the ruleset, due to them being processed before any controls are actually created.
The ruleset performs any initialization before any of the extensions are initialized.
All extensions reside in the extensions folder in the Fantasy Grounds application data folder.
Extensions can be packaged into a single file, identitifed by the .ext extension.
Folders vs. package files
All extensions must contain the extension.xml file, which is similar to the base.xml
file for rulesets, containing the root level definitions for extension contents. Extensions may also contain any
number of additional files, similar to rulesets.
The recommended development process for extensions is to first create a new folder under the extensions folder,
giving it a unique and descriptive name to match the purpose of the extension. Files should then be placed in this
folder. The application will recognize unpacked extensions created using this scheme, and ruleset reloading will
reload the latest version of the extension files as well, making development faster and easier.
Extensions can be packaged by using a zip archive program and adding all the files in the directory to a zip file.
The archive should not contain the folder for the extension. The package file should then be renamed to have a .ext
extension, and be placed directly into the extensions folder.
The extension.xml file
The extension.xml file contains the root level definitions for the extension, as well as extension
metadata such as its title, author and version. It also defines the dependencies (other extensions and/or rulesets)
that the extension requires.
Below is an example extension.xml file. The <base> element contains the ruleset definition
and has been omitted here for brevity.
<description>A simple demonstration extension providing
sheets for inputting town and city data.</description>
The <name>, <author> and <description> elements contain strings. The name must be
unique among the selection of modules, the others are simply information to the user and optional.
The <version> element is optional and should contain a number. The version may consist of two number
values separated by a '.' character, indicating a major and minor version, e.g. 1.2.
The <ruleset> element is described in detail below.
File search locations
All file references done in extensions are primarily looked up in the extension itself. If a file with the
same name is found in both the extension and the ruleset, the one in the extension is used. If no match is found,
the base ruleset package or folder is searched.
Versioning and dependencies
It is possible to create extensions that build on other extensions. Some extensions that may simply
introduce useful generic functionality such as scripts or templates, intended to be used by other extensions. For
this purpose, an extension can be defined as requiring dependencies. Optionally, it is possible to
give upper and/or lower limits for the version numbers of the dependencies accepted.
Extension dependency declarations are placed under the <properties> element in the extension.xml
file. The following is an example:
The <name> element defines the name of the extension required for this extension to be usable.
Both <minversion> and <maxversion> are optional.
Ruleset dependency declarations are placed under the <properties> element in the extension.xml
file. An example is given below:
The <name> element gives the name of a ruleset with which this extension is compatible.
The <minrelease> and <maxrelease> elements are optional, and refer to a ruleset release
number defined in the base.xml file of the ruleset itself. The number is given in the
release attribute to the <root> element in that file:
<root version="2.0" release="12">
You can define multiple rulesets as dependencies, to make the extension compatible with multiple rulesets.
If no ruleset dependencies are declared, the extension is usable with all rulesets.
Making extensions usable in an existing ruleset
An important thing to remember is that the general usability of extensions may depend very heavily on the
ruleset on top of which it is loaded. For example, the base ruleset might define the elements on the desktop
directly, in which case creating an icon on the desktop is not possible, short of redefining the entire icon
Ruleset designers are encouraged to take this aspect into consideration when designing their rulesets, and
possibly taking steps to make it easier to implement extensions in areas where they are deemed most useful.