Themes
Home |
Introduction |
Installation |
Quick start |
Troubleshooting |
Themes |
Script tutorial |
Script basics |
Script callbacks reference |
Script API reference |
Known bugs |
Frequently Asked Questions
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:
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.
The "u61" base package contains only one theme, because I try to keep this
file as light as possible. However, the "u61-data" contains more themes.
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 reuired to
build the default.dat file are of course available in the u61-data
package, so you can tweak it, even if it won't be as easy as with
other themes.
- .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. All the extra themes in the u61-data package
use this system, so they are very easy to tweak. 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 u61-data 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 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 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
In the u61-data package, 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 in the u61-data package 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 u61-data package, 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 Linux or
"C:\Program Files\U61\data\builtin\theme" under Windows)
to the user theme directory
("~/.u61/theme" under 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.
This documentation is also available on:
www.ufoot.org.
Contact author:
ufoot@ufoot.org