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.

Extension files

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.

File location

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.

<root version="2.0">
  <properties>
    <name>Town sheet</name>
    <version>1</version>
    
    <author>SmiteWorks Ltd.</author>
    <description>A simple demonstration extension providing 
      sheets for inputting town and city data.</description>
    
    <ruleset>
      <name>d20</name>
      <minrelease>12</minrelease>
    </ruleset>
  </properties>
 
  <base>
    ...
  </base>
</root>

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 dependencies

Extension dependency declarations are placed under the <properties> element in the extension.xml file. The following is an example:

<dependency>
  <name>Test Dependency</name>
  <minversion>1</minversion>
  <maxversion>1</maxversion>
</dependency>

The <name> element defines the name of the extension required for this extension to be usable. Both <minversion> and <maxversion> are optional.

Ruleset dependencies

Ruleset dependency declarations are placed under the <properties> element in the extension.xml file. An example is given below:

<ruleset>
  <name>d20</name>
  <minrelease>12</minrelease>
  <maxrelease>12</maxrelease>
</ruleset>

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

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.