knights/CreatingThemes

====================
  Creating Themes
==================== 

This document is your guide to creating themes for the Knights chess
interface.

-----------------------
1. Anatomy of a Theme:
-----------------------

A theme is a collection of images, sounds, and settings which create a
unique representation of a chess environment. Typically, this theme is in the
form of a gzipped tarball.

There are three types of themes for Knights: Chessboard themes, Chessmen
themes, and Audio themes. 

------------------------
2. Tarball Information:
------------------------

Themes must be stored in tarballs. Knights will use any type of tarball that
KDE supports. A good test is to try loading it in Konqueror using a
tar://mytarball URL. Generaly speaking, using the standard gzipped tarball
( with a '.tar.gz' extension ) will be fine.

The first two letters of your filename must be 'KB', 'KC', or 'KS' depending on
the type of theme it is. KB tells Knights that it is a Chessboard theme, 
and KC represents Chessmen themes. KS is a sound theme. This is 
case-sensitive.

Between the prefix and the extension comes your theme's name. Write it exactly
how you want it displayed in Knights, except use underscores instead of spaces.
So if you want your theme to be called "My Uber Chessmen" within Knights, you'd
have the following filename: KCMy_Uber_Chessmen.tar.gz

As a general rule, you should remove write and execute permissions on the
files, and either remove Owner/Group attributes, or make them something
harmless ( like nobody:users )

---------------------------
3. theme.conf Information:
---------------------------

Every theme must contain a text file called 'theme.conf'. Here's a
sample theme.conf file:

################################
# A Sample theme.conf file
################################
[General]
Type=Board
Name=Default
Version=1.0
Author=Troy Corbin Jr.
AuthorEmail=tcorbin@users.sourceforge.net
AuthorWWW=http://knights.sourceforge.net
Notes=This is the default chessboard for Knights. It was made with the Gimp.

[2DWhite]
King=white.king.png
Queen=white.queen.png
Bishop=white.bishop.png
Knight=white.knight.png
Rook=white.rook.png
Pawn=white.pawn.png

[2DBlack]
King=black.king.png
Queen=black.queen.png
Bishop=black.bishop.png
Knight=black.knight.png
Rook=black.rook.png
Pawn=black.pawn.png

[2DBoard]
Light=square.light.png
Dark=square.dark.png
Motion=square.motion.png
Select=square.select.png
Danger=square.danger.png

[Coordinates]
TextColor=255,255,255
ShadowColor=0,0,0

[Audio]
Select=select.wav
Move=move.wav
Check=check.wav
MatchOver=matchover.wav
Challenge=notify.wav
Tell=tell.wav
Notification=notify.wav
DrawOffer=draw.wav
Say=tell.wav
Promote=promote.wav
################################

Nothing too tough to figure out. 'Type' must be one of the following:

- Board
- Chessmen
- Audio
- 3DBoard ( For future use )
- 3DChessmen ( For future use )

'Name' is your theme's name and 'Version' is the version of your theme. Author,
AuthorEmail, and AuthorWWW should be self explanitory. Notes are any comments
you want to add.

The '2DWhite' and '2DBlack' sections are required in Chessman themes. Each line
specifies the file to be used for each different piece type.

'2DBoard' and 'Coordinates' are required in Chessboard themes. 'Light' and
'Dark' specify the file to be used for each color square on the board. 'Motion'
is the highlight used to indicate that a piece moved, 'Select' is the selection
highlight, and 'Danger' indicates an attacked piece. The 'Coordinates' are
standard 8bit RGB colors. These are the colors that Knights will use for board
coordinates. Try to use colors that contrast with the board itself.

New in Knights 0.5.6 are Chessboard borders. They are not required, but they
can greatly enhance the appearance of your chessboard. If you'd like to use one
then under '2DBoard' add the following lines:

HaveBorder=true
Border=border.png
BorderLightOn=light_on.png
BorderLightOff=light_off.png

-----------------------
4. Pixmap Information:
-----------------------

Your pixmaps can be in any format that Qt supports, as long as it supports an
alpha channel. For this reason you are strongly encouraged to stick with PNG
images. Note that there are a few exceptions to this in Chessboard themes. The
'Light', 'Dark', and 'Border' pixmaps constitute the lowest layer of graphics,
and so they will never be transparent. Therefore, for these items you can use
non-transparent file types ( like JPEG ).

Knights will scale your pixmaps to the current theme size. This means you can
supply any sized images you want and Knights will make it work. However, when
Knights has to enlarge a pixmap, the resulting image tends to be of poor
quality. To keep this from happening to your themes, you should make all your
pixmaps 144 pixels by 144 pixels. This ensures that your images will never be
enlarged, and it's not so large that it's wasteful.

Borders are an exception to the size rule. The 'Border' itself needs to be 9
times the size of your other images. So if you use the recommended 144 pixel
image size, the 'Border' needs to be 1296 pixels. Likewise, the 'BorderLightOn'
and 'BorderLightOff' images need to be half the size of your other images. So
a regular size image of 144 pixels required that the lights be 72 pixels.

----------------------
5. Audio Information:
----------------------

Like pixmaps, you can supply your audio using any file format that aRts
supports. I recommend you stick with .wav and .ogg, although the last time
I checked aRts' Ogg Vorbis support was flaky with short sounds. Also, for
very short sounds, .wav files are actually smaller. It's best to try both
and see which works best with your paticular sounds.

----------------------
6. Copyrights:
----------------------

If you're planning to share your themes with the Knights Project, you must be
the copyright owner on all the material contained in the theme. As much as I'd
love to see the heads of Neo and Agent Smith flying around the board, I don't
want to recieve any nasty letters from Warner Brothers.

Your material must also be released under a GNU or similar license. If you're
in doubt, contact us and we'll work it out.