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.
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%;.
on csh UNIX: setenv CLASSPATH .../bin/gmht.jar:.../bin/velocity.jar:.../bin/jdom.jar:.../bin/xerces.jar:$CLASSPATH:. |
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). |
<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. |
<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> |
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.
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.
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:
NOTES:
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:
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.
Step Two: Introduction for Programmers
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+".") ;
}
}
Tables
Table.loadTables("tables.xml") ;
// 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") ; } } |
Using Forms is pretty simple. Forms can be specified in three different ways:
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() ;
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....
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: