Module Making Manual v 1.2 -by SoulOfTheReaver 1 Intro 1.1 Stuff you'll need 1.

2 XML Primer 2 FG2 general style Tags 3 The module 3.1 The structure of the Module 3.2 The libraries section 3.2.1 Library header 3.2.2 Library Entries 3.2.2.1 Window Classes 3.2.2.2 Links 3.2.2.3 The referencetext class 3.2.2.4 The referenceindex class 3.2.2.5 The npc and item classes 3.2.2.6 The feat class 3.2.2.7 The skill class 3.3 The reference section 3.4 The image section 3.5 Adventure module sections 4 Final thoughts Errata Making library modules without XMLs 1 - Intro So you wanna make a library module for your favourite game system, but don't know where to start? Well you've come to the right place. Fantasy Grounds 2 makes good use of a rather intuitive and human readable method of defining and storing everything from its user data to the very windows and rules of the software in the form of XML (extensible markup language) files as well as a bit of LUA scripting for the rulesets. This makes it extremely customizable, as the many community rulesets available stand testament. If you have a knack for programming there is ample documentation on making and changing rulesets on the FG2 website. Making adventure modules to store and transport encounters, items, NPCs and tokens is not a mystery either thanks to Xorne's excellent video tutorials found here. Now many rulesets also come with a library that can have anything from game rules to monster manuals or lists of feats or magic items, either for free (like Complete SRD) or for sale on the FG2 store. But what if neither of these is the case for your ruleset? FG2, while otherwise admirably well documented (as shown above) has little to no information on making library modules. Information on this subject is scarce and available only as snippets of information that you must hunt down on the forum. Failing that you have to learn to do so yourself by poking around in a module's guts. Having done that, I've decided to write this little guide to make the life of those that would do the same a bit easier. As I'm sure you've noticed by watching Xorne's videos you can easily export adventure modules from within FG2 itself, building them with the game's internal text editor and NPC character sheets and whatnot. This is not possible for Library modules. I've recently learned this is not true, you CAN use FG2 itself to make rudimentary library modules but using this method is highly limited in what you can do with it. If you want to learn more check out the errata at the end.

Designing a proper library still requires you to get dirty and go under the hood. Fret not however, you CAN make them, you just need a bit of patience, a bit of info(found here) and a few simple tools; this brings me to our first order of business: 1.1 - Stuff you'll need Technically all you'll need is notepad, but these tools help make your life a bit easier: Any archiving program that can open ZIP files. I use WINRAR. A dedicated XML editor like XML Marker. Get it. You'll thank yourself for it. A basic HTML editor to help with writing reference pages. You can technically use FG2's internal editor but that one doesn't have support for making tables, and those are a bother to do by hand. Basic knowledge of writing HTML. This guide assumes it. If you don't have it, learn what an HTML tag is, and learn to properly use the most basic ones. Now let's get down to business. 1.2 - XML Primer (skip to the next section if you know XML and/or Kung Fu) eXtensible Markup Language is a machine-independent, human readable way of storing and transporting data. It is very similar to HTML in concept but where HTML's purpose is to format and display data, hence well-defined tags, XML is designed to organize and store it. This means that it has no predefined set of tags, those are up to the software reading it, in this case FG2. This also means that you can make up your own tags where appropriate. It does however have a few rules that you should know about and keep in mind. I'm listing them here in order to avoid common mistakes and make sure your modules work as intended: - All XML files start with a declaration that looks like this
<?xml version="1.0" encoding="ISO-8859-1"?>

It mentions the XML version and the character set (in this case Latin-1/West European)Don't forget to include that if you're building a module from scratch. - The first tag that comes after the declaration is the root element. The XML must start and end with that tag. For most XML documents the root element is simply <root>, which should be the second line after the declaration(empty lines don't count). Conversely the last line should be </root>, ending the tag. Please note that in FG2 the root element must have a version attribute like so
<root version="2.0"> -

without which the module will not be recognized! - That reminds me make sure every tag is properly closed. XML marker will scream at you if you leave any open ones by the way. While you're at it make sure that: - All tags must be properly nested. Simply put
<b><i><u>text</u></i></b>

is correct, while
<b><i><u>text</i></b></u>

is not! Close child tags before closing their parent tags. Don't let them overlap. - When naming tags you can use letters and numbers as well as special characters. Stay away however from the characters ./:$& for obvious reasons. Also don't start the tag name with a number. Finally, be careful when giving tags names so they don't conflict with dedicated FG2 tags, more on those later. - When giving tags attributes don't forget to quote the value, like so:
<name type="string">

If you need to type & within your text, use &amp; which is an entity reference, to avoid conflicts. There are more. Google them. While you're at it Google XML Tutorial for more information.

2 - FG2 general style Tags While XML has fully customizable tags, FG2 uses some in common with HTML where text formatting is concerned. That said it doesn't use all HTML tags, and of those it uses, some work differently. Furthermore it has some of its own custom style tags. I'll reference each here: Tags that function like their HTML counterparts: <p> - simple paragraph tag. Nuff said. <b><i><u> - Bold, Italic, Underline. <table> - limited compared to HTML: The border attribute doesn't work. Use the decoration="underline" in the <tr> tags to draw the table lines. Colspan works but rowspan does not. Tags also found in HTML but with a different function: <frame> - syntax is like that of <p>. It makes a chatbox with draggable text. <list> opens a bulleted list like <ul> would in HTML. Each item must have the <li> tag as normal. FG2's custom formatting tags: <h> is a paragraph tag with a different font. Heading basically. <listlink> and <link> are the link tags from within text windows. Very important tags. More detail here. 3 - The module OK now we're getting to the juicy part! What's in a module? that which we call a .mod by any other name would smell as sweet; which is to say not at all because all a .mod file is, is basically a ZIP archive renamed. You can find plenty of them that come with FG2 in the program's application data folder under the Modules sub-folder. Check them out, snoop around, they can be a treasure trove in helping you understand how to make your own. To open them just rename them temporarily to .zip or even better get your archiver to be the default software to open .mod files, well unless you're into old-school music formats, but don't worry about it if you didn't get that. Inside a module you'll usually find two files, possibly three. One is called definition.xml, which is basically a label for the module. It looks sort of like this:
<root version="2.0"> <name>Complete SRD Monsters</name> <author>Digital Adventures, LLC.</author> <ruleset>d20</ruleset> </root>

First is the <name> as it will show up in your library. <author> is self explanatory, and <ruleset> is what ruleset it will work with. Must be exactly as the ruleset's folder name. Case sensitive, as is all XML by the way. Another file you may or may not have is thumbnail.png. It's a small graphic that will show up next to the Module name in the browser. Make it square, no more than 100x100 for best results. Just put it in the archive and it will show up. Quick note about the thumbnail, it will show up in the module browser always, however it will only show up in the library itself next to the library name, if the latter (as defined in the individual library's own <name> tag is the same as the module name in definition.xml.

Now the most important file, the one that holds most of the module's data, will have one of three names. It will either be db.xml, client.xml or common.xml, and what name it has is important because it will alter the behaviour of the module. If you name the file client.xml, it will only load for your players if they have the file on their computers. A common.xml file will download the data to the players even if they don't have it, useful for the lazy. Finally db.xml will only show up for you, the players won't even see it. Use this for stuff like monster manuals which they don't need to see. When making your own module, simply make these three files (either from scratch or by modifying an existing module) and put them together in a ZIP archive that you then rename mod and put in the modules folder. If all goes well it will show up in your module browser when you next load the ruleset. If the module is an adventure module you may also see other files like tokens and stuff but those three files are the most common. Speaking of adventure modules, people separate them from library modules but the separation is false. You can put adventure data and library data in the same module. This is useful if say you're building a campaign module which also includes special rules or new feats and such that you want the players to easily reference. Keep that in mind. 3.1 - The structure of the Module All a module's main XML file really needs to have is the declaration and the <root> tag but that would make for a pretty boring module. Inside the root you can define several databases or info categories, which are basically just tags that hold other ones inside them like so:
<root version="2.0"> <library> (stuff here) </library> <reference> (other stuff here) </reference> </root>

In this case the <library> category would hold your libraries (a module can have several) while <reference> would have miscellaneous info that library windows will link to, such as lists of feats or NPCs. Mind you this isn't strictly necessary as you can have said data inside the libraries themselves but it's easier for organizing your module. You can define your own categories and link to them at will, as will be shown a further down, but there are certain categories that are default to FG2 and the program will look for them when doing certain things. They are as follows: <library> FG2 will look here upon the module's loading to check for library entries to display in the appropriate window <reference> you don't need to strictly call it that since you can define what links to what, but it's a common category name, good to have in mind when linking across to existing modules. <image> lists images that show up in the FG's picture browser in-game. If you want to make pictures that are linked from library entries but do NOT show up in the browser, make a custom category tag to hold them that is structured like <image> but is called otherwise. The following categories contain adventure module data and stuff in them will show up in the relevant browsers: <item> items for the item browser, Blood for the Blood God! <encounter> story entries. <npcs> shiny happy people.

3.2 - The libraries section The <library> category, as said before holds what shows up in the library window upon module loading. Let's take a look more closely at it. This category tag is basically very simple. Let's take a look at this sample:
<library> <csrdbasicrules> (some contents here) </csrdbasicrules> </library>

Within the category tag itself you have a subcategory called <csrdbasicrules> I'm sure you can guess what that is. Each subcategory is one line that shows up in the left part of the library window; effectively a self-contained library. Most modules only need one sub-cat, but you can, for what ever reason add several if you wish. Let's take a look at what's inside that. 3.2.1 - Library header Zooming in we see this:
<csrdmonsters static="true"> <name type="string">Complete SRD Monsters</name> <categoryname type="string">Complete SRD</categoryname> <entries> (the library content is here in the entries tag) </entries> </csrdmonsters>

The library's tag can have a static=true attribute. On Host modules (ones with db.xml) having this means that the module is read-only. Otherwise the GM can edit the info from inside FG. Common and client modules are read-only regardless of this attribute. All the tags before <entries> are what's called the category's header: <name> defines what it shows up as in the left side of the library window. The attribute type=string lets FG2 know it's a text string and not, say, a number. Note Library modules will be listed on the left side in REVERSE alphabetical order. Best keep that in mind when naming them. <categoryname> defines the group it's part of in the same window. Libraries with the same category will be nested together. <entries> contains the library content itself and here's where we go next. 3.2.2 - Library Entries The <entries> tag contains the list of items that is displayed in the right-hand side of the library window, the library's table of contents if you will. In the XML a single entry will look like this:
<csrdmonsters static="true"> <name type="string">Complete SRD Monsters</name> <categoryname type="string">Complete SRD</categoryname> <entries> <aacreditslegal> <librarylink type="windowreference"><class>referencetextwide</class><recordname>..</recordname></librarylink> <name type="string">Credits &amp; Legal</name> <text type="formattedtext"> (boring legalese text) </text> </aacreditslegal> (other entries) </entries </csrdmonsters>

This entry is called <aacreditslegal> but it can be called anything you want. The reason why the name starts with aa (with ab, ac, ad, etc following if you'll check out the module for yourself) is that the entries in a library show up in the window in alphabetical order according to entry tag name not what's under <name>. Putting a little prefix in front of the tag name is an easy way to make them be ordered otherwise. The next line is the link that defines where you find the actual content that gets displayed when you pop up the window. For details on that see the links section below. The <name> tag (notice the type=string attribute again) defines what it will be called in the library's table of contents on the right side. Notice also the &amp; entity reference used to avoid conflicts with special characters in the name. The <text> tags kindly warns FG2 that a blob of text follows (formatted by the tags I mentioned earlier). The text itself I cut out for the sake of brevity and to prevent your death by boredom. The tags are then closed in the proper order and another entry can begin. There are many kinds of entries, and I will describe each in detail but first you gotta know about: 3.2.2.1 - Window Classes Window classes are something we'll be working with a lot, so you need to know a bit about them beforehand. A window class is a small set of rules that defines how a window in FG looks and behaves, whether it's a character sheet or story entry or map, etc. (for more information you can check out the Ruleset Modification guide on the FG2 website library). Now what window classes there are is largely dependent on the ruleset itself so you may wanna look into yours a bit more, but most rulesets derived from d20 use a few common ones which you'll need to know about when organizing your library: referencetext the most basic. It's a small window with text in it. Useful for short blurbs of text. referencetextwide as above just wider. Useful if you have big tables. referenceindex (comes in wide and bigwide varieties) is a list of links. npc what it says on the tin. Same window that pops up in the personality browser. item see above. imagewindow opens up a picture. Reference link only. feat a specialized feat window. Mostly relevant to d20-based systems but other rulesets make use of it too. skill see above. Those should be all you need for library modules, but you can snoop around the XMLs in your ruleset's folder for other window classes should you feel you need them. Now that those are out of the way let's talk about: 3.2.2.2 - Links Remember that juicy large link line in the previous chapter? This one specifically:
<librarylink type="windowreference"><class>referencetextwide</class><recordname>..</recordname></librarylink>

Let's dissect that: When you have a link somewhere in a module entry, FG2 needs to know two things what kind of window it opens, and what information it will be filled with. The syntax for telling that to FG2 depends on the type of link. Links can be defined by three tags: <librarylink>, <listlink>, and simply <link>. The first two are used mainly in the library, either to link from the library categories on the left hand side of

the library window - <librarylink> - to a page on the right, or from said page to other windows <listlink>. Examine pre-made modules to see how that works in more detail. Now these two are formatted as in the example above; more specifically: The attribute called type= tells FG what sort of link it is, normally it will be windowreference since we open other windows in links. Inside the link tag there are two other tags: <class> which defines the window class, in this case a simple text window, and <recordname> which tells FG where to look for the window's data. The .. in the present example means that the entry itself contains the data. However the data is sometimes stored outside the entry. In such cases the <recordname> tag will look like this:
<recordname>reference.animalmonsters.wolverine@Complete SRD Monsters</recordname>

That means that the information is in category tag <reference>, subcategory <animalmonsters>, data tag <wolverine>, all of which can be found in the module called Complete SRD Monsters. All this means that you can store the data externally either in another part of the module or in a different module altogether. Pretty handy for organizing stuff, no? Finally, the <link> tag is a handy one-tag way of linking to other entries, and is usually found within reference pages themselves. It looks something like this:
<link class="imagewindow" recordname="image.image-charsheet_portraits_jpg@FGII User Manual Ref">Character Sheet Portrait Icons</link>

As you can see, the same information is there, just defined by the <link> tag's own attributes instead of sub-tags. Also the name of the link is the tag's value, and not a separate <name> tag. This way of linking is generally used from single pages to single pages, where no referenceindex windows are involved, or when you want to avoid code clutter. Let's now take a look at some specific window classes and see what they do and how. 3.2.2.3 - The referencetext class This class is your basic bread and butter when making a library module. A link with this class will spawn a small, narrow, non-resizable window with room to input basic, formattable text and tables, as well as links to other windows. You can also use the referencetextwide class to get a wider version of that, handy for large tables. If you need to, and are willing and able to modify the ruleset, edit reference_basicclasses.xml in the ruleset folder and add an even bigger window class to suit your needs. This class has a simple header consisting of
<name type="string">Window Name Here</name>

and contents wrapped in a <text type=formattedtext> tag. Remember that every line of text needs to be in a <p> tag. You can also edit the text in a visual HTML editor and then paste it into the XML. In fact this is almost mandatory for tables unless you wanna spend ages coding them by hand. Just make sure to clean up the tags afterward so your text isn't messed up by non-approved tags.

3.2.2.4 - The referenceindex class This class is your basic list o' links. After the same type of <name> header as referencetext, it will have an <index> tag that can hold other window links of any kind, even other referenceindexes. A typical example is shown here

<shroomrecipes> <librarylink type="windowreference"><class>referenceindex</class><recordname>..</recordname></librarylink> <name type="string">list of magic mushroom recipes</name> <index> <recipe1> <listlink type="windowreference"><class>referencetextwide</class><recordname>..</recordname></listlink> <name type="string">The Shroom of Doom</name> <text type="formattedtext"> (contents here) </text> </recipe1> (other recipes) </index> </shroomrecipes>

You can also add a <description type=formattedtext> before the <index> to write a small intro for your list. There are also the classes referenceindexwide and referenceindexbigwide for the window space hogs among you. 3.2.2.5 - The npc and item classes. These are a bit special since they are very closely tied to the ruleset in question so the tags needed will be different for every one. <name> header tag is still standard though. Here's a down and dirty cheap trick to make these very fast. Start up FG2. Enter your characters/monsters/items into the relevant browsers. Export them as an adventure module. Then open up that module's XML and copy/paste as needed. Saves a lot of time when creating monster manuals. By the way you can use the same method with text entries if you don't need to draw tables. That said, although you can enter the data you get from FG2 (or create manually if you know the tags and are a masochist) in the library's entry directly, it's a good practice to keep things like NPCs, items, feats and skills in a separate reference category for easy access and link to them like so:
<baboon> <listlink type="windowreference"><class>npc</class><recordname>reference.animalmonsters.baboon@Complete SRD Monsters</recordname></listlink> <name type="string">Baboon</name> </baboon>

See reference category section below for more info about linking 3.2.2.6 - The feat class Everything said above about the item and npc classes applies to the feat class as well, with a few notable differences. One is that while it does tend to be used mainly for d20-based rulesets, the feat class as well as its sister the skill class are also often used in other rulesets as well, although perhaps by other names. The talents in Dark Heresy come to mind here for instance. The window itself is a small, specialized text window. Its tags are few and generic so I will list them here. <name type=string> - self explanatory <type type=string> - Will show up below the title in brackets like so [GENERAL] <benefit type=formattedtext> description of feat will appear under a benefit subtitle. <special type=formattedtext> same. <prerequisites type="string"> one-line prereqs description Not all tags need be entered and only the ones that do will show up, so no empty headings. Here's an example entry:

<armorproficiencyheavy> <name type="string">Armor Proficiency (Heavy)</name> <type type="string">GENERAL</type> <benefit type="formattedtext"> <p>See Armor Proficiency (light).</p> </benefit> <prerequisites type="string"> Armor Proficiency (light), Armor Proficiency (medium). </prerequisites> <normal type="formattedtext"> <p>See Armor Proficiency (light).</p> </normal> <special type="formattedtext"> <p>Fighters, paladins, and clerics automatically have Armor Proficiency (heavy) as a bonus feat. They need not select it.</p> </special> </armorproficiencyheavy>

3.2.2.7 - The skill class This is the same as the feat class only it just gets two tags: <ability type=string> - functions like <type> in the feat class. <text type=formattedtext> - a description of the skill.

3.3 The reference section Although this section tag is usually encountered in official modules for FG2 as <reference>, you don't need to call it that way necessarily. Any legal name will do. This chapter is about general reference sections specifically As mentioned before, when you make a link type tag in any window, there's a sub-tag called <recordname>. If you enter its value as .. then the linked window will get its data directly from within the parent tag of the <listlink> or <librarylink>. If you want to send it elsewhere for the data, use the syntax tag.subtag.entrytag@module name - no quotes. This gives you great flexibility with the content and organization of your module, and even allows you to link across modules as long as both of them are open in FG2. These database or reference tags are very simple, they have no header. It's basically
<reference> <subcategory> <item> (content of item) </item> </subcategory> </reference>

all of which you can set up as you see fit. 3.4 The image section

<image> is a database-type category tag but with a few special details. For one anything appearing under this tag will show up in FG2's image browser. If you want to avoid this just place your images (with the syntax shown below) in a differently named database category. The image entries themselves are formatted thus:

<image-d20reference_jpg> <image type="image"> <bitmap>d20reference.jpg</bitmap> <shortcuts> </shortcuts> </image> <image-d20reference_jpg>

The entry name, in the examples I've seen it's an underscored version of the file name but I'm willing to venture that's not necessary(any input on that by the way?). Then we have <image type=image> - the type of entry <bitmap> which is the file path. Just the file name if the image is in the module archive. Otherwise it is a relative path where the Fantasy Grounds II application data folder is the root (<bitmap>pictures/ideas/lighbtbulb.png</bitmap> for instance) <shortcuts> Place to store the map pins on the image. See more below. The <shortcuts> tag is an index of map pins that the GM can define. They function like spatially located links. See Xorne's videos for more on making those in game. The code looks like this:
<shortcuts> <shortcut> <x>59</x> <y>33</y> <class>encounter</class> <recordname>encounter.id-00002</recordname> </shortcut> (another map pin) </shortcuts>

The <shortcut> tag is an individual map pin. <x> and <y> are its coordinates on the image. <class> is its window class and <recordname> is what it points to. Simple no? Images from here can be brought up in the library or anywhere else by making a link with the class imagewindow and pointing the <recordname> at the image entry in this section. 3.5 - Adventure module sections These sections, named <item>, <npc>, and <encounter> are automatically generated by the exporter when making adventure modules and any entries within are brought up are treated as items, personalities and story entries and show up in their respective browsers. Other than that there is no difference between them and any other database categories. Use in your self made modules if and where you believe it necessary. Otherwise avoid these names lest you clutter the browsers. In adventure modules created with the FG2 exporter, these categories will have a header tag that looks like this:
<category name="" mergeid="Illum" baseicon="2" decalicon="6">

This refers to the separate tab that appears for the module in the relevant browser. Name is obvious, mergeid is there to tell FG2 to display modules with the same value for this attribute in the same tab, and baseicon and decalicon define the visual style of the little bookmark thing that identifies the modules when you switch tabs in the browser. See Xorne's videos for more about that. 4 Final thoughts Well here we are at the end of this Module Making Manual, as far as I know the first of its kind. It is a living document, so any new information I come upon will be added as required, along with any corrections. I hope this helps you get on your way to creating your very own Fantasy Grounds 2 library modules and helps you out with your gaming.

Many thanks to DrZeuss on the forums who gave me a few invaluable starting tips, as well as griogre, moon_wizard and others who kindly and sagely answered the questions of others and some of mine about the module structure. Have fun creating and playing your games! Errata Making library modules without XMLs I've recently noticed you can make library modules using FG2's built in exporter and not touch an XML file once. What you do is create your library data as story entries, personalities and items, format and link them up with the in-game editor, then hit the /export command. In the window that pops up, check the relevant data, and also check the I for each, which will make them indexable as a library. Define a thumbnail file in the field above, and also select an index group which is basically the same as the <categoryname> tag and you should be good to go. The obvious disadvantages to this are that you cannot specify window classes on your own, which consequentially means that you cannot make feat or skill windows or whatever else you can't do from within the game itself, and you can not make tables either for that matter. Moreover, your library entries will still show up as story entries which is not that big of a deal but it's still annoying. Unless you're in a real hurry or completely unwilling to learn the manual way of making modules, the only real use this method has is to make a basic skeleton for your module which you then go in an edit and refine further. Who knows perhaps in the future the software will come with a library editor's mode which allows you to customize the kind of data you build more (are you reading this developers?).

Module Making Manual by SoulOfTheReaver is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.