PokerStars Theme Integration Guide
|
This information is provided directly from PokerStars and can be found via the PokerStars FAQ page under the "Where can I find more about your game software?" question. It is information on how to create and integrate your own custom PokerStars theme. For additional information please see the PokerStars site.
PokerStars Theme Integration Guide
Version 0.9.3.5
I. Scope
This document describes how to add a third-party “theme” to the PokerStars client, where “theme” describes the look and feel of the GUI (graphic user interface) on the table. This guide can be used to create a custom theme for individual use or for a theme intended for distribution. Some of the points of this guide will apply only to themes intended for distribution and those points will be marked with “[DIST]” and “[ENDDIST]”.
This document is provided “as is”, without warranties of any kind, expressed or implied. PokerStars reserves the right to change these specifications at any time without notice. If these specifications change, PokerStars will attempt to maintain backward compatibility of its software with any themes that meet the specifications laid out in this document, but it is not guaranteed that this will be the case.
II. Creation and Registration of New Theme
Each new theme added to the PokerStars client must be included in the XThemes folder within the main PokerStars client folder. For the purposes of this explanation, we will assume that your folder for the PokerStars client is C:\Program Files\PokerStars\
Each theme (at this time) is based off of an existing “root” theme (that is, a theme that is included with the installation direct from PokerStars). To create a new theme, follow the steps listed below. For the purposes of this example, we will assume that you are going to name your new theme NEWTHEME-1 and base it off of the default PokerStars theme.
II.1.Create a subfolder in the XThemes folder for all of your custom themes. To avoid naming problems if you will ever want to share any of your themes with other players, we recommend to name this folder “your_PokerStars_user_name.pokerstars.com”. For the purposes of this example, we will use folder “user456.pokerstars.com”.
[DIST] Notes for creation of a theme with the intention of distributing the theme via a website, etc.
For theme distribution we strongly suggest to use name of your website as a name of this folder. For example, themes, distributed by web site myname.myisp.com, should use “myname.myisp.com” as a folder name. On the other hand, folder name may contain only letters, numbers and dots, so if your web site name is “geocities.yahoo.com/mysite”, use something like “mysite.geocities.yahoo.com”. For the purposes of this [DIST] example, we will assume that the website myname.myisp.com is distributing a theme named Omaholics, which is based off of the default PokerStars theme.
[ENDDIST]
II.2.Create a subfolder in the user456.pokerstars.com folder for your theme. In our example, your new folder should be:
C:\Program Files\PokerStars\XThemes\user456.pokerstars.com\NEWTHEME-1\
II.3.From the Gx client folder (C:\Program Files\PokerStars\Gx) or folder containing the theme off of which you are basing your new theme (see Appendix A.1 for more detailed explanation), copy the following files into the NEWTHEME-1 folder:
a) bg.bmp
b) fg.bmp and fg.a.bmp
c) the entire folder “label”
Note that all these items are optional.
II.4.Using image editing software, edit the files above to your liking.
- See the appendix at the end of this manual on the use of the program mskmgr for important information on proper display of your images.
II.5.In the folder C:\Program Files\PokerStars\XThemes\, find a file named xthemes.ini (create an empty file if it doesn't exist). This file is a standard Windows INI file with each section describing one theme; it must be edited for your new theme to be displayed within the PokerStars client. When editing this file, it is important that you do not remove any content previously in the file; add theme information to the end of the file. After you have added your new theme definitions to xthemes.ini, it should look like this:
[NEWTHEME-1@user456.pokerstars.com] - this line begins the definitions portion for each theme.
name=New Theme 1- defines the name of the theme shown within the client
copyright=(c) Your-name-here 2006 - optional display of copyright information within the client
folder=user456.pokerstars.com\NEWTHEME-1 - path to the theme, relative to the XThemes folder.
base=default@pokerstars.com - base theme name used for new theme, which enables the client to display the appropriate non-editable graphics for the given customized theme. Note that if the base theme used is not installed on the PokerStars client that any XTheme based on said theme will not function.
deck=default – optional name of default deck for the theme; currently may have one of the following values: "default", "large", "simple".
The whole section for the new theme NEWTHEME-1 will look as follows:
[NEWTHEME-1@user456.pokerstars.com]
name=New Theme 1
copyright=(c) John Q. Public 2006
folder=user456.pokerstars.com\NEWTHEME-1
base=default@pokerstars.com
**Important Note**: It is essential that each theme added to xthemes.ini has a unique name. Furthermore, it is strongly recommended that a backup copy of xthemes.ini is created before the file is modified.
[DIST] Notes for creation of a theme with the intention of distributing the theme via a website, etc.
For our [DIST] Omaholics example, the entry in xthemes.ini would look like this:
[Omaholics@myname.myisp.com]
name=Omaholics
copyright=(c) myname.myisp.com 2006
folder=myname.myisp.com\Omaholics
base=default@pokerstars.com
**Important Note**: If creating an automated installer which adds new themes to xthemes.ini, you MUST make sure that: (a) installer checks whether your theme is already registered in xthemes.ini; b) installer preserves all existing content of xthemes.ini; c) if using any method of modifying xthemes.ini other than opening the file in 'append' mode or WritePrivateProfileString API, installer MUST create a backup version of xthemes.ini named xthemes.ini.bak.
[ENDDIST]
III. Debugging
If a theme, after creation, is not displayed in the “Themes” dialog within the client, the problem is most likely with the xthemes.ini file. The first place to look for such a problem is the file PokerStars.log.0, found in the main PokerStars client folder.
When changes are being made to the xthemes folder while the client is open, it is possible for the client to malfunction. For example, if a designer deletes a file, while working in the folder, which the client needs to function, an error will occur. Information relevant to this type of error will appear in a pop-up window within the client, or in the file PokerStars.log.0.
Appendix A - Creating / Editing Image Files
A.1 Theme/folder structure
Themes work within a hierarchy in the client. Each theme is either a “root” theme, or refers back to a base theme for the display of certain images. When the client is working with a theme and the software calls for a certain image, if that image is not detailed in the theme folder then the client gets said image from the base theme's (as defined in xthemes.ini) folder. If said image is not there, either, then the client looks in that theme's base, and so on, until it reaches either a root theme or the Gx folder, which is the universal default for all images.
At present, only image files may be overridden by themes, thus negating the possibility of entirely new layouts. On the other hand, many elements of the table may be customized (with a few exceptions, noted below). When customizing an image, the replacement image must have the exact name as the image it is replacing, and it must be of the same type. (.bmp replaces .bmp, .jpg replaces .jpg). It is recommended to keep image size the same as original when editing; changing image size might be possible in certain cases but requires very careful testing and is not supported.
At present, the following files cannot be customized:
- non-image files
- content of the “fonts” folder
- contents of the “chips&deck” folder
A.2 Mask files
Mask files (those ending with *.a.bmp): mask files act in concert with their corresponding non-mask file (for example: fg.bmp and fg.a.bmp go together). In order for customized graphics used in fg.bmp to be displayed properly, changes might need to be made to fg.a.bmp. The mask file is essentially a transparency mask which filters corresponding non-mask file. Think of a photo on top of which one might put a sheet of black construction paper with a hole cut out of it to show only that portion of the photo which is not covered by black paper. In this analogy, the black paper is the mask file.
**Important Note**: if image file has a mask file, it is necessary to have both non-mask file and mask file in your custom theme folder (i.e. It is invalid to copy only fg.bmp not copying fg.a.bmp). You don't need to care about it if copying whole folders though.
Mask files are stored, initially, in a format that prevents them from being manipulated, graphically, with much ease. The program mskmgr.exe enables switching of the file format to one which can be worked on within an image editor. The syntax for the command, from a command prompt window within the theme's folder:
mskmgr image1.a.bmp image2.a.bmp /r, where image1 is the .a.bmp file and image2 is a temporary name created by the user for the purpose of editing the file. See more detailed description of mskmgr.exe in Appendix B.
Appendix B – Tools
There are 2 tools related to image manipulation within the scope of this guide (both are command-line executables for Windows platform).
B.1 mskmgr.exe
mskmgr.exe can be used to add/remove palette from mask (.a.bmp) files.
To add grayscale palette to the mask file (and therefore make mask bmp visible with usual graphical tools), use the following command:
mskmgr /r
To remove palette back (not strictly necessary, but will reduce bmp size), use the following command:
mskmgr
Note that in both cases and should point to different files.
B.2 png2bmp.exe
png2bmp.exe can be used to convert standard file in PNG format to 2 bmp files recognizable by the client program - image itself and mask file. Use the following command:
png2bmp
Note that png2bmp.exe requires PNG file to be of 24-bit format and have transparency.
Have you ever come across a confusing poker term? Our poker dictionary has 1224 definitions! Play for FREE and practice your game at...
Would you like to submit your own poker article to be featured on FTR? You can by clicking here - Submit a Poker Article!
|
English
Deutsch
Español
Français
Italiano
Nederlands
Pусский
Svenska
