Developer Guide - Extensions

1 Overview
2 Details
3 Easiest Way
4 Best Practices

Overview

Extensions within Fantasy Grounds are the way that rulesets can be customized within a campaign. Extensions can be used to add new graphics (such as a desktop decal or full theme replacement) or to modify behavior (such as house rules or new features).

Details

Any number of extensions can be opened within each campaign in order to customize that campaign. Since rulesets and extensions are written by different authors, conflicts can arise with the ruleset (especially when rulesets are updated) or between extensions (such as extensions that try to modify the same assets). When working with extensions make sure that you have the latest version of the extension from the developer who made it, and that they have verified that it works with the ruleset version or other extensions you are working on. The order that extensions load can be controlled by specifying a loadorder tag within the extension properties.

Any extensions that are enabled on a GM client will be automatically downloaded and enabled for each player during the game session.

At a technical level, extensions are defined almost exactly like rulesets, with a few minor file name and tag definitions. Also, they work like ruleset layers, and extension changes are applied after all ruleset layers are loaded.

Easiest Way

The easiest way to create an extension for Fantasy Grounds is to copy an existing extension, give it a new folder/file name, and begin modifying the extension in small ways. This allows you to get used to how FG allows you to define the user interface and game mechanics. As you become more comfortable with making changes, you can take on bigger changes, and eventually learn to create your own full-fledged ruleset.

Another easy way to create an extension is to define a very bare bones extension, begin overriding specific graphic or other assets in a small way and moving on to bigger changes. Below is a very barebones extension extension.xml definition example to use. Make sure to put this extension.xml file in a new folder under the extensions folder in the FG data directory.

<?xml version="1.0" encoding="iso-8859-1"?>
<root version="3.3" release="1">
  <announcement text="Test extension v3.3.2 for Fantasy Grounds" font="emotefont" icon="rulesetlogo_CoreRPG" />
  <properties>
    <name>Test Extension</name>
    <version>1</version>
    <author>SmiteWorks USA, LLC</author>
    <description>Test extension for CoreRPG ruleset</description>
    <ruleset><name>CoreRPG</name></ruleset>
  </properties>
  <base>
  </base>
</root>

Best Practices

Here are some best practices for building FG extensions:

When possible, try to avoid overriding core windows or global scripts. Instead, use window class merging or template replacement to override specific behavior. If you override core windows or global scripts, your extension will be more likely to require maintenance when the ruleset is updated.
Watch the Fantasy Grounds Laboratory thread for announcements of beta versions of the FG software and built-in rulesets. This will allow you to test your extension on the latest version many weeks in advance of the actual release.
If you are replacing window class assets, template assets or global scripts, make sure to save off a copy of the ruleset files that contain the assets or scripts you are changing. In this way, when a ruleset update is made, you can simply compare the ruleset file you based your extension on to any new ruleset file updates to see any changes. This will help you more quickly update your extensions when rulesets are updated.