U61 (v1.0.1) - 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.

