How to create user-defined themes

A user-defined theme supports the same features as the standard themes that come with Four Winds. 

However, there are some differences between the two:

• Standard themes use 256-color graphics that use one common palette, so they can be used in all color modes supporting at least 256 colors. User-defined bitmaps can have any color depth but can be used only if the current screen mode supports at least 16-bit colors (High Color mode). This is to avoid problems related to using incorrect or incompatible palettes.
• Standard themes include two versions of all graphic elements, ones to be used with small and large game boards and ones to be used with medium and extra large boards. This is supported in user-defined themes, as well, but only the graphic elements for medium and extra large boards are required. If the "low-resolution" versions are missing, they will be created programmatically from the "high-resolution" versions (often with more or less mediocre results).
• Standard themes always include cursors (including animated cursors) and sounds. This is supported in user-defined themes, too, but they are not obligatory. Any element not available in the theme will be replaced by a corresponding element of the default Four Winds theme.
• Standard themes are compiled in a single .dll file while user-defined themes consist of maximum of three bitmaps and a .4wg configuration file placed in a separate folder under the Custom/Themes folder (see below). In addition, if a user-defined theme uses theme-specific cursors and sounds, these must be placed in the same folder.

To create user-defined themes, it is strongly recommended that you use Four Winds Theme Editor, a separate utility that can be downloaded free of charge from Four Winds web site. In addition to making the creation of user-defined themes easy, this utility includes documentation that explains in detail how the graphics must be created (e.g., the exact size of each bitmap and exact position of each graphic element that must be included, etc.).

Installing user-defined themes

Each user-defined theme must be placed in a separate folder under \Custom\Themes folder (Custom folder is by default a sub folder in the Four Winds program folder, or when Windows Vista or later is used, under the [Users]\[Public]\[Documents]\4Winds2 folder). The folder names are used directly in the user interface to identify the user-defined themes. The file names must be as follows ([MyTheme] denotes the name of the folder and your theme, e.g. "Garden"):

• [MyTheme]1.bmp – contains the "high-resolution" graphics to be used with medium and extra large game boards. This is an obligatory file and must contain all graphics elements used in the game, placed exactly in correct locations. Four Winds Theme Editor creates a correct layout automatically so it is recommended that this utility is used in creating user-defined themes.
• [MyTheme]2.bmp – contains the "low-resolution" graphics to be used with small and large game boards. If this file is missing, the needed graphics will be created programmatically from the bitmap above (often with more or less mediocre results).
• [MyTheme]3.bmp – contains the preview picture of the theme to be displayed in the user-interface when the user selects a theme in the Themes list (on the Themes option page of the Preferences dialog box). This is an obligatory file.
• [MyTheme].4wg – a standard ANSI text file that contains color settings to be used with the theme. The file also includes the description that is displayed in the user interface when the user clicks the About Theme button on the Themes option page of the Preferences dialog box. This is an obligatory file.
• Optional sound files with the following names (for any event that does not have a sound file specified, the corresponding Four Winds sound event is played, instead, unless a customized sound file is specified in the Preferences dialog box): 
  • Mjscore.wav – used when a deal ends in one of the players going out.
  • Chow.wav or player-specific effects Chow1.wav through Chow4.wav – used when a player claims a Chow. If Chow.wav is found, the same sound effect is used for all four players.
  • Pung.wav or player-specific effects Pung1.wav through Pung4.wav – used when a player claims a Pung. If Pung.wav is found, the same sound effect is used for all four players.
  • Kong.wav or player-specific effects Kong1.wav through Kong4.wav – used when a player claims or declares a Kong. If Kong.wav is found, the same sound effect is used for all four players.
  • Ready.wav or player-specific effects Ready1.wav through Ready4.wav – used when a player declares a ready hand. If Ready.wav is found, the same sound effect is used for all four players.
  • Out.wav or player-specific effects Out1.wav through Out4.wav – used when a player declares out on a self-drawn winning tile. If Out.wav is found, the same sound effect is used for all four players.
  • DOut.wav or player-specific effects DOut1.wav through DOut4.wav – used when a player declares out on a discard. If DOut.wav is found, the same sound effect is used for all four players.
  • Flower.wav – used when a player receives a Flower or Season.
  • Dora.wav – used when a player receives a Dora tile.
  • Pao.wav – used when a player melds a set that makes his hand a probable high-scoring hand, thus warning other players that making an irresponsible discard results in a heavy penalty (the discarder must pay the winner's points for all losers).
  • Click.wav – used when a tile is placed on the game board or in the rack.
  • Undo.wav – used when the user undoes his last discard.
  • Draw.wav – used when a deal ends in a draw (no one wins).
  • FOut.wav – used when a player declares faulty out.
  • [MyTheme]1.mid – a midi file used when the complete game session is finished. If DirectX is installed, the following sound formats are supported in addition to the MIDI format: .aif, .aiff, .au, .mp3, .snd, .wav.
  • [MyTheme]2.mid – a midi file used for background music.  If DirectX is installed, the following sound formats are supported in addition to the MIDI format: .aif, .aiff, .au, .mp3, .snd, .wav.
• Optional cursor files, named as follows (if any of these is missing, the corresponding element of Four Winds theme is used for that element, instead):
  • Claim.cur – used when a player can claim a tile and he places the the cursor over a discard slot.
  • Discard.cur – used when a player can discard a tile.
  • Accel.cur – used when it is another player's turn (indicates that you can accelerate the game by clicking the game board).
  • Wait.ani (an animated cursor) or Wait1.cur through Wait6.cur – used for animating the cursor while it is player's own turn (the animated bird in the default Four Winds theme).
  • Dice.ani (an animated cursor) or Dice1.cur through Dice48.cur – used for animating the dice.

Contents of the .4wg configuration file

The theme configuration file [MyTheme].4wg is a standard ANSI text file that contains the following settings:

The meanings of the settings are explained in detail in the documentation that comes with Four Winds Theme Editor (which also lets you specify all these settings visually so that you do not need to type the values in the configuration file).

If you have created a complete user-defined theme (preferably including all the needed cursors and sounds) and want to share it with other users, please contact info@4windsmj.com for details.

Related topics:
Changing a theme
Using custom tiles
Customizing the sound effects and background music