Fantasy Grounds operates on two kinds of information, which are defined and used separately.

First, the ruleset defines the sheets, views, and graphics used in viewing data. You can think of rulesets as blank sheets with places where you write up numbers, text and other data. In addition to this, rulesets also contain logic that defines how the different fields are interrelated, e.g. taking two numbers and entering their sum in a third automatically.

Second, the data entered and viewed using the ruleset are stored in the data base. The data base contains value fields of different types such as numbers, strings and dice. You can think of the data in the data base as the values on a sheet - the pencil marks left behind if all the ink was washed away from a traditional character sheet. Usually, the data base contains several instances of sheet data. You have a multitude of story book pages, character sheets and NPCs, but all the items of the same type are viewed on a similar sheet.

The ruleset and data base combine to create the exact representation of data contained in the data base. Fields on a character sheet, for example, are automatically generated in the data base when the character sheet is opened. The data is contained in campaigns or modules, whose primary function is to separate collections of data into chunks, used for a particular game or a particular purpose. All these can share a common ruleset for the view and presentation definitions, however.

Creating rulesets

If you want to make modifications to the sheets, views and/or logic used in a ruleset, or wish to create an entirely new presentation for a new game or set of rules, you will need to create a new ruleset and run your game using it.

If you wish to create new adventures, rule books, monster/NPC collections, spells or house rules, creating rulesets is probably not the right way. Instead, you would probably want to look at creating and distributing module files.

Creating the ruleset folder

The first step in creating a new ruleset is to create a folder for placing the ruleset files. The name of the folder is simultaeously the name of the ruleset, and should be unique. If you are making modifications to an existing ruleset, or creating a modified version of game rules defined elsewhere, it might be a good idea to add a personal bit to the ruleset name to avoid confusion with any other potential rulesets.

First, you should locate the application data folder. You should have a shortcut to it in the Fantasy Grounds start menu group. If you are looking for it in the file system, it is typically at:

• C:\Users and Settings\[Account name]\Application Data\Fantasy Grounds II (Windows XP)
• C:\Users\[Account name]\Application Data\Roaming\Fantasy Grounds II (Windows Vista)
• C:\Users\[Account name]\AppData\Roaming\Fantasy Grounds II (Windows 7)

In this folder, locate (or create) a folder called "rulesets" and navigate to it. Your ruleset folder should be created as a subfolder of this folder.

Ruleset files

Your ruleset is comprised of several files, all of which should be placed in or under the ruleset folder created above. All references to ruleset files are relative to this folder.

You can create subfolders under the ruleset folder in order to organize the ruleset files. To refer to them, prefix the file name referred to by the subfolder names separated by slash (/) characters.

XML files

The primary representation format for ruleset files is XML.

About XML

XML is a standardized format of presenting data. It does not define the structure of the information, but has some rules someone working with rulesets should know. The official specification for the XML can be viewed at http://www.w3.org/TR/xml/. Other useful introductory articles are listed below.

• XML in 10 points
• XML Tutorial
• A Quick Introduction to XML
• XML Tutoral (intermediate to advanced)

If you are having problems with XML documents, the following is a list of the most common errors causing XML document processing to fail.

• Closing tags are missing or invalid. XML tag names are case sensitive and opening and closing tags need to be similar.
• There are special characters present that are invalid. Check the encoding setting for the document and escape special characters. More information on encoding and escaping can be found in the XML specification and tutorials.
• Orphaned opening tags are not allowed. Singular tags (with no closing tag) need a trailing slash inside the tag (e.g. <noreset />)

The starting point - base.xml

The loading of a ruleset starts with processing a special ruleset file called base.xml. This file has to be present in all rulesets. Usually, the contents of the file are used to include additional XML files.

Using <includefile>

It is a good idea to split the ruleset into several files, organize their contents by type and topic, and include them from other XML files. The base.xml file can act as the top level inclusion point, from which other include branches start.

The <includefile> definition inserts the contents of the specified file at the point in the source file where the include definition appears. The included file can contain further <includefile> definitions.

This directive should only be used to include other ruleset definition XML files. Other files such as graphics and Lua script files are included using defintions dedicated to this purpose, and will be covered later in the documentation.

Using the ruleset reference documentation

All the available XML elements and their structure are detailed in the ruleset reference documentation. This documentation is split into pages for each element and object. The XML definitions are presented in the Definition section on each page.

All elements do not have a definition section. This means that the element is not definable in XML, and is only usable by using scripting.

Some elements are valid only in a specific context, such as controls that should be defined inside a window class definition. The Context entry at the top of each element's page indicates if it is constrained to a particular context, and the context element.

Using the 3.5E or 4E ruleset as a basis

Starting from scratch with a new ruleset is a large effort. Even if you do decide to undertake this task, it's good to have a set of examples to guide you. The 3.5E and 4E rulesets bundled with Fantasy Grounds can be used as a starting point for modifications, large or small, and also as a source of examples.

Extracting the 3.5E or 4E ruleset files

The rulesets for 3.5E and 4E are located in the program folder at "C:\Program Files\Fantasy Grounds II". By making a copy of the 3.5E.pak and 4E.pak files, then renaming the files to .zip, you can open the ruleset files using Windows or your favorite ZIP file utility. Extract all the files to a new folder to begin making modifications to the ruleset.

Using a custom ruleset

To use a custom ruleset within FG, you can create a new subfolder in the FG2 application data folder directory (a link is included in the FG2 Start Menu directory). Set the name of the new subfolder to the name you want FG to display on the launcher screens. Copy all of your customized ruleset files into the new subfolder. In order for FG to recognize a custom ruleset, it needs to be able to find [FG app data folder]\rulesets\[Ruleset name]\base.xml in the custom ruleset directory.

Rulesets can also be compressed into a single ZIP file with the base.xml in the root of the ZIP file, and the file renamed with the extension .pak. The name of the ruleset in this case will be the name of the compressed ZIP file without the .pak extension. (Ex: A 4E.pak file would be interpreted as a "4E" ruleset definition.) These compressed ruleset files should be placed in the [FG app data folder]\rulesets\ directory.

The loading priority for rulesets is: App data subfolders, App data PAK files, FG2 built-in PAK files

Keeping up to date

The built-in rulesets are constantly being updated. If you make your own version of a built-in ruleset or want to grab new features, make sure to look at the ruleset files again after each release, and review the release notes.

Distributing rulesets

After you have created your custom ruleset, others need to have access to the ruleset as well, in order to use it in a game.

Client auto download

Clients connecting to a session hosted by you using your own custom ruleset will automatically download a copy of your ruleset without any further need to distribute it. Any updates you make to a ruleset between sessions will be updated when clients connect to your session a second time.

Making rulesets publicly downloadable

To distribute rulesets, you need to package the contents of the ruleset folder, and deliver the files to the interested person(s). If maintaining compatibility with campaigns and modules is required, care should be taken to make sure the ruleset name remains the same when the ruleset files are installed on another computer.

Code and graphics included in the built-in FG rulesets can be distributed freely as part of other FG rulesets, as long as the new rulesets are made freely available. If you wish to build an official ruleset for your favorite gaming system, please drop us a note at [email protected].