module making manual

10
Module Making Manual v 1.0 -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 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. 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:

Upload: soulofthereaver

Post on 10-Apr-2015

396 views

Category:

Documents


5 download

DESCRIPTION

A little primer on how to make library modules in the Fantasy Grounds II virtual tabletop software

TRANSCRIPT

Page 1: Module Making Manual

Module Making Manual v 1.0-by SoulOfTheReaver

1 Intro1.1 Stuff you'll need1.2 XML Primer

2 FG2 general style Tags3 The module

3.1 The structure of the Module3.2 The libraries section

3.2.1 Library header3.2.2 Library Entries

3.2.2.1 Window Classes3.2.2.2 Links3.2.2.3 The referencetext class3.2.2.4 The referenceindex class3.2.2.5 The npc and item classes3.2.2.6 The feat class3.2.2.7 The skill class

3.3 The reference section3.4 The image section3.5 Adventure module sections

4 Final thoughts

1 - IntroSo 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. 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:

Page 2: Module Making Manual

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

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

Page 3: Module Making Manual

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> is the link tag from within text windows. Very important tag. 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. 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 don'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><name>Complete SRD Monsters</name><author>Digital Adventures, LLC.</author><ruleset>DarkHeresy</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.

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

Page 4: Module Making Manual

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

Page 5: Module Making Manual

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 usually has a static=”true” attribute, and I don't know what it does. If anyone can enlighten me, I'll add the info to the next version of this documentation. 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.

• <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 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:

Page 6: Module Making Manual

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, that is either a <listlink> or <librarylink> tag, FG2 needs to know two things – what kind of window it opens, and what information it will be filled with. It does so by means of its attribute.

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?

Let's now take a look at some specific window classes and see what they do and how.

Page 7: Module Making Manual

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>

is shown hereand 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 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:

Page 8: Module Making Manual

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

Page 9: Module Making Manual

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. Now unlike general database categories, image-type categories have a header tag that looks like this:

<category name="" mergeid="Illum" baseicon="2" decalicon="6">

At the time of this document's writing I don't know much about it, if anyone could shed some light I'd be thankful. Beyond that, 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> I currently have no idea what this tag does. Anyone?

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.

4 – Final thoughts

Well here we are at the end of the first draft 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.

Page 10: Module Making Manual

Many thanks to DrZeuss on the forums who gave me a few invaluable starting tips, as well as griogre who kindly and sagely answered the questions of others and indirectly some of mine about the module structure. Have fun creating and playing your games!

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