The GUB: Generic Universal Boardgame

	Sign In Sign-Up

Making Game Sets for The GUB

by Stephan Beal

NOTE: These instructions are for version 0.7.x and earlier. They WILL NOT WORK with version 0.8. I will be posting instructions for 0.8's game piece list files some day.

One of GUB's strengths is the ability to quickly create sets of game pieces using a simple text file and optional graphics. This page describes how to make your own game piece sets (called Game Piece Files, or GPFs, from now on).
Before we start, here are some things you should be aware of:

All GUB game piece set filenames should end with the extension GUBLIST (case is unimportant).
All GUB-related files should be stored under the DATA directory, under the directory where GUB is installed to. This is not a hard-coded requirement, but is requested for standardization.
All paths to images must be relative paths, starting from where the GPF is stored. Absolute paths will not work. It is suggested that your GPF be in DATA directory, directly below GUB's home, and your graphics be included in subdirectories under that. This allows you to easily use graphics from other game sets without having to copy them to your subdirectories.

Template:

Instead of writing a whole GPF from scratch, feel free to download this template and edit it.

The Text File:

GUB's source of information about a set is a text file with the following information:

The name of the list. This name will appear at the top of the player's game piece selection list.
Labling, bordering, and image scaling options for the game pieces (optional).
Freeform text, which will be added to the "Game Info" tab when a player loads the list. Can be used for game rules, copyright information, etc.
List of game pieces available.
Any number of comment lines. These lines start with ; and are ignored by GUB.

Now we'll go into detail about each of these sections. Note that any key names in the GPF must be in ALL CAPS.

The Header:

All GPFs should have the following line at the top of the file:

VERSION=0.3

This is NOT the version of your list, but the version of the data file format. If GUB tries to load a different version than the one it was built to use, it will complain.

Title:

When a game piece list is loaded, it's nice to see the name of the list appear at the top of the selection list that the player will see. To set this, add the following line to your GPF:

TITLE=My Piece list

Game Piece and Board Options:

Game pieces and the game board have multiple options that can be set via the GPF or at runtime. They are shown here as they might appear in your GPF:

; The height and width of the game board. This ONLY has an effect
; if BOARD_SCALING equals 2, 1, or 0. See below for scaling.
BOARD_HEIGHT=500
BOARD_WIDTH=500
; A simpler way to set the height/width of the game board, but works
; the same.
BOARD_SIZE=600,600

; Sets the scaling of the game board. This should normally be left at
; normal (3). If you use a small graphic and want it tiled many times, use
; 0, then set the board size (above).
; Scaling: normal=3, scaled to fit the size specified by BOARD_WIDTH x BOARD_HEIGHT=2,
;    centered=1, tiled=0. These work exactly like the wallpaper options in Windows or KDE.
BOARD_SCALING=3

; If you know the graphic you want to use, type it's name here. Use
; a name that has a path relative to the path of this file. For example,
; if you have chess.gif in the chess directory just under the dir where
; this file lives, use chess/chess.gif. 
; If you set this, and scaling is set to 3, the any game board size set
; above will be ignored.
; You should not use a GIF with transparency as your game board. It will 
; look really bad.
BOARD_FILE=board/myboard.jpg

; The following 3 values are boolean. Use a number greater than 0 for "true"
; and less than 1 for "false".
; Should the pieces show their label by default? Useful if you do not have graphics
; for all of your pieces.
PIECE_SHOW_LABEL=1
; Should the pieces show their border? Useful if your graphics don't already have 
; a border around them
PIECE_SHOW_BORDER=1
; Should the pieces scale their image to fite their size? If not, it will use the
; image's default size, even if it's bigger than the game piece.
PIECE_SCALE_IMAGE=0

; The default height and width of the game pieces. 
PIECE_HEIGHT=40
PIECE_WIDTH=40

All of these fields are optional. GUB will try to use sensible defaults for game piece options, and load no game board by default. All of these options can be selected at runtime, before adding pieces, or for individual pieces, via their right-click popup menu.

Text:

A GPF may have any amount of free-form text in it. This text will show up in the "Game Info" tab in GUB's main interface. This is useful for copyright info, game or scenario rules, contact information, etc. You should not include any copyrighted information in here unless you have permission from the copyright holder(s).
To add text to your GPF, start each line of text with a single ".". For example:

; Any lines starting with a "." will be put in the "Game Info" tab.
.Here is my text...
.Here my text continues.
.This is my last line of text.

Plugins:

If you'd like to automatically launch a GUB plugin from your GPF, you must know the whole ("fully qualified") Java class name of the plugin (without the .class extension), plus you must give it a name (which will show up on the tab that it is added to). You can add any number of plugins, but it should be kept to a minumum to avoid crowding the player's UI. Plugins are added with the following format:

; Name any plugins you want auto-loaded here (don't get carried away).
; Use the format of NAME|CLASSAME, where NAME equals whatever you want to
; show up in the plugin's tab, and CLASSNAME equals the full class name
; of the Java class file that is the plugin.
PLUGIN=Dice|gub.plugins.DieRoller
PLUGIN=Ogre Record|gub.plugins.OgreRecord

This example would put plug in two plugins, titled "Dice" and "Ogre Record", respectively.

Game Piece Listing Format:

GUB has several formats for saving game pieces, and needs to know which format will be used in your GPF. This line is the most important line in your file, and GUB may not live to tell about it if you leave it out. Until I write more documentation on how to use this line, always use the following:

; FORMAT tells GUB what format the game pieces are saved in. Don't touch this
; unless you know what you are doing.
FORMAT=LSIN

Case is VERY important here.

Piece Listing:

This should be the final section in your GPF, and is the part that will have the most visibility to the player, so be careful when editing it. Game pieces, when using the format specified by the FORMAT line listed above, are saved with the following information:

Long name. This complete name of the piece. This will show up in the game piece selection list.
Short name. This will be printed on the game piece the option PIECE_SHOW_LABEL is set to true.
Image filename. This must be a relative path, relative to the place where your GPF is stored. For some reason, using "../" in the path does not work, so only reference images in paths equal to or below the directory where you have saved the GPF. If you don't want a graphic for your piece, put a "-" instead of a filename. If you do this, GUB will not warn about not being able to load the image.
Note. This can be any one-line text, and will show up in hoverhelp or when the user clicks the "Edit Note" menu option of a game piece. If you don't want a note, put a single period or dash there.

Each of these fields is separated by a | (called a pipe or a vertical bar) character, so don't use this character in your unit's information.

Here are examples:

Pushpin: Red|Pushpin: Red|generic/pushpin.red.gif|Generic marker.
Pushpin: White|Pushpin: White|generic/pushpin.white.gif|Generic marker.
Pushpin: Green|Pushpin: Green|generic/pushpin.green.gif|Generic marker.
Pushpin: Blue|Pushpin: Blue|generic/pushpin.blue.gif|Generic marker.
Dummy Piece|Dummy|-|Used for marking "covered" pieces.

That's it!

Now you should have everthing you need. Save your file to the DATA directory, under GUB's directory, and be sure to put a "GUBLIST" extension on it (case doesn't matter). Then, from within GUB, from the game piece selection tab, load your list and see how it looks. You do not need to restart GUB when editing the list. Simply reload the list after editing it. Changes you make will not be applied to pieces already on the board. You must re-add the pieces to see the changes.

In the Future:

A future version of GUB will include a built-in GPF editor plugin.