Overview

The goal of this document is to help you create templates for use with DM Toolkit. The document will explain how DM Toolkit processes feed data, as well as how a user can format data for inclusion in the toolkit.

Difficulty Level

Template creation is not difficult. Anyone who understands the fundamentals of XML/HTML should have no difficulty creating templates. If you aren't familiar with XML/HTML, W3Schools provides an excellent tutorial here.

Other Info

This document created on May 17th, 2010. by D. Brad Talton Jr.

XML Specification for modules for version 1.2 "Drawmij" of DM Toolkit.

Please contant kiyoshi.kyokai@gmail.com with comments and suggestions regarding this document.

Back to the top

Modules

Each library of downloadable content is called a Module. A single module is contained in one XML file. An XML file cannot contain more than one module.

Updating and Replacing Modules

DM Toolkit knows which resources belong to which modules. Because of this, if you decide to update your module later, your changes will overwrite the old module's resources rather than creating an entirely new module.

Each module has a unique 'name' associated with it. If your module's name is the same as another module's name, then your module will erase all of that module's data when it is loaded.

Module Syntax

The module should be the root node of your XML document. The simplest possible DM Toolkit library looks like this:

<module name='Sample Module' author='D. Brad Talton Jr.' publisher="Level 99 Games" formatVersion="1.2" moduleVersion="1.0" system="No System" > </module>

Here's a breakdown of those options

• name - The name of the module. This name must be unique, because of the way modules update (as explained above).
• author - Your name. Don't use my name. I will not be amused.
• publisher - The original publisher of the content you are posting (if open source content). Otherwise, should be the name of the web site or company hosting your feed.
• formatVersion - This is the minimum required version of DM Toolkit that can load this module. If a lower version attempts to load this module, it will download the entire module, then reject it before unpacking. If the module XML format changes in later versions of DM Toolkit (which is likely) this will be important. Should not be less than 1.2.
• moduleVersion - This is the version of your module. Each time you update, you should increase this number. DM Toolkit checks the version number of an installed module of the same name against this one. If the installed module has an equal or greater version number, the module will be rejected by the app as an old version. Please start version numbering at 1.0, and do not use more than one decimal point in your numbering.
• system - The system that this module should be listed under. Capitalization matters.

The above module is acceptable to DM Toolkit, and will be loaded, but is ultimately useless because it contains no objects. The process of creating objects will be described in the next section.

Back to the top

Objects

Objects in the XML file are what will eventually become Resources once the file is loaded into DM Toolkit.

Objects can be simple or complex. There's no limit to the amount of customization that you can include in your objects.

Object Syntax

Objects have their own parameters, which can be seen here:

<object name="Sample Object" system="No System" id="SampleObject001" type="character" template="YES" description="" note=""> </object>

Let's take a moment to examine each of these options:

• name - This is the name of the object, as it appears in the app. For templates, this should be descriptive of the kind of template you are creating, and should probably include the system as well. ie: "DnD 4E Character", "Runequest 4 Ritual", "BESM Spell", etc.
• system - This determines the system that the object is listed as. Since this is a string that will be searched on, capitalization, spacing, and symbols all matter. For example, a search for "DnD" will not display your result that has system set to "D&D" or "dnd".
• id (optional) - the id is used in cross-referencing. ID's MUST be unique across your template. If you do not provide IDs for your resources, DM Toolkit will randomly generate a unique ID for each resource as it installs your module. The only reason you would want to specify an ID is if you want to cross-reference resources within the module you are creating. ID's should not contain spaces.
• type - This will determine the type of the object, and what it gets listed as from the main screen.
• template (optional) - If this attribute is set to anything at all, the object will be a template. If you want to create an object that is not a template, just leave this attribute out completely. Setting template="NO" will NOT work.
• description - This is the description for the item. It is recommended to leave this blank for templates.
• note - This is the note attached to the item. Use this to hold any miscellaneous information, such as sources cited, original publisher, tips for placement or useage. For templates, it is recommended to leave this blank.

Back to the top

Properties

Properties are the first list that shows up in an object. This list should contain important and often-referenced data that defines the object. Is it a mechanical or magical trap? Is it a level 10 or 20 monster? Is it a baker or a locksmith NPC? These kind of things make good properties.

Kinds of Properties

• Simple Properties - These are simple name/value pairs. Appropriate for numbers or one-word values.
• Extended Properties - These are longer name/value pairs that display over multiple lines. Great for history, special attack descriptions, effects, and anything that takes a sentence or longer to explain.
• Cross References (soft links) - These are references to other objects within your module. These are good if a resource is used multiple times (like a feat, item, or special attack that a number of npcs would use). It is not recommended to use Cross References in templates.

Property Syntax

Each property is contained in a single line. Notice how the tags close with a "/>"--the proper closing for tags with no content. The three kinds of property are shown below.

<property name="Age" type="" value="23" /> <property name="Super Evil Death Whirl" type="extended" value="The caster concentrates all the powers of darkness together and then spins in a circle, unleashing dark energy as black blades of necrotizing energy. Useable only be evil casters, obviously." /> <property name="Sword of Might" type="softlink" value="Sword049" />

You can also use

<property></property> as with normal XML tags, but any content between the tags will be ignored, so there's not much point.

A short explanation of these parameters:

• name - The name of the property. Should be no more than two words for simple properties, and no more than 5-6 words for extended properties. For cross references, this attribute should be set to the name of the cross-referenced object.
• value - The value that will be associated with the property. Can be any length. For cross references, this attribute should be set to the id of the cross-referenced object within your module. (There is no way to cross-reference other modules at this time).
• type - The value of this determines what kind of property is created. If it is "extended", the property is an Extended Property. If it is "softlink", the property is a cross-reference. In all other cases, the property defaults to be a simple property.

Property Lists

Property lists constitute the sub-sections of your resource.

An object can contain any number of property lists. Each property list can contain any number of properties.

The syntax for a propertylist is as follows:

<propertyList name="Sample Property List"> </propertyList>

Between the <propertyList> tags, you can include any number of properties.

Back to the top

Complete Sample

Here are all the examples you've seen, cobbled together into one. You can use this skeleton as a starting point for your own modules.

<module name='Sample Module' author='My Name' publisher="Me" version="1.2" system="No System" > <object name="Sample Object" system="No System" id="SampleObject001" type="character" template="YES" description="" note=""> <property name="Sample Simple Property" type="" value="42" /> <property name="Sample Extended Property" type="extended" value="An Extended Property can span multiple lines, but remember that tabs and new lines are NOT ignored, so be sure that the way the text looks is exactly how you want it to look in the final resource." /> <property name="Sample Cross Reference" type="softlink" value="otherObjectID" /> <propertyList name="Sample Property List"> <property name="Sample Simple Property" type="" value="A" /> <property name="Sample Simple Property" type="" value="B" /> <property name="Sample Simple Property" type="" value="C" /> </propertyList> </object> </module>

Back to the top

Other Notes

Here are a few other things to consider when creating your modules.

Size

The size of a module should optimally not exceed 500kB. If your module will be larger than this, consider breaking it down into smaller sections. This is not a hard-and-fast rule. However, modules larger than 500kB may be difficult to download for users on a 3G or Edge connection.

Copyright

Published RPG content is the property of its creators and is protected by copyright law. YOU are responsible for any modules you create. DO NOT infringe on the intellectual property of others. If in doubt, contact the copyright holders. Some games, like World of Darkness, impose limits on the publication of even user-created content. Please check your copyrights before posting anything, because I really don't want to deal with that hassle, and neither do you. Most of this information can be found on the home page of the individual RPG publisher.

System Freedom

It's good when your resources can be used out of the box, but it's even better when they can be used by anyone. If you are creating a large list of traps, spells, rituals, items, or the like, consider formatting your resources for use with any system (system="No System"), and letting GMs adapt your content to their specific needs.

Back to the top