How to create a new Theme
=========================

Creating a theme for BGBlitz is easy... at least adapting the graphics to BGBlitz is easy. 
Creating a good looking and playable board is hard work ;)

In the folder/directory "themes" exist another folder/directory and a xml file for each Theme e.g. xxx.xml and xxx

In xxx.xml is described, which name the theme has and the name of the folder/directory where the images are e.g.:
 <themeInfo displayName="Xxx (big, Author Name)" name="xxx" />

In the folder/directory xxx is another file called xxx.xml that describes the graphics of the theme.
Comments are only for this HowTo and start with a //.  
 
<?xml version="1.0" encoding="UTF-8"?>          // has to be there to be a valid xml file
<theme displayName="Xxx (big, Author)" >        // the displayName has to match the displayName in the other file

<background name="background.jpg" numbersType="oneImage" numbersXoff="0" numbersYoff="0" additionalCubeArea="79,298,34,34" >
        <numbers type="LRD" name="numbersLRD.gif"/>
        <numbers type="RLD" name="numbersRLD.gif"/>
    </background>
//<background> describes the background 
// name                the name of the background picture. Could be a GIF or JPEG. A PNG is possible too, but doesn't run
//                     on Java 1.1, so it isn't possible to use it with Mac OS 9.
// numbersType         "oneImage"   the numbers are displayed in one image. "twoImage" two number images are displayed
// numbersXoff         how many pixels in x direction the numbers image should be moved 
// numbersYoff         how many pixels in y direction the 1st numbers image should be moved 
// numbersYoff2        how many pixels in y direction the 2nd numbers image should be moved 
// additionalCubeArea  hard to explain. Used when the centered cube has another position than the not centered cube
//                     see Plexi theme  
// <numbers> describes the number images to be drawn over the background
// type                could be LRD LRU, RLD RLU 
// LRU                 means: playing from left to right; player is in the upper half   DEPRECATED
// RLD                 means: playing from right to left; player is in the lower half
// name                is the file name of the number image

<dice type="sixImage" red="dice_red?.gif" green="dice_green?.gif" leftX="224" rightX="610" leftX2="280" rightX2="666" masktype="twoImage" calculateShadow="true"/>
// <dice> describes the dice. There could be one single image or six different pictures for the dice
// type                valid values are "sixImage" and "oneImage"
// red                 the name of the dice image file. In the case of "oneImage" it must be a real file name. In the case 
//                     of sixImage the "?" is replaced with values 1 to 6 to give the real file name.
// green               see red
// leftX               the x position of the left dice on the left side
// rightX              the x position of the right dice on the left side 
// leftX2              the x position of the left dice on the right side. Optional.
// rightX2             the x position of the right dice on the right side. Optional.
// masktype            the graphics to use to indicate which dice are already used. (version 2.7 and higher)
//                     masktype could be:
//                              "twoImage"    when a full and a half grey mask are sufficient for all dice
//                                            in this case the names must be "dice_mask_f.png" (full) and
//                                            "dice_mask_h.png" for the half.
//                              "sixImage"    when each dice needs a different mask but both player use the same mask
//                                            in this case the names must be "dice_mask1_f.png", "dice_mask2_f.png" and
//                                            "dice_mask1_h.png" and so on.
//                              "twelveImage" when a separate mask is needed for all dice and all player
//                                            in this case the names must be "dice_mask1l_f.png", "dice_mask2r_f.png" and
//                                            so on.where "l" and "r" stand for "left" and "right". Technoboard is the only 
//                                            example for twelveImage so far
// calculateShadow    true or false : shall shadows generated on the fly (as with the checkers) Optional. default false
    

 <cube type="oneImage" name="cubes.gif" max="64" initialType="two" initialAtEnd="true" firstIsLeft="true" 
       centeredCubeXOffset="31" leftX="13" rightX="594" offsetY="30"/>
// the <cube> tag describes the doubling cube       
// The cube can be provided in different images or in one single image.
// type                valid are "sixImage" and "oneImage"
// name                the name of the cube image file. In the case of "oneImage" it must be a real file name. In the case 
//                     of sixImage the "?" is replaced with values 2, 4, 8, 16, 32, 64 up to the maximum cube given. If 
//                     there are special images for the centered cube the appendix is "64_L" and "64_R".
// max                 what is the maximum number an cube image is provided for (e.g. 64)     
// initialType         valid values "none", "one", "two". Are there special images for the centered cube?
// initialAtEnd        "true"/"false". When you use one picture and have special centered cube pictures: are they at the end
//                      of the image or at the beginning?
// firstIsLeft         "true"/"false" when you use one picture and have two special centered cube pictures is the first one 
//                     the left one?
// centeredCubeXOffset used in conjunction with background/additionalCubeArea. How many pixels is the centered cube 
//                     shifted to the center. See Plexi theme.
// leftX               overrides the default x-position on the left side
// rightX              overrides the default x-position on the right side
// offsetY             shifts the not centered cube on the y axis
// centeredCubeYOffset shifts the centered cube on the y axis

<checker red="checker_red.gif" green="checker_green.gif" offsetX="7" offsetY="29" offsetLeftHome="0" offsetRightHome="0">
    29,106,160,214,268,322,376,433,492,546,600,654,708,762,840
</checker>
// <checker> describes the images an position of the checkers.
// red                 the name of the image file for the red checker
// green               the name of the image file for the green checker
// offsetX             an x offset added to each checker in the case the calculated values are wrong. It's easier to set 
//                     the x coordinates individually for each column
// offsetY             same for Y
// offsetLeftHome      the home has often a different offset than the other checkers. Here you can set the x value
// offsetRightHome     the home has often a different offset than the other checkers. Here you can set the x value
// topLow              "true"/"false" optinal parameter. There are two bitmaps for the checker one for top one for low.
//                      If the board is turned left/right top and low are changed. In the name of the checker has to be
//                     a "?" that is replaced with an "t" and an "l"
// In the body of the tag are the x coordinates of the checkers. Recommended way to position    

<indicator redLeft="ind_red_l.gif" redRight="ind_red_r.gif"
           greenLeft="ind_green_l.gif" greenRight="ind_green_r.gif" 
           offsetX="2" offsetY="25" shiftY="3" 
           hasInactive="true"/>
// the indicator shows whoi's turn it is. The <indicator> tag describes gifs and positions of the turn indicator
// redLeft             the turn indicator for red on the left side
// redRight            the turn indicator for red on the right side
// greenLeft           the turn indicator for green on the left side
// greenRight          the turn indicator for green on the right side
// offsetX             how many pixels to shift to the center in x direction
// offsetY             how many pixels to shift to the center in y direction
// shiftY              how many pixels to shift to the top
// hasInactive         optional attribute: if true indicator images are also shown on the inactive side. The image files has 
//                     to follow the name convention that if file X.png is the normal indicator X_i.pmg is the inactive inidicator.
               
Looks complicated? I guess yes. The most easy way to create a new theme is probably to copy an existing theme, rename it 
and then change part after part. Or look at some themes and play around with the parameters. If there are questions just 
drop me an email.

There is the undocumented flag in the bgblitz.cfg
General.enableReloadTheme=true
If it is set (any editor can edit bgblitz.cfg, just BGBlitz shoudln't run when editing) there is an entry 
"Reload Themes" under "Miscellaneous" that reloads the theme, so one can see the the changes immidiately 
and doesn't have to restart BGBlitz.

If there is a demand for a special feature, just ask.

regards
Frank