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:

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.

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.

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.

Warning

Creating a ruleset named "3.5E" or "4E" will result in the custom ruleset overriding the built-in rulesets.

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

Warning

Please make sure you have permission if you are considering distributing rulesets involving copyrighted material or intellectual property owned by
someone else. A good rule of thumb is to always ask for permission first.

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