1. Overview

This documentation introduces the basic skinning tools used by the P.I.S.D. Layers. Applications and games are free to use these tools as they wish. Therefore they may not implement all the functionality detailed here. There are specific notes at the end of this document on some individual applications using the P.I.S.D. skinning system.

2. Image Box

An image box is a rectangular area of specified size made by combining one or more images. An image box uses a set of image files with matching file names. Image Boxes load a set of 1,3 or 9 images which it then tiles or re sizes to produce the box of the requested size. The file names match the following pattern:

<base_name>_<ibox_position>.<image_filetype>

The base name can be anything you like and is used to identify the members of the image box. The image box position identifies where in the box the image belongs. This is dependant on the number of images that make up the set. The system automatically works out which kind of image box to use by the files it finds. Therefore it is important to make sure you have all the images that make up the image box otherwise it will not load. Image file type can be any supported image format such as JPG or PNG. It is recommended to use PNG rather than JPG as a JPG image slightly distorts the image and can create strange effects when the image box is drawn.

2.1. Image Box - 9 Way

This is the best image box to use as it will re size in both directions with little or no distortion. The files required for a 9-way image box are:

skinning_images/9way.png

1. <base_name>_top_left.png
2. <base_name>_top_mid.png
3. <base_name>_top_right.png
4. <base_name>_mid_left.png
5. <base_name>_mid_mid.png
6. <base_name>_mid_right.png
7. <base_name>_bottom_left.png
8. <base_name>_bottom_mid.png
9. <base_name>_bottom_right.png

2.2. Image Box - 3 Way

Horizontal

Horizontal image boxes work best when their height does not change very much. They will scale horizontally with little or no distortion but if the height varies by more than a few pixels it will start to distort.

skinning_images/3wayh.png

1. <base_name>_left.png
2. <base_name>_mid.png
3. <base_name>_right.png
Vertical

Vertical image boxes work best when their width does not change very much. They will scale vertically with little or no distortion but if the width varies by more than a few pixels it will start to distort.

<base_name>_top.png
<base_name>_mid.png
<base_name>_bottom.png

2.3. Image Box - Single Image

Single image, image boxes are not that helpful as any change in size will cause distortion. They should only be used when you are confident the object is of a fixed size and splitting the image up into 9way or 3way tiles is too complex or unnecessary.

2.4. Image Box - Auto Sliced Single Image

To make life easier the image box system can split a single image into component images automatically. This can simplify the skinning process while retaining the flexibility of the image box resizing system. This will not work in cases where the split is not symmetrical or requires custom splitting positions. It is intended to work in most cases as a convenient way to produce and handle image box images. By naming the single image as shown below you will instruct the system to chop up your image into the corresponding image box type as detailed above.

<base_name>_9way.png
<base_name>_3wayh.png
<base_name>_3wayv.png

3. Button Image Boxes

In the case of buttons you can specify an image box for each state the button can have. The following image boxes are required to draw this object:

<base_name>_up_<ibox_info>

The button is in its natural idle state.

<base_name>_down_<ibox_info>

The button is pressed by either the mouse or keyboard shortcut.

<base_name>_<ibox_info>

Used for up and down states if both fail to load.

The following image boxes are optional:

<base_name>_disabled_<ibox_info>

The button is not functional.

<base_name>_active_up_<ibox_info>

The button is not pressed and in its active state.

<base_name>_active_down_<ibox_info>

The button is pressed by either the mouse or keyboard shortcut and in its active state.

<base_name>_active_disabled_<ibox_info>

The button is not functional and in its active state.

<base_name>_active_over_<ibox_info>

Mouse is hovering over button and in its active state.

<base_name>_highlighted_<ibox_info>

Button is highlighted.

<base_name>_over_<ibox_info>

Mouse is hovering over button.

<base_name>_flashing_<ibox_info>

If provided, the button alternates with this image box at regular intervals.

<base_name>_dragging_<ibox_info>

If provided, the button uses this image box when it is being dragged. If this is not supplied a semi-transparent image of the current button state is used.

For example, if you want to create a set of images for a button when the mouse if hovering over it using a 9-way image box, you need the following images:

<base_name>_over_top_left.png
<base_name>_over_top_mid.png
<base_name>_over_top_right.png
<base_name>_over_mid_left.png
<base_name>_over_mid_mid.png
<base_name>_over_mid_right.png
<base_name>_over_bottom_left.png
<base_name>_over_bottom_mid.png
<base_name>_over_bottom_right.png

You can then repeat the above replacing "over" with "down" to create the images to show a button in the down state (i.e. pushed by the user clicking on it).

4. Style Sets

The skinning system is built around style sets. Each one details a look that can be applied to any on screen object. They are simple text files allowing you to link to images, set spacing and a selection of other visible settings.

Style sets can work in two different ways, graphical or API mode.

In API mode, the object defined by the style set will use API drawing routines to render the object. These are such tools as draw_line() and draw_rect(). This creates a very fast but rather simple, dated look. You can use the style set to control the colours used to draw the object and a few simple settings.

In graphical mode, image box(s) are used to render the object. This is achieved by setting the "image_filename" field in the style. This is used as the <base_name> field when loading in image boxes. When in graphical mode the API drawing information is not used and can be ignored.

Here are the supported settings for a style set:

name

The name of this style set. It can be used by the application to locate this style set. It does not have to be unique, however if the application searches for the name and there are two identical entries it may not find the right style set.

image_filename

The base name of the image box(s) used to draw the object. If this is valid the object is drawn in graphical mode, otherwise API mode is used.

image_path

The path where the image box(s) are located. See Disk Paths for an explanation of path entries.

shading_type

TDB

fg_colour

The foreground colour of the object. In most cases this is the colour of text on the object. See Colour Formats for explanation of valid colour entries.

bg_colour

The background colour of the object. See Colour Formats for explanation of valid colour entries.

Only used when object is drawn in API mode
fading_colour

This colour is blended/faded with the background colour of the object when the ssf_hfading or ssf_vfading flags are set. See Colour Formats for explanation of valid colour entries.

Only used when object is drawn in API mode
highlight_colour

TDB

highlight_text_colour

TDB

active_colour

TDB

active_text_colour

TDB

mouse_over_colour

TDB

mouse_over_text_colour

TDB

flashing_colour

TDB

flashing_text_colour

TDB

underline_colour

TDB

visible

TDB

shading_flags

TDB

font_id

TDB

font_x_sz

TDB

font_y_sz

TDB

font_name

TDB

border_left_gap

TDB

border_right_gap

TDB

border_top_gap

TDB

border_bottom_gap

TDB

cell_left_gap

TDB

cell_right_gap

TDB

cell_top_gap

TDB

cell_bottom_gap

TDB

x_spacing

TDB

y_spacing

TDB

scrollbar_button_width

TDB

scrollbar_slider_width

TDB

grid_scrollbar_width

The width of the side scrollbar if present.

Only used by grid objects
grid_two_tone_value

The percentage by which each alternate grid row is darkened. I negative percentage can be used to lighten the alternate rows. The ssef_grid_two_tone flag must be set for this value to be used.

Only used by grid objects
ssf_draw_border

TDB

ssf_indent_border

TDB

ssf_outstanding_border

TDB

ssf_hfading

TDB

ssf_vfading

TDB

ssf_darkened_background

TDB

ssf_left_justify_text

TDB

ssf_right_justify_text

TDB

ssf_top_align_text

TDB

ssf_bottom_align_text

TDB

ssf_use_text_colour_for_outline

TDB

ssf_shadow_text

TDB

ssf_inset_text

TDB

ssf_chiseled_text

TDB

ssf_disabled

TDB

ssf_icon_left

TDB

ssf_icon_right

TDB

ssf_icon_top

TDB

ssf_icon_bottom

TDB

ssf_icon_attach_to_text

TDB

ssf_wrap_text

TDB

ssf_dont_resize_image

TDB

ssef_invert_vfading_on_press

TDB

ssef_indent_when_active

TDB

ssef_left_arrow

TDB

ssef_right_arrow

TDB

ssef_up_arrow

TDB

ssef_down_arrow

TDB

ssef_auto_depress

TDB

ssef_auto_activate

TDB

ssef_dont_mask_click

TDB

ssef_sb_horizontal

TDB

ssef_sb_with_buttons

TDB

ssef_te_password

TDB

ssef_grid_fix_top_row

Set to 1 for a fixed top row that does not scroll, otherwise set it to 0. This can be very useful for column headings so they are always visible.

Only used by grid objects
ssef_grid_two_tone

Set to 1 to make the grid darken every alternate row by grid_two_tone_value percent, otherwise set it to 0.

Only used by grid objects
ssef_grid_type_lines

Set to 1 to make the grid draw line by line, otherwise set it to 0. The grid background is calculated line by line.

Only used by grid objects
ssef_grid_type_cells

Set to 1 to make the grid draw cell by cell, otherwise set it to 0. The grid background is calculated cell by cell.

Only used by grid objects
ssef_grid_scroll_by_line

Set to 1 to make the grid scroll down a row at a time. Set to 0 to make the grid scroll one pixel at a time.

Only used by grid objects
ssef_grid_no_scrollbar

Set to 1 to stop the grid automatically creating a scrollbar when the number of rows exceeds the space to draw. Set to 0 to make the grid dynamically create a scrollbar as needed.

Only used by grid objects
ssef_grid_only_draw_used_lines

Set to 1 to stop the grid drawing unused rows at the end of the data. Set to 0 to make the grid draw blank lines after the data until the end of the grid.

Only used by grid objects
ssef_grid_dont_shorten_scrollbar

Set to 1 to make stop scrollbar being shortened below the fixed top row, otherwise set it to 0.

Only used by grid objects
ssef_pb_only_draw_bar

TDB

ssef_pb_vertical

TDB

ssef_pb_no_shading

TDB

ssef_pb_position_text_on_bar

TDB

ssef_pb_draw_alt_percentage

TDB

ssef_fm_hide_scrolling_arrows

TDB

sssf_retain_width

TDB

sssf_retain_left_border

TDB

sssf_retain_right_border

TDB

sssf_retain_x_font_size

TDB

sssf_retain_height

TDB

sssf_retain_top_border

TDB

sssf_retain_bottom_border

TDB

sssf_retain_y_font_size

TDB

5. Graphical Button Using Style Sets

In order to define a graphical button using a style set you first need to create the required image box sets for each button state you want. In this example we will create a button using 3-way Horizontal image boxes for the up, down and over button states. We will use a base name of "my_button", but this could be anything we like that identifies this buttons images. So that means we need the following images:

skinning_images/button_states.png

1. my_button_up_left.png
2. my_button_up_mid.png
3. my_button_up_right.png
4. my_button_over_left.png
5. my_button_over_mid.png
6. my_button_over_right.png
7. my_button_down_left.png
8. my_button_down_mid.png
9. my_button_down_right.png

Assuming the above images are in a sub folder named "ibox_images", you would then make the following changes to the style set to tell it which images to use:

image_filename
        my_button
image_path
        $HERE/ibox_images

Now when this style set is used to skin a button, the images you created above will be used to draw that button.

6. Grid Style Set

Grids are often used to display tables of data. It is often hard to read a grid if the background is one uniform tone or colour. There are a number of tools to change the visual appearance of grids to make them easier to see.

ssef_grid_type_cells and ssef_grid_type_lines can make the lines stand out by changing the way the grid draws its background. This is not suitable if you want to round the corners of your grid as it would round each cell or each line respectively.

You can use ssef_grid_two_tone and grid_two_tone_value to darken each alternate line. If you wish to lighten the line you can supply a negative two tone value. This easily adds a subtle line effect that can help the visual impact of a grid.

The last option is only available if it is supported by the application you are skinning. It is possible to supply separate style sets for alternate rows. So all the even numbered rows use one style set and the odd numbered rows use another style set. This gives you the most graphical control, however not all applications support this method.

All there methods above work in conjunction with each other. This allows you to combine the effects to create the desired look..

7. Colour Formats

There are three supported colour formats, RGB, HSL and CMYK. RGB is how the graphics hardware works and therefore is used internally by the system. This means both HSL and CMYK need to be converted which can introduce slight errors. This means you should consider using the RGB format in preference to HSL and CMYK.

The CMYK format is designed around printer hardware, specifying the amount of each coloured ink needed to create the desired colour. This means the RGB and CMYK systems are very different in how they combine colours. For example all colours combined with the CMYK system creates black, but all colours combined with the RGB system creates white. Conversion between these different systems is only approximate as a result, so any colour specified as CMYK is not going to be very accurate.

The skinning system uses a full 8-bit alpha channel which is pre-pended to the three supported colour formats. So RGB becomes ARGB, where the A indicates the alpha value. An alpha channel of zero means the colour is transparent, with an alpha channel of the maximum range being solid.

In order to make things simpler the system understands four different number ranges. They are all the same internally so feel free to use whichever number range you feel most comfortable using.

7.1. Using hexadecimal (Base16)

#010203

This specifies a colour using RGB format in hexadecimal where the alpha is solid, red is 0x01, green is 0x02 and blue is 0x03.

NOTE: This is a special case and is included for compatibility with HTML colour specifications.
#FF010203

This specifies a colour using ARGB format in hexadecimal where the alpha is 0xFF, red is 0x01, green is 0x02 and blue is 0x03.

#AHSL FF010203

This specifies a colour using AHSL format in hexadecimal where the alpha is 0xFF, hue is 0x01, saturation is 0x02 and level is 0x03.

#ACMYK FF01020304

This specifies a colour using ACMYK format in hexadecimal where the alpha is 0xFF, cyan is 0x01, magenta is 0x02, yellow is 0x03 and black is 0x04.

7.2. Using Percentage (0-100)

%100,1,2,3

This specifies a colour using ARGB format in percent where the alpha is 100%, red is 1%, green is 2% and blue is 3%.

%AHSL 100,1,2,3

This specifies a colour using AHSL format in percent where the alpha is 100%, hue is 1%, saturation is 2% and level is 3%.

%ACMYK 100,1,2,3,4

This specifies a colour using ACMYK format in percent where the alpha is 100%, cyan is 1%, magenta is 2%, yellow is 3% and black is 4%.

7.3. Using Decimal (0-255)

&255,1,2,3

This specifies a colour using ARGB format in the range 0-255 where the alpha is 255, red is 1, green is 2 and blue is 3.

&AHSL 255,1,2,3

This specifies a colour using AHSL format in the range 0-255 where the alpha is 255, hue is 1, saturation is 2 and level is 3.

&ACMYK 255,1,2,3,4

This specifies a colour using ACMYK format in the range 0-255 where the alpha is 255, cyan is 1, magenta is 2, yellow is 3 and black is 4.

7.4. Using Normalised (0.0-1.0)

@1.0,0.1,0.2,0.3

This specifies a colour using ARGB format in the range 0.0-1.0 where the alpha is 1.0, red is 0.1, green is 0.2 and blue is 0.3.

@AHSL 1.0,0.1,0.2,0.3

This specifies a colour using AHSL format in the range 0.0-1.0 where the alpha is 1.0, hue is 0.1, saturation is 0.2 and level is 0.3.

@ACMYK 1.0,0.1,0.2,0.3,0.4

This specifies a colour using ACMYK format in the range 0.0-1.0 where the alpha is 1.0, cyan is 0.1, magenta is 0.2, yellow is 0.3 and black is 0.4.

8. Disk Paths

The core design of the P.I.S.D. Layers aims to remove platform specific knowledge. One of the areas where this is most obvious is disk paths. Each OS has its own way to identify and handle disk drives and devices. For example Microsoft Windows uses driver letters (c:\, d:\, etc) which are not understood on Apple Mac or Linux. The P.I.S.D. Layers handle this by creating a set of useful locations the core of which are relative to the application location. This allows paths to have a sensible meaning on all the platforms supported by the P.I.S.D. Layers. That way a path saved on one platform has a good chance of working on another.

The locations can be considered equivalent to drive specifications. You can append sub-folders using the / character. Do not use a the windows \ character as it is not supported. So to set the path to an installed data file in the sub folder "my-path" you should use "$APPDATA/my-path".

Here are the known folder locations:

$APP

location of the running program

$APPDATA

system specific location of shared, installed, read only data (set to $APP/data)

$USERAPP

location of user specific applications that can be installed by the current user. (if folder not found it is set to $APP)

Windows: CSIDL_APPDATA\<app_name>
        98/XP/2k = C:\Documents and Settings\<username>\Application Data\<app_name>
        Vista/7  = C:\Users\<username>\AppData\Roaming\<app_name>
Mac:     kCurrentUserFolderType/.<app_name>/bin
        /Users/<username>/.<app_name>/bin
Linux:   ~/.<app_name>/bin
$USERDATA

User specific location of installed read/write data that can be installed by the current user. Data in this folder should not require the user to access it from outside the application. (if folder not found it is set to $APP/data)

Windows: CSIDL_APPDATA\<app_name>
        98/XP/2k = C:\Documents and Settings\<username>\Application Data\<app_name>
        Vista/7  = C:\Users\<username>\AppData\Roaming\<app_name>
Mac:     kCurrentUserFolderType/.<app_name>/data
        /Users/<username>/.<app_name>/data
Linux:   ~/.<app_name>/data
$USERPREFS

system specific location of user customisable data/preferences that can be installed by the current user. Data in this folder may require the user to access it outside the application using 3rd party tools such as a text editor. (if folder not found it is set to $APP/data)

Windows: CSIDL_PERSONAL\<app_name>
        98/XP/2k = C:\Documents and Settings\<username>\My Documents\<app_name>
        Vista/7  = C:\Documents and Settings\<username>\My Documents\<app_name>
Mac:     kDocumentsFolderType/<app_name>/custdata
        /Users/<username>/Documents/<app_name>
Linux:   ~/.<app_name>/custdata (Symlinked to ~/Documents/<app_name>)
$SYSAPP

location of system wide applications and can only be installed with root access (if folder not found it is set to $APP)

Windows: CSIDL_PROGRAM_FILES\<app_name>
        98/XP/2k = C:\Program Files\<app_name>
        Vista/7  = C:\Program Files\<app_name>
Mac:     /Applications/<app_name>
Linux:   /opt/<app_name>/bin
$SYSDATA

system specific location of shared, installed, read/write data. This folder requires root access to install, but once created any user can change it. Data in this folder should not require the user to access it from outside the application. (if folder not found it is set to $APP/data)

Windows: CSIDL_COMMON_APPDATA\<app_name>
        98/XP/2k = C:\Documents and Settings\All Users\Application Data\<app_name>
        Vista/7  = C:\ProgramData\<app_name>
Mac:     kSharedUserDataFolderType/<app_name>/data
        /Users/Shared/<app_name>/data
Linux:   /opt/<app_name>/data
$SYSPREFS

system specific location of shared, customisable, data/preferences (read/write) This folder requires root access to install, but once created any user can change it. Data in this folder may require the user to access it outside the application using 3rd party tools such as a text editor. (if folder not found it is set to $APP/data)

Windows: CSIDL_COMMON_DOCUMENTS\<app_name>
        98/XP/2k = C:\Documents and Settings\All Users\Documents\<app_name>
        Vista/7  = C:\Documents and Settings\All Users\Documents\<app_name>
Mac:     kSharedUserDataFolderType/<app_name>/custdata
        /Users/Shared/<app_name>/custdata
Linux:   /opt/<app_name>/custdata
$DATA

location of data for running app

Set to the first found of these locations in this order:
        $USERDATA
        $SYSDATA
        $APPDATA
        $APP
NOTE: If you use this with the create_if_not_found set the system will create the first folder it can in the given order.
$TEMP

system specific location of temp data (if not folder not found it is set to $APP/temp)

Windows: CSIDL_PERSONAL\<app_name>\temp
        98/XP/2k = C:\Documents and Settings\<username>\My Documents\<app_name>\temp
        Vista/7  = C:\Documents and Settings\<username>\My Documents\<app_name>\temp
Mac:     kTemporaryFolderType/<app_name>
        /private/var/tmp/*/<app_name>
Linux:   ~/tmp/<app_name> or /tmp/<app_name>
$ROOTx

root folder of drive/device x (where x is the drive/device number)

$FONTDATA

location of font data (normally $APPDATA/fonts)

$ICONDATA

location of icon data (normally $APPDATA/icons)

$HERE

situation specific as it is passed in by the application. In the case of style sets it is the location of the current style set file.

$BASE

Depreciated - Use $APP

$INSTDATA

Depreciated - Use $APPDATA

9. Out Of The Park Baseball Skinning

The Out Of The Park Baseball skin does not allow the screen layout to be changed. This is deliberate due to the complexity of some of the screens. That said, there is the ability to adjust border sizes and alignment information. The style sets can be found in data/skins/ootp classic/style_sets.

Out Of The Park Baseball currently uses the "two tone" settings for grids (See Grid Style Set section) which darkens every alternate row. It does not support the alternate style set system.

Once you have changed the skinning information you will need to delete the skin cache file data/skins/ootp classic/skin.bin. When you restart the game it will take quite a bit longer to start as it reads all the skinning information and rebuilds the skin cache. On a Mac it can take a really long time as opening files can be rather slow. Or if you prefer you can select "rebuild skin" option from the game menu.

There are lots more settings and bits you can change. Its is very easy to mess things up so make sure you copy an existing skin and don’t change the supplied one so you can always get back in.

10. Title Bout Championship Boxing Skinning

Title Bout Championship Boxing uses binary skin files as they are faster to load and easier to share. However this can make modifying them a little harder. Title Bout has two command line options to assist in creating a custom skin that extracts and packs the skin data into a directory tree containing config, xml and image files:

--extractskin

Copies the currently selected skin data from the binary file and into the custom_skin folder.

--packskin

Packs the custom_skin data into a new skin file named "Custom Skin.bin" in the default skin folder.

In addition to the command line arguments above there are two hotkeys from version 1.3 onwards. Pressing F2 will save the current skin to the custom_skin folder in the same fasion as --extractskin. Pressing F3 will do the same as --packskin by reading in your custom skin folder and packing it into the "Custom Skin.bin". In addition it will load the newly packed skin to assist in testing. It is a good idea to only use F3 from the main page as reloading the entire skin during intense processing, such as running a fight, could have strange results.

If you wish to create your own skin it is a good idea to start from the default skin by running the game with the "--extractskin" command line option. Then change the contents of the custom_skin folder as much or as little as you wish. You can change graphics files, config files or change the objects in the page XML files under the custom_skin folder. Once you have finished modifying your skin, run the game again with the "--packskin" option to create a skin binary file. The new skin file will show up in the game options dialog as "Custom Skin" in the skin selection list box.

You can rename and upload the custom skin binary file to the Internet to share it with others. It is not a good idea to zip and upload the custom_skin folder as it is slow to load and will most likely fail to load on other systems as the paths are bound to be different.

Tips

Packing and extracting skin data can take some time, especially on slower or older systems. Please be patient. Its a good idea to make small changes and test them regularly so that if something goes wrong you know where the problem lies. Be very careful when changing the XML files as they can easily break the game if you don’t know what your doing.

Folders

The temporary skin folder is found in "$USERPREFS/custom_skin" and the binary skin files are found in "$USERPREFS/data/skins"

Command Line Arguments

Command line arguments are historically supplied via the shell/command prompt when starting the application. However in many modern operating systems it is considered unfashionable to use a text based shell to start applications. Therefore if you are not familiar with command line arguments you can use the PISD arguments file. Create a plain text file called "pisd_args.txt" in the same folder as the application which contains one command line argument on each line. The application will read in this file as it started and treat each line as if it was passed as a command line argument. Make sure you remove this file when you have finished with the command line arguments.

11. More help

If you get stuck then please feel free to email someone@pisd.co.uk for help.