GnomerMind Manual
<<< Previous |  | Next >>>

# Building themes

## Basics

Building themes is a trivial matter. You may be discouraged by the several files you see in a theme directory, but it's just a question of fantasy and skill in drawing. An ideal application to use is `GIMP`, and creating a theme doesn't takes more then an hour, from the idea to the installation... :)

The game field is composed by several elements: a background (the game board itself), the tokens, the hint pins and the control icons. You must provide one or more pixmaps for each element, plus the masks that allow the program to cut out the elements in the desired shape. Infact, the tokens, the pins and the control icons aren't all square, nor have the same dimensions: this way, the graphics are much more flexible, and you can decide the position of the single pins, for example, or the token clickable area shape... for istance, in the Classic theme the tokens are round, and you can activate them by clicking on the very shape; this is allowed by the masks... notice also that the hint pins are differently positioned in the different themes; this is because you can put them just wherever you want! :))

Moreover, you must provide an `ABOUT` file with the infos on your theme.

## The background

The background is actually composed by nine files; the main tile and the margins.

The main tile is the background for just everything in the game; it must be square, and of the same size of all the other elements that will lie upon it.

The margins are the elements surrounding the board, that will be the margin of it; e.g. in the Classic theme, the tile is the wood pattern, while the margins are the beveled borders. There are 8 of them, for upper margin, lower margin, left and right ones, and for the four corners. They are the only elements that can differ in dimension from the tile: infact, they have a 'margin width' and must adapt to it. So the upper margin will be as wide as the tile, while its height must be the margin width; the left margin will have the same height of the tile, and the width equal to the margin width; the corners will be square, with side dimension equal to the margin width, and so on.

| Please ensure that the tile and the margins connect seamlessly, and the margin with each other: the top margin can be flanked by another one, so it must graphically connect to it, and so on. An example is better than thousand words: please look at the files that are in the theme directories.

### Files

The files must be PNG, any depth, the following are their names, and the dimensions they must have (we will call BASE the tile side length, and EXT the margin width):

- `tile.png` — the main tile (BASExBASE);

- `ul.png` — upper-left corner (EXTxEXT);

- `u.png` — upper margin (BASExEXT);

- `ur.png` — upper-right corner (EXTxEXT);

- `r.png` — right margin (EXTxBASE);

- `br.png` — bottom-right corner (EXTxEXT);

- `b.png` — lower margin (BASExEXT);

- `bl.png` — bottom-left corner (EXTxEXT);

- `l.png` — left margin (EXTxBASE).

## Tokens

You must provide ten different pixmaps for the tokens, plus the pixmap for the token hole. They must be painted on a square with the same dimensions as the background tile. So, from now on, all the pixmaps must be BASExBASE; I won't specify it anymore. Moreover, you must provide a common mask for them all; this mask will specify the visible (and clickable) part of every pixmap. So, you won't need to draw all the square; you can draw your token, and paint the invisible parts in an uniform colour.

Again, please look at the themes for examples. You'd better make tokens that can be easily distinguished, contrasting very well with the background tile and with each other. It's quite difficult with colours, to make ten of them, but with shapes or patterns it's just trivial.

All the masks are stored in the alpha channel of a BASExBASE PNG pixmap. I use a 2-colours pixmap, painted all black (or white), with the alpha channel transparent where I want to hide the token tile.

| If you don't need a pixmap, and just want the token image to overdraw the tile, you must still provide a pixmap, but you can make it without the alpha channel - just make a 1-bpp black PNG, for instance.

### Files

Again, the files must be PNG, any depth:

- `tokh.png` — the pixmap for the token hole;

- `tok0.png — tok9.png` — the pixmaps for the 10 tokens;

- `mtok.png` — the token mask.

## The hint pins

You must provide three sets of six pins each. These are, one set for the 'correctly guessed' pins, one set for the 'misplaced' ones, and one set for the holes. These sets will be painted each on a tile; so for each tile there will be 6 pins. In addition, you must provide six masks to cut out the single pins.

No need to say that this sounds complicate... but it's easy. Just draw the three sets the same way, so that the same pin is in the same place; in other words, the three sets must be sovrapponible. Then make the masks, with the same rules as the one for the tokens (alpha channel, etc.), all trasparents but in correspondance of the pin you want to mask. Look at the themes... :)

### Files

- `pin0.png` — the pixmap for the pin holes set;

- `pin1.png` — the pixmap for the 'misplaced' pins set;

- `pin2.png` — the pixmap for the 'correct' pins set;

- `mpin0.png — mpin5.png` — the masks for each pin.

## The control icons

You must provide four control icons, one for each state: wait — when the program waits for the player to complete a row; ready — when a row is complete, and the player can evaluate it; failure and success — for, well, failure and success! :) Moreover, these will be masked by another mask. Just as ever.

### Files

- `stt0.png` — the icon for the waiting state;

- `stt1.png` — the icon for the ready state;

- `stt2.png` — the icon for failure;

- `stt3.png` — the icon for success;

- `mstt.png` — the mask for these icons.

## The ABOUT file

This is simply an ASCII file containing some fields. They are separated by the string "<——>", and may contain line breaks. The fields are:

1st field: Theme version

  The release version. Please, for uniformity, start from 0.1 and go on.

2nd field: Copyright notice

  The copyright notice for the current theme. There must be only one, so, it's for you. Please include any other notice (like the copyright for the images you eventually copied) in the notes, below. Also, please use the (c) form for copyright, not the "©" character, since some users with particular character sets may not be able to display it.

3rd field: Author

  Your name, and your email written between "< >".

4th field: Theme notes

  Anything else you want to say. History. Comments. Greetings. Fables... anything. Just write in english, and again, don't include 'strange' characters.

| If there's something wrong in the ABOUT file, when you'll select the About theme menu item, the dialog won't appear, and a message will show in the terminal window; of course this will happen only if you'll start the program from there. Obviously, the program can't check if all the fields make sense; it will only check if there is the right number of them. The rest is up to you. After having built a theme, select the About theme dialog and ensure all is OK.

### Files

- `ABOUT` — the file described above.

## Final details

| A good theme should be around 30-40 kb. Please consider that each pixmap is stored in memory, and the larger are the BASE/EXT dimensions, the more memory they occupy... Moreover, if you make too large pixmaps, the game won't probably fit on the player screen, if they use lower resolutions.

When you have finished, to control everything's fine, just run:

gnomermind --theme=<your theme dir full path>

If it displays with the new theme, compliments! You've done it! :)) If not, you have made an error; since you have started the program from commandline, it should have warned you on the type of it.

| Please notice that you could get confused in interpreting the error message: infact, the game will take the dimensions of `l.png` as the base for evaluating the other pixmaps; so if the dimensions of this one are wrong, it will report an error on the other ones, not on that...

| Share your theme!
| If you think your theme is really nice (if not, why did you make it? ;), please send it to us, referring to `<mano78@users.sourceforge.net>`, and it will be included in the site! :)

<<< Previous | Home | Next >>>
Known Bugs and Limitations |  | Authors