README file for GMHT (Game Master Helper's Toolkit) 0.5 GMHT is a Java library which is designed to make it easy to build programs to help RPG GMs (Role Playing Game, Game Masters). The offical web page is: http://joshualevy.tripod.com/gmht/index.htm Distributions are handled through the Yahoo group GMHT: http://groups.yahoo.com/groups/gmht This is an early release, and it is not ready for prime time. I'm releasing it now for people who understand that it is still experimental, and who are willing to get grungy software because it is early software. OVERVIEW This library is based on seven classes: Dice a pretty normal dice rolling class. fudgeDice supports FUDGE style dice. gausDice support pure gaussian distributed pseudo-dice. Table a class to create and roll on simple tables. TableTwo is a table that you roll on twice, once for the "up-down" result, and once for the "left-right" result. TableMCols has many result columns, and you pass in an argument which tells it which column to use. Forms converts text using dice and table, so that text like this: "$roll3d6 $useAttribute" becomes this "13 Dexterity", or whatever the random rolls say they should be. The following two classes are deprecated, and should not be used anymore: Page converts text, based on table and dice rolls. For example, text like this "%skill% at %3d6%" gets translated to "swimming at 14" or "fighting at 9" depending on the exact roll of the skill table, and a 3d6 dice roll. It's called page, because you can create a large template. StringTree a class to keep track of data as you create objects. This class can keep track of an NPC's IQ and know that IQ is an attribute, and so on. All of these classes can be configured so that they roll dice randomly and do table lookups randomly. Or, they can be set up to use a dialog box to ask the user what the results of a dice roll should be, or the result of a table roll. That means that these classes can be used to generate random things, or to help a GM design those same things. There are also several classes which help create GUIs for your table based programs: GenOne: Rolls once on a table, and puts the result up in a window for you to see. GenAsk: Creates a new Page, and asks the user if it should be kept, or not. Does this until enough pages that the user likes have been generated, and then puts all the Pages in a file. Gen100s: Creates hundreds of new pages. INSTALLING As a pure Java library, GMHT should run anywhere, but it has only been tested on the following configurations: Machine Java How Much Testing? ------- ------- ----------------- Windows98 Sun's JDK 1.2 Maximum Testing Solaris 2.7 Sun's JDK 1.1 Minor Testing (but only 0.2) WindowsNT Sun's JDK 1.3 Minor Testing You should get the gmht-0.5.jar file. Unpack the release with a command like this: "jar -xvf gmht-0.5.jar". You will get a directory called gmht-0.5, and under it five directories: bin, src, examples, docs and apps. If this is your first release using GMHT, you will also need to get the gmhtliba.jar file, and unpack it, in the bin directory, with a command like "jar -xvf gmhtliba.jar". Finally, there is an optional jar file with a name like gmht-0.5ts.jar, which contains GMHT's unit test suite. You can unpack it (in the same directory that you unpacked the gmht-0.5 jar file), with the command "jar -xvf gmht-0.5ts.jar". You will get one new directory: utest. Then you need to add several jar files to your classpath search variable. On a PC, edit the setup-nt.bat file so that it points at your installation, and then run it. On UNIX, you will need to write a setup.sh or setup.csh file which does the same things as the setup-nt.bat file, which is not hard. The starthere web page has details of the commands. DOCUMENTATION (.../docs) Frankly, the current documentation sucks. I will improve it for the future releases. For right now, you should read the starthere.htm file, and then look at the javadoc generated pages in the api subdirectory, starting with index.html (note the *.htm tutorial vs. *.html javadoc stuff). The .../docs/index.htm pages has links to the rest of the documentation, but it is all half written. EXAMPLES (.../examples) There are three big examples, each in it's own directory: starthere, horses, and stalls. Plus some smaller ones in examples itself. The starthere directory is a collection of small java programs which use different gmht features. These programs don't do much, but they do show you how to do things with gmht. I strongly suggest that you read .../docs/starthere.htm at the same time that you look at this directory, since the two are designed to work together. However, if you just want to build and run the examples, follow the instructions in .../examples/tutorial/tutorial.txt To run the smaller examples, you need to set your classpath ... Stall contains three programs which generate the stalls found in the Cairo bazar of the 1920s. (The original idea is from Chaosism's Cairo source book for Call of Cthulhu.) This example uses the "StringTree" class and the GUI classes, in addition to Table and Dice. To run it: First, set your classpath. If this is not already done, you can run setup.bat on a PC or setup.sh on a UNIX machine. Second, build the application by running build.bat on PCs or build.sh on UNIX machines. Third, run the application with a command like these: java stallRnd java stallAsk java stall2one java stall2six Full details are in .../examples/stalls/stalls.txt. Horses contains two programs which print out HTML pages full of horses. (In very little detail, right now.) This example uses the "Page" class, in addition to Table and Dice. It also shows how to use the GenAsk class to provide a simple GUI. To run it: First, set your classpath. If this is not already done, you can run setup.bat on a PC or setup.sh on a UNIX machine. Second, build the application by running build.bat on PCs or build.sh on UNIX machines. Third, run the application with a command like these: java Horses java HorsesGenAskPgm Full details are in .../examples/horses/horses.txt. APPLICATIONS (.../apps) Most of the applications are in the .../apps directory, which has it's own web page (.../apps/apps.htm) which you can read. However one very simple application is in the .../bin directory. It is called "GenOne" and works kind of like a "yellow sticky". It runs the table once, and then puts up the result where you can see it. That's all. You can use it like this: java GenOne gurpsEye The gurpsEye table select's a person's eye color randomly based on rules from the GURPS Basic rule book. You can replace gurpsEye with any table (although there must already be a *.class file for that table). If you want to see a list of all the tables shipped with GMHT, look at the file .../docs/tablelist.htm. It will tell you where to find them, and a summary of what each one is. SUPPORT All support for this package is handled through http://joshualevy.tripod.com/gmht/support.htm. SOURCE CODE (.../src) Full source code is provided, although since the *.class and *.jar files are included, you should not need them. Here are some of my naming conventions: Files which end in "BS" are part of the Basic SWING GUI for the toolkit Files which start with Tst are part of the most primitive test suite. (a better test suite will someday be in a tst subdirectory). Files which end in Tst are also test files, but this usage is being phased out. Files which end in Dice are specialty Dice subclasses. KNOWN PROBLEMS Always check the GMHT home page: http://joshualevy.tripod.com/gmht/index.htm for a complete list of known bugs and problems. Because of the way I make releases, several extra files end up getting released. Ignore them. I'll get rid of them in a future release. This release (0.5) has several major redesigns and is less stable, less tested, less documented, and generally less finished than previous releases. Things should stablize around 0.6 or 0.7 in preperation for the "real" release of 1.0.