Ruleset - Assets

1 Introduction
2 Icons
- 2.1 Example
3 Strings
- 3.1 Example
4 Frames
- 4.1 Examples
5 Fonts
- 5.1 Examples
6 Dice
- 6.1 Examples
7 Portraits and Portrait Sets
- 7.1 Examples
8 Tokens
9 Window Classes
10 Templates

Introduction

Rulesets and extensions contain many definitions for assets that are used to implement the user interface and logic. These include graphic assets, such as icons and fonts, as well as user interface assets, such as window classes and templates. All assets are reference by their name attribute for use within the ruleset. Also, any file references are considered to be relative to the ruleset or extension folder/file where the asset is defined.

This topic will cover the individual asset types that can be defined within a ruleset.

Icons

Icon assets define simple images, usually used to represent a symbol or a user interface element such as a button. Icon images are usually relatively small, and will be scaled down to fit the size of the interface element they are used within.

Several image file formats are supported, but the recommended choices are PNG and JPG. These formats are widely available and create reasonably small file sizes. PNG images also have good transparency support and do not suffer from image degradation.

Example

<icon name="button_maps">icons/button_maps.png</icon>

Strings

String assets define text strings that can be referenced by windows, controls and scripts within the ruleset. By using string assets instead of defining the strings directly, the ruleset can more easily be modified by extensions to support other languages.

Example

<string name="sidebar_tooltip_ct">Combat Tracker</string>

Frames

Frames assets are graphical elements that draw a rectangular background image. They are typically used as window and control background graphics that are capable of adjusting to the size of the element.

Frames are built from rectangular sections that comprise the corners, edges and center of the frame. The corner sections are always drawn once, at each corner. The left, right, top and bottom edges are formed by repeating the corresponding section as many times as needed to complete the frame at the specified size. The center piece is tiled, i.e. repeated both vertically and horizontally, to fill the remaining gap in the middle. This type of graphic asset is usually referred to as a 9-slice image, and you can find information online about this topic, such as this external link on 9-slice sprites.

All frame sections are defined within a single image, and do not have to be laid out in a grid (though that is the easiest way to visualize).

Frames are defined using the framedef tag, specifying the bitmap to use, and the location of the sections on that bitmap. Each section definition comprises of four numbers, separated by commas. The numbers are measured in pixels and their meanings are:

The zero-based horizontal pixel offset of the top-left corner of the section
The zero-based vertical pixel offset of the top-left corner of the section
The width of the section
The height of the section

If any sections are omitted, they are assumed to be empty. Empty sections are ignored when building frames. Also, the sections can also be defined using the offset tag where the left, top, right and bottom offsets are applied to the frame graphic automatically to create the sections.

If frames are drawn smaller than the total size of the corner pieces, the resulting output may look garbled. Care should be taken when defining elements to make sure the element is not too small for a frame. Windows and controls using frames should use a minimum size constraint to guarantee valid appearance.

The following two examples illustrates the definition of a frame using individual section definitions as well as the offset method.

Examples

<framedef name="minisheet">
  <bitmap file="frames/minisheet.png" />
  <topleft rect="0,0,15,15" />
  <top rect="15,0,250,15" />
  <topright rect="265,0,16,15" />
  <left rect="0,15,15,249" />
  <middle rect="15,15,250,249" />
  <right rect="265,15,16,249" />
  <bottomleft rect="0,264,15,16" />
  <bottom rect="15,264,250,16" />
  <bottomright rect="265,264,16,16" />
</framedef>

<framedef name="minisheet">
  <bitmap file="frames/minisheet.png" />
  <offset>15,15,16,16</offset>
</framedef>

Fonts

Font assets determine the appearance of text within the user interface. Fonts have three properties, the font file to use, the default color to use for this font, and an optional shadow tag to define background shadows. Font colors can be overridden in most controls that use font assets.

For Fantasy Grounds Unity, font files can only be TrueType fonts (.ttf). Fantasy Grounds fonts (.FGF) are no longer supported in Fantasy Grounds Unity (v4.0 and up).

Fantasy Grounds Classic still supports the legacy .FGF format. The FGF font files can be creates by using the Font Generator utility.

Examples

Dice

Dice assets are used by the system for handling the 3D dice on the desktop, for use die database values and window controls, and for generating die rolls based on the ruleset logic.

Built-in Dice

There are seven kinds of basic built-in 3D dice:

d4 = Four sided die
d6 = Six sided die
d8 = Eight sided die
d10 = Ten sided die
d12 = Twelve sided die
d20 = Twenty sided die
dF = Fudge die, which is a cubical die with 2 sides each of plus sign, minus sign or blank side, returns values of -1, 0, or 1

If any of these dice are defined using the "die" tag, the 3D models of these dice are automatically added to the campaign desktop on load within this ruleset.

Each of the built-in dice needs to be associated with a default location on the desktop, as well as an icon resource that represents the image displayed for roll results in the chat window. This is done with the die tag.

Custom Dice

Custom dice are die types based on one of the built-in dice, with the option to assign custom values to the die result. The built-in die on which the custom die is based is will be used as the 3D model for the roll. Custom dice do not appear on the campaign desktop, and the option to roll the custom die will be found in the right click menu of the associated built-in die.

A script function can be associated with a custom die. The script function receives the result of the built-in die rolled, and can apply modifications to the result before it is passed on for further processing.

An example below defines a d3 (three sided die), generating a value from 1 to 3, by dividing the result of a d6 by two.

Special Case

There is one additional built-in 3D die type that does not need to be defined:

d100 = Percentile tens die, returns value of 00 to 90

The percentile tens die is not placed on the desktop like the other basic dice, but a d100 options is automatically added as a right click menu for the basic d10 die (if defined). Also, when a percentile tens die is selected, a d10 will also be added to the drag dice pool. The d100 is always available, and does not need to be defined.

Percentile dice in Fantasy Grounds have a slightly different convention than most RPGs. The d100 die and the d10 are always added together. So, a 00 on the d100 die, and a 10 on the d10 die, will return a value of 10 (00+10); and a 90 on the d100 die and a 10 on the d10 die, will return a value of 100 (90+10). While this convention is slightly different than the most most way to interpret percentile dice, it still correctly returns a range of 1-100.

Examples

Portraits and Portrait Sets

Player clients can select portrait images for any of their player character (PC) identities. These portrait images are then used to automatically generate icon assets based on any portrait set definitions in the ruleset. An icon generated in this way will be automatically updated when the PC identity portrait is changed. These icons can be used as usual in any context that icon assets can normally be used.

Portrait sets are defined using the "portraitset" tag. The portrait icon asset is formed by first scaling the portrait image to the size of the icon asset defined as the mask for this portrait set. The resulting icon is then masked by copying the transparency information from the mask icon asset. Finally, the resulting icon is composed with the icon asset defined as the base for this portrait set, using the base icon as a background image.

Icons generated from portrait sets are named according to the name of the portrait and the internal ID of the PC identity ("portrait_[identity identifier]_[portraitset name]") (Ex: portrait_id-00001_charlist).

If the createtoken tag is added to a portrait set definition, a token asset with the same name as the icon will be defined.

Examples

Tokens

Tokens are not specifically defined as assets within Fantasy Grounds, but are added automatically when graphic files are placed in the correct file location. Within rulesets, any graphic files within a "tokens" subfolder will be automatically added to the campaign using the ruleset. Any tokens added from a ruleset will have a token name of "ruleset/[ruleset_name]/[token_path]".

Window Classes

Window classes are asset definitions that define the way that the user interface works within a ruleset. The full breakdown of the window class asset is given in the Rulesets - Interface topic.

Templates

Templates are asset definitions that can be used to extend or centralize window control definitions for use within window classes. The full breakdown of the template asset is given in the Rulesets - Templates topic.