Using GUB

	Sign In Sign-Up

Using GUB

How to get, install, run, and use the GUB.

IMPORTANT:
GUB is a Java 2 application. You must have either the JRE or JDK 1.2.2 (or higher) installed to run it (or any other Java application written to use the features available in Java 2). You can download these from http://java.sun.com/products. All instructions below assume that you are familiar with Java's CLASSPATH environment variable and that all Java binaries are in your PATH.

GUB depends on fixes in the JVM version 1.2.2 or higher, and may not work correctly with versions 1.2 or 1.2.1. If your JVM is older than mid-July, '99, then you need to upgrade before running GUB.

Getting GUB:

To download GUB, visit the GUB version's page. The newest one will always be near the top somewhere. Just click on the big hyperlinked version number.

Installation:

There are several ways to do this, depending on how you want to install GUB and how knowledgable you are in configuring Java on your system. The method below is my "officially supported" method, and is what I believe to be the easiest for most people (compared to other methods of installing Java applications).

Make a directory where you want GUB to stay.
Unzip GUB's distribution ZIP file to that directory. This directory will be called "GUB's home" in this documentation.
If you have the Java Shared Data Toolkit version 1.5 or higher installed, or if you know you will never play GUB networked, then you are done. If not, then you'll need to continue with the following steps.
Grab this JAR file (210k). Put it in the same directory as that unzipped GUB to. That's all you have to do with it for GUB to find and use it.

GUB can run without the JSDT files unless you try to run the network client or server, and which point it will silently fail to do any network activity.
Note that the JAR with JSDT files is NOT the complete JSDT package. It's just the stuff you need to run GUB. If you ever install the JSDT after installing my file, please delete my version of the files to be sure there are no conflicts.

Before You Continue:

This section will give you some information that you need to know when setting up GUB. Please read this before using GUB, and certainly before asking me questions about the game.

Paths: (this part is very important)

One of GUB's primary design goals is the ability to painlessly transport game files from one system to another, without having to transport the images themselves (this assumes that each player has the game piece set). Painlessness has it's price, though, and in GUB this is the rigidity of the structure of the directories that GUB uses. This is described below:

GUB must have a data directory directly under it's "home" directory. So, if you have GUB installed in C:\GAMES\GUB, then you must have the directory C:\GAMES\GUB\DATA. This is the tree where GUB will store all game sets and saved games.
The exact structure under the data directory is not so important. All paths referenced in your game piece sets and savegame files must refer to relative paths, starting from the directory where the game file lives. Let's assume the following directory structure:

C:\GAMES\GUB
         +-\DATA
            +-\generic
               +-\maps
            +-\GEV
               +-gfx

And assume that I have a gev.pieces file in my GEV directory. (GEV, by the way, is a game by Steve Jackson Games.) I keep all my piece graphics under the gfx directory, but I keep my maps in generic\maps (because I can use them with almost any game). The relative path to my maps folder from my GEV folder is ..\generic\maps. This means that if I have a BOARD_FILE=... line in my pieces file (this tells the piece set which game board to load), then it needs to look like this:

BOARD_FILE=..\generic\maps\forest.trails.jpg

The same rule applies to game piece graphics.

Since pieces and the game boards are loaded from relave paths, you must save your games to the same directory as you originally loaded your pieces from. I'm sorry about this (really), but until I find a better way to do it and still have portability, this is the way it needs to be.

Running GUB:

Because GUB is a Java application, and I have no professional development tools, GUB has no installer which can make a shortcut on your desktop or anything like that. Because of that, you'll have to open up a command prompt to start GUB. Or you can manually make a shortcut, as described below.

The INI File:

GUB has an INI file which can control some features of GUB. You will find it in GUB's home directory.
If you like, edit gub.ini to your liking. Open it up with any text editor to see instructions for each section. You may either leave gub.ini where it is or copy to your home directory (if you use Unix), C:\WINDOWS for Win9x, C:\WINNT for WinNT[, and God knows where for OS/2 and Mac]. GUB does not require this file.

That's it! Now you must install one or more game sets for GUB to be useful. GUB comes with a checkers set configured to start up the first time you start GUB (if you run GUB from the directory where it lives). Instructions for installing additional game piece sets are listed below.

Starting it Up:

Browse to GUB's home directory.
If you are running Windows and have the JRE (or JDK) 1.2.2 or higher installed, you can now simply double-click on gub.jar to run GUB. You may make a shortcut by doing the following (assuming you're using Win95 or higher):
- Right-click on gub.jar.
- Right-click on your Desktop. Click the Paste Shortcut menu option.
- Right-click on the icon you just made. Click the Properties menu option.
- Make sure that GUB's home directory is listed in the "Start In" field.
Ff you would rather run it from the command line, or would like to start it from a batch file, type the following command at a command prompt (make sure you are in GUB's home directory).

jre -jar gub.jar

(this assumes that the path to the JRE's executable is in your PATH. The JRE installs it's executables under C:\PROGRAM FILES\JavaSoft\JRE\[version]\BIN by default.)
or, if you have the whole JDK installed, you can run it like this:

javaw -jar gub.jar

or

java -jar gub.jar

GUB does not yet have any command-line arguments. It will some day.

GUB should start up and be on your screen after a few seconds (be patient on a slower machine... Java applications are not known for their speed). If you are starting GUB for the first time, you should see a checkers set on your screen. In the next section I'll explain how to use that board and it's pieces.

Using GUB:

Here are the basics on how to use the game board and pieces. This assumes that GUB started up correctly and loaded the default game piece set (checkers). If it did not, please send me a description of what happened, along with a list of all files in your GUB directory (from a DOS prompt, type "dir *.* /s > list.txt" from GUB's home directory, then email me the file list.txt). This list is just an overview. Detailed instructions will come out one of these days!

The left side of the screen holds a list of pieces you can add to the board. You may double-click any of them to add it to the game board (this does not remove it from the list).
The small red dot on the game board is where the next piece that you add will go. To move the red dot (affectionately called the Red Dot in GUB lingo), either drag and drop it to where you want, or double-click on the game board and the Dot will go there.
To move pieces, drag and drop them.
To change a piece's options or remove it from the board, right-click on it. You will get a menu with lots of options.
Right-click on the piece at the bottom of the piece selection list to change the basic look and feel of each piece added to the board. This does not affect pieces in play. For example, change the size of the sample piece to 70x70, set the Scale Icon toggle (in the Background submenu), then add a piece to the board. It will be 70x70 pixels and it's graphic will be much larger than normal.
To load a game, click on the "..." button at the top of the pieces list or click the FILE -> LOAD menu. You should look for files with a pieces or gubpieces extension somewhere under the data directory (see above for information on the data directory). Once it's loaded, if your game board does not display correctly, try resizing the board slightly, and that should do it. If not, manually re-load the board only by clicking the "..." button on the game board's toolbar. (This part is still somewhat buggy.)
To save your game, click the FILE -> SAVE menu. You MUST save your game in the same directory where you loaded your original game from (where the pieces file lives). See above for the reasons for this limitation.
Right-click on the game board for some game board options.
To quit, click on the window's close button or the FILE -> Exit menu.

I'm sorry to be so terse here. One day I'll have docs with screenshots and such. It's still changing so much that I hate to go into too much detail about it.

How to install GUB Game Sets:

Once you have downloaded a game set for GUB, you should do the following to make it usable by GUB:

Unzip the archive to the directory where GUB resides.

This should create a data directory, and possibly other subdirectories, containing the graphics and such for the game. Strictly speaking, the files do not HAVE to be kept in one place, but they SHOULD be kept in one place for easy housekeeping. GUB's save/load support relies heavily on this because it aims to allow savegames that can easily be transported between systems (for PBEM). Once you have this completed, start up GUB and click on the appropriate button to load your game piece list (and your game board, if the game piece list doesn't load one for you). You can set GUB to automatically load a default game piece list and game board by editing the sample gub.ini that comes with the GUB distribution. When GUB starts up, it will first look in the current directory for gub.ini, then it will look in your home directory (C:\WINDOWS for Win9x users). In the INI file, if you use relative path names, they will work from the directory you start GUB from.

Each game set may have a license and/or copyright information contained in its archive, which lays out the rules for its usage and distribution. Please pay heed to these.

An early version of GUB had a plugin to import V_MAP games. There have been many, many internal changes to GUB which have broken this tool. But... I will be re-writing it once GUB's development gets more solid, and I stop changing the API all the time. I will also write game import/export tools (or help you to write them) as I have the need for them. I would love to import SMS files, but the format is just so strange.

That should do it!

Email me with installation/running problems.
Have fun!
----- Stephan Beal