Themes

About themes

What is a theme?

Think of themes as "skins" which can be applied to the game. Technically a theme is a datafile or a directory which contains:

• Graphics
• Sounds
• Musics

The scripts are *not* contained in the dafafile, so one can use any theme with any set set of rules, since both are indenpendants.

The theme can be chosen in the "Options/Theme" menu. Just move to the theme you want to use with the keyboard arrows and press ENTER.

Copyright and artwork

It's very difficult to find artwork which can be GPL'ed. Most of the free resources on the web are available for free as long as one does not make money from them. However this kind of restriction is not compatible with the GPL, so I have created almost everything myself, from scratch. This way *all* the artwork in U61 is available under the terms of the GPL. This means that:

• All the graphics are GPL'ed. I have drawn most some of them myself, and the pictures come from my personnal collection. Only some of the graphics in the default theme have been contributed by Ursula Adler, and she agreed that I placed her contributed work under the terms of the GPL.
• All the sounds are GPL'ed. Some of them I found on a CD with domain public sounds, and the others I have recorded myself, with a microphone.
• All the musics are GPL'ed. I insist on this point since copyrights on .mod, .it or .xm files are not always very clear. So these mods are not public domain. They are placed under the terms of the GNU General Public License. The samples are also GPL'ed. I have recorded the drums years ago with a dusty SB16 and a friend, and the brass samples where recorded at home with my own instruments and my good old microphone 8-)

If you want to contribute to U61 by creating new themes, keep in mind that your work must be available under the terms of the GPL. This means that I can not accept themes which use graphics from a proprietary game for instance. So if you want to make a "Diablo 2 theme" you can do it but I won't distribute - and you should not distribute it either since it would be a plain GPL violation, besides being also a copyright infringement of Blizzard's game.

Difference between .dat and .scr themes

As U61 is based on ClanLib, it is able to read the datafiles in 2 different ways:

• .dat files are WAD-like files. This mean all the resources are stored in a single opaque .dat file. I used this format to ship the default theme since this format is less problem-prone than .scr files. Basically, if you have a successfully compiled .dat file, there are few chances that the games fails when it runs, since everything has been checked before. All the resources which are required to build the default.dat file are of course available in the source package.
• .scr files are plain text files which contain links to the resources files. In U61, a "mytheme.scr" file will basically contain pointers to graphics, sounds and music files located in the "mytheme" directory. You just have to modify the .pcx, .wav or .xm files - which are "standard" file formats. The only drawback of this system is that you might end up in breaking up the theme and in this case the game simply won't run.

By default the makefiles in source package produce both .dat and .scr versions of all the available themes. Then the install scripts chose to install the default theme as a .dat file and other themes as .scr files, but you are free to change this behavior.

Directory issues

U61 reads datafiles from 2 different directories:

• The builtin theme directory. It should be something like "/usr/local/share/u61/theme" under GNU/Linux or "C:\Program Files\U61\data\builtin\theme" under Windows. This is where all the files coming with U61 are installed. Even if it's OK to modify these files directly, you should not modify them directly, since after you won't be able to get the genuine themes back easily.
• The user theme directory. It should be something like "~/.u61/theme" under GNU/Linux or "C:\Program Files\U61\data\user\theme" under Windows. These directories are empty when you first install the game. This is where you should put your home-made themes, so that there's no conflict with the builtin themes which are originaly shipped with the game.

Building new themes

About the makefiles

To build .dat and .scr themes, I use an IMHO quite complex makefile system, involving Python scripts which generate makfiles automatically. You might wonder why I did that since with ClanLib's support of .scr files I could have simply copied the source directory into the target install directory? Well, here's the answer:

• On one hand, I like the idea, when I create themes, to share files between themes. For instance the default and the fanfare themes use the same sprites for squares. It would be a nonsense to duplicate all those files in developpement. If I change these sprites, I do not want to make the changes twice.
• On the other hand, when the themes are installed. People might to add, delete, and share their installed themes if they have tweaked them. And in this case, if themes have been installed as .scr files, you never know what to delete and/or change. For instance, should you want to delete the fanfare theme, you would have to look at every file it uses, and check that it is not used by another theme. And if you imported a friend's theme which uses patched versions of the genuine graphics, then all your already installed themes would be affected.

Therefore, the makefiles build .scr files from .theme files. The .theme file is the developper file, with references to files in the square or sound directories, and the .scr file is the final file which will be read by U61, and it contains references to files in a directory which is automatically created and contains a copy of all the required files. This way, each theme is stored in a independant directory.

However, if you want to tweak an existing theme, you can simply take the installed .scr and associated directory and start tweaking theme right away without bothering with all this makefile stuff. But keep in mind that if you want your theme to become part of the "official" U61 distribution, creating it with the same makefile system I used will make things much easier in the long run.

Getting started

Let's say you want to build a new "foo2" theme from an existing "foo" theme. What you should first to is open the foo.scr file with a text editor, and look what's in it. It is a plain and quite self-explanatory file, so it should not take ages to understand its global structure.

So just copy the existirg foo.scr theme and its associated directory from the builtin theme directory ("/usr/local/share/u61/theme" under GNU/Linux or "C:\Program Files\U61\data\builtin\theme" under Windows) to the user theme directory ("~/.u61/theme" under GNU/Linux or "C:\Program Files\U61\data\user\theme" under Windows) and when you run U61, you should see the theme foo appear twice in the list of available themes. One is the builtin theme and one is the theme you just copied.

Rename the foo.scr file you have copied to foo2.scr, (only the foo.scr should be renamed for now but not the foo directory, since this freshly copied foo.scr file still has references to a directory which name is foo). Now if you restart u61, foo (the builtin theme) should be available along with foo2 (the one you have just copied/renamed).

You are now ready to tweak foo2.

Naming conventions

All the sections follow some basic naming conventions:

• a "_w" suffix indicates that the value is a width
• a "_h" suffix indicates that the value is a height
• a "_x" suffix indicates that the value is an x coordinate. 0 is associated to the left of the screen.
• a "_y" suffix indicates that the value is an y coordinate. 0 is associated to the top of the screen.
• an "offset_" prefix indicates that the value is an offset which will be added to the top-left corner of the zone the item is associated to.
• a "_big" suffix indicates that the value is used when drawing a map for a local player. Usually twice bigger than its _small equivalent.
• a _small suffix indicates that the value is used when drawing a map for a remote player. Usually twice smaller than its _big equivalent.

The property section

This section contains integer values which are used to define the size of the theme (640x480, 800x600...) and the position of various items on the screen. All dimensions are given in pixels.

Here is the list of all the values:

• screen_w, screen_h: the size of the window in windowed mode, or the resolution in full-screen mode.
• player_w, player_h: the size of the zone which is associated to a player. This includes the map and the info zone. Those zones will be tiled and/or centered automatically.
• offset_map_x_big, offset_map_y_big, offset_map_x_small, offset_map_y_small: the position of the map background bitmap. This bitmap is the main background image a player sees on his playfield. The offset is added to the position of the player's zone, which is calculated at run-time.
• offset_info_x_big, offset_info_y_big, offset_info_x_small, offset_info_y_small: the position of the info background bitmap. This bitmap is the background image of the info zone, where score and other information are displayed. The offset is added to the position of the player's zone, which is calculated at run-time.
• offset_squares_x_big, offset_squares_y_big, offset_squares_x_small, offset_squares_y_small: the position of the top-left square. Indeed, the background bitmap might be bigger than the actual playfield, so ususally this value is the size of the "border". The offset is added to the position of the map background image, which is not necessary the same the the global position of the player.
• offset_name_x_big, offset_name_y_big, offset_name_x_small, offset_name_y_small: where the name of the player should be displayed. The offset is added to the position of the info background image.
• offset_score_x_big, offset_score_y_big, offset_score_x_small, offset_score_y_small: where the score of the player should be displayed. The offset is added to the position of the info background image.
• offset_target_x_big, offset_target_y_big, offset_target_x_small, offset_target_y_small: where the name of the target should be displayed. The target is the player's next victim, who will receive a curse whenever the player gets an occasion to send one. The offset is added to the position of the info background image.
• offset_preview_x_big, offset_preview_y_big, offset_preview_x_small, offset_preview_y_small: where the next block preview should be displayed. The offset is added to the position of the info background image.
• offset_curses_x_big, offset_curses_y_big, offset_curses_x_small, offset_curses_y_small: where the list of curses which affect the player should be displayed. The offset is added to the position of the info background image.
• offset_antidotes_x_big, offset_antidotes_y_big, offset_antidotes_x_small, offset_antidotes_y_small: where the number of available antidotes should be displayed. The offset is added to the position of the info background image.

The font section

This section contains all the fonts used in the game, plus some special fonts used to display curses and antidotes.

There two kinds of fonts in ClanLib:

• The first kind is the one I use but it's deprecated. You have to make a 256 color indexed bitmap, and tell which color is the transparent color. One also needs to draw rectangles with colors 253,254 and 255 to tell the font engine where the letters are. Check the existing fonts in U61 to have more information on how to make this kind of fonts.
• Alpha based font can be built from .tga files. Check out ClanLib's doc to know more about this kind of fonts.

Here is the list of all the values:

• menu: font used to display the menus. Must contain all the common ascii characters.
• info_big, info_small: font used to display the informations in the info zone, such as scores and players names.
• symbol_big, sumbol_small: special font used to display the curses and antidotes. The "-" character represents the negative curses, the "+" character represents the positive curses, and the "a" character represents the antidotes.

The sound section

This section contains all the sounds, except the musics.

Here is the list of all the values:

• game_start: played when the program is launched.
• menu_move: played when the players moves up or down in the menus.
• menu_move: played when the players moves validates a choice in the menus.
• block_touch: played when a block lands at the bottom of the map.
• block_pattern: played when the player completes a pattern, for instance when a line disappears.
• player_start: played when a remote player joins the game.
• curse_received: played when a player receives a curse.
• player_loose: played when a player looses and restarts with a blank map.

The music section

This section contains all the musics, in .mod, .xm and in a more general manner in any format supported by MikMod.

Here is the list of all the values:

• number: the number of mods available. It's OK to make a theme with no music at all, in this case number must be 0.
• mod_n: the actual module files. In "mod_n" the "n" should be replaced by an index number, ranging from 0 to (the number of mods available)-1.

The square section

This section contains all the sprites used for the squares.

You need to provide 16 set of sprites, because there are 2 sizes (small and big) and 8 colors. For instance "small_3" is the set of sprites associated to color 3 used to dislay the squares for network players.

The bitmap files must contain 16 different pictures for each sprite, which will be used to animate the sprite. If you don't want to use the square animation, simply provide a sprite with 16 times the same picture.

Please check ClanLib's documentation to know more about sprites. IMHO a good way to understand how it works is to try and understand how the builtin squares in U61 have been created.

Here is the list of all the values:

• big_n, small_n: the standard squares.
• big_curse, small_curse: the special square which blinks and indicates where the current curse square is. BTW, the sprite does not need to handle the blinking, simply draw a standard 16 step sprite, and the game engine will handle the blink automatically.
• big_explosion, small_explosion: the sprite used to represent the explosion of a square before it disappears.

The map section

This section contains all the background pictures used for the player's playfield.

Here is the list of all the values:

• number: the number of maps available. There must be at least one map so number can not be 0.
• big_n, small_n: the maps, where one should be able to put 10x25 squares. In "big_n" and "small_n" the "n" should be replaced by an index number, ranging from 0 to (the number of maps available)-1.

The back section

This section contains general background pictures.

Here is the list of all the values:

• main: the main background image. The one which is displayed when one launches the game, and is used as a background in any situtation.
• shade: this bitmap is blitted on the screen in the in-game menus. By default I use a plain bitmap which makes everything look darker.

The info section

This section contains the background pictures used for the "info" zone, where the score and other parameters are displayed.

Here is the list of all the values:

• big, small: the picture used to fill the "info" zone.