GMHT is a collection of Java classes which make it easy to create programs to help Game Masters for Role Playing Games. Sample programs are included to generate AD&D style magical swords and stalls in a Cairo bazar for a GURPS game.

GM Helper's Toolkit: Start Here

by Joshua Levy

Getting Started

how to install, etc.

Throughout GMHT documentation "..." in file names refers to the location that GMHT has been installed. So, if you see ".../examples/starthere/Sword1.xml" in the documentation, and you have installed GMHT on a PC in D:\games\gmht, then you would use the following path: D:\games\gmht\examples\starthere\Sword1.xml.

Before running any of the examples below, you need to set your classpath variable to include the following new jar files: .../bin/gmht.jar, .../bin/velocity.jar, .../bin/jdom.jar, and .../bin/xerces.jar. Use one of the following commands:

on PCs: set classpath=.../bin/gmht.jar;.../bin/velocity.jar;.../bin/jdom.jar;.../bin/xerces.jar;%classpath%;.
Or edit the .../bin/setup-nt.bat file for your installation, and run that.

on csh UNIX: setenv CLASSPATH .../bin/gmht.jar:.../bin/velocity.jar:.../bin/jdom.jar:.../bin/xerces.jar:$CLASSPATH:.
on sh UNIX: CLASSPATH=.../bin/gmht.jar:.../bin/velocity.jar:.../bin/jdom.jar:.../bin/xerces.jar:$CLASSPATH:.
Remember to replace ... with your installed path!

Step One: No Programming Introduction

There are three basic ideas you need to know in order to use GMHT:

XML is used to control what GMHT does. XML files contains text and tags. Tags start with < and end with > most tags (and all used by GMHT) have a beginning <TAG> and an end </TAG>. All tags used by GMHT are in all-caps.

Obviously there are lots more rules about XML files, which you can read about here, here, and here.

Forms are used to describe what will be printed. GMHT uses Velocity forms from the Apache project. These forms are powerful and complex, but easy to use.

Tables and Dice are what role players have been using for years.

This is an XML file which is used by the Form class. It is run like this:
cd .../examples/starthere
java Form Sword1.xml
it will print out one copy of the filled in form. Take a look at the different parts of the XML file:

Remember that all XML tags used by GMHT must have a matching end tag.

The file starts with a SWORD1 tag, but it could be any tag.

After that it contains one form and two tables. Everything between the <FORM> and the </FORM> is the text of the form. Within the form, $roll3d6 is replaced by a random roll of three, six sided dice. (Note that you can not use plusses or minuses, so $roll1d6+2 will not work.) Also, $useAbility will be replaced by a random roll on the Ability table, defined below.

Each TABLE contains a NAME, and the dice ROLL, and a bunch of table ROWs. Each ROW contains a RANGE (either a number or a range of number-number) and a RESULT (any text string).

This example is from the .../examples/starthere/Sword1.xml file
<SWORD1>
  <FORM>
  $usePlus sword with the ability to $useAbility
  IQ: $roll3d6 WIS: $roll3d6
  </FORM>
  <TABLE>
    <NAME>Ability</NAME>
    <ROLL>1d4</ROLL>
    <ROW><RANGE>1</RANGE><RESULT>cast a fireball</RESULT></ROW>
    <ROW><RANGE>2</RANGE><RESULT>detect magic</RESULT></ROW>
    <ROW><RANGE>3</RANGE><RESULT>glow in the dark</RESULT></ROW>
    <ROW><RANGE>4</RANGE><RESULT>detect evil</RESULT></ROW>
  </TABLE>
  <TABLE>
    <NAME>Plus</NAME>
    <ROLL>1d9</ROLL>
    <ROW><RANGE>1</RANGE><RESULT>+4</RESULT></ROW>
    <ROW><RANGE>2-3</RANGE><RESULT>+3</RESULT></ROW>
    <ROW><RANGE>4-6</RANGE><RESULT>+2</RESULT></ROW>
    <ROW><RANGE>7-9</RANGE><RESULT>+1</RESULT></ROW>
  </TABLE>
</SWORD1>

This is an XML file which is used by the GenAsk class. It is run like this:
cd .../examples/starthere
java GenAsk Sword2.xml
it will print out a page worth of filled in forms into a file called genaskoutput.htm. Take a look at the different parts of the XML file:

Most of new stuff is in the <CONTROL> section, which controls how GenAsk works. DONE is the number of times to use the FORM, before the program is done. ROWS and COLS determine how the FORMs are printed out. They are printed in a table with the given number of rows and columns. FILENAME is the file where these FORMS will be written.

This example is from the .../examples/starthere/Sword2.xml file
<SWORD2>
  <CONTROL>
    <DONE>30</DONE>
    <ROWS>10</ROWS>
    <COLS>3</COLS>
    <FILENAME>swords.htm</FILENAME>
  </CONTROL>
  <FORM>
  $usePlus sword with the ability to $useAbility
  IQ: $roll3d6 WIS: $roll3d6
  </FORM>
  <TABLE>
    <NAME>Ability</NAME>
    <ROLL>1d4</ROLL>
    <ROW><RANGE>1</RANGE><RESULT>cast a fire ball</RESULT></ROW>
    <ROW><RANGE>2</RANGE><RESULT>detect magic</RESULT></ROW>
    <ROW><RANGE>3</RANGE><RESULT>glow in the dark</RESULT></ROW>
    <ROW><RANGE>4</RANGE><RESULT>detect evil</RESULT></ROW>
  </TABLE>
  <TABLE>
    <NAME>Plus</NAME>
    <ROLL>1d9</ROLL>
    <ROW><RANGE>1</RANGE><RESULT>+4</RESULT></ROW>
    <ROW><RANGE>2-3</RANGE><RESULT>+3</RESULT></ROW>
    <ROW><RANGE>4-6</RANGE><RESULT>+2</RESULT></ROW>
    <ROW><RANGE>7-9</RANGE><RESULT>+1</RESULT></ROW>
  </TABLE>
</SWORD2>

What to do next?

If you are a non-programmer, read about templates, since more complex templates will let you do more complex things.

Or, if you want to generate lots of something (100s of NPCs, dozens of taverns, etc.) then read about the GenLots GUI.

After that read about more GUIs for non-programmers, for more complex presentations.

If you are a programmer, then go on to the next section, although in the future, you will want to read about templates, too.

Step Two: Introduction for Programmers

All the features used by non-programs are available to programmers, with even more flexiblity. To use them, you need to use and understand the following classes: Dice, Table, Form, and GenAsk.

Dice

Basically, you can either use a static method to roll dice, or you can create a dice object and then roll that object as many times as you want. For either type of dice roll, you can either use roll to return an int, or sroll to return a String. The following example shows all six basic methods for rolling dice:

    /* This example is in .../examples/tutorial/testDice1.java */
    public class testDice1() {
      public static void main(String args[]) {
        /* you can use a static method: */
        int worth = Dice.roll("10d100") ;
        String worth2 = Dice.sroll("10d100") ;
        /* or create a Dice object: */
        Dice d = new Dice("10d100") ;
        String worth3 = d.sroll() ;
        int worth4 = d.roll() ;
        System.out.println("First roll was "+worth+".") ;
        System.out.println("Second roll was "+worth2+".") ;
        System.out.println("Third roll was "+worth3+".") ;
        System.out.println("Fourth roll was "+worth3+".") ;
      }
    }

NOTES:

Tables

There are two ways to define tables. One is in XML files, as described above. These XML files should start with a <TABLES>, and all the tables in one can be loaded at once with java code like this:

    Table.loadTables("tables.xml") ;

The other way to create tables, is by extending the Table classes, such as below. Both tables use a six side dice, and return a human on a rol of 1-3, an elf on a roll of 4, and so on.
// For programmers who like numbers
public class swordRace1 extends Table {
    swordRace1() {
        super("race","1d6") ;
        add(1, 3, "human") ;
        add(4, "elvish") ;
	add(5, "dwarvish") ;
	add(6, "orcish") ;
    }
}
// For programmers who like strings
public class swordRace2 extends Table {
    swordRace2() {
        super("race","1d6") ;
        add("1-3", "human") ;
        add("4", "elvish") ;
	add("5", "dwarvish") ;
	add("6", "orcish") ;
    }
}

Forms

Using Forms is pretty simple. Forms can be specified in three different ways:

  1. You can put a template in a "*.vm" file, following the instructions in the Velocity documentation.
  2. You can put a template in the <FORM> section of an XML file, as described above.
  3. You can put the template, as a string, directly into the construct.
all of these are shown below. After creating the template, they are all used in the same way:
    Form f1 = new Form("example1.vm") ;
    String result1 = f1.create() ;
    Form f2 = new Form("example2.xml") ;
    String result2 = f2.create() ;
    Form f2 = new Form("raw template: $roll3d6 $useTableExample, etc.") ;
    String result3 = f3.create() ;

What to do next?

If your goal is to write simple programs to create things, then you should know enough to get started. In the future ...

If you want to write....

Step Three: Remembering While Programming

So far we've discussed simple programs, which just randomly create things. But, you may also want to write more complex programs, which look at what they've already done, to customize what they are going to do. As a developer, you've got two choises:

  1. Create custom classes to store and access whatever you are creating.
  2. Use the BetterHash object to represent whatever you are creating.
The trade off is pretty simple: your own class will be specifically and exactly what you want, but you will need to do all the implementation work yourself. The BetterHash class already exists, and does almost everything you could want. BetterHash is not really implemented yet.

What to do next?

Step Four: A Taste of Advanced Topics

What to do next?