Creating a Theme



All themes must reside in the Themes folder below the StepMania program directory. Inside a theme folder, you will all or only a few of the items below:

  • Themes\<ThemeName>\BGAnimations\
  • Themes\<ThemeName>\Fonts\
  • Themes\<ThemeName>\Graphics\
  • Themes\<ThemeName>\Numbers\ (SM 3.9)
  • Themes\<ThemeName>\Scripts\ (SM 4-5)
  • Themes\<ThemeName>\Sounds\
  • Themes\<ThemeName>\metrics.ini

The 5 possible folders in a theme hold "theme elements". A theme element is simply a little piece of the theme that can be changed. Each of the 5 folders contains different types of information as explained below:


BGAnimations: This folder contains BGAnimation elements for the different screens. Since all backgrounds for all the menus in the game are generated using BGAnimations, any screen in the game can have an animating background. Also, BGAnimations can contain movie layers. For more information about BGAnimations, see the section "BGAnimations Format" in this document.


Fonts: This folder contains graphics and font width data used by the font system. Font graphics and width files are generated using the program "Bitmap Font Builder", which is available at their site. To export a font for use in StepMania:

  1. In Bitmap Font Builder, choose Character Set->Full ASCII. StepMania can only load 16x16 character sheets.
  2. In Bitmap Font Builder, click File->Save 32bit TGA. Save the file some place that is easy to access.
  3. Open Photoshop and load the TGA file. Click the chanel "Alpha 1", then load this channel as a selection.
  4. Click back to the Layers tab and create a new layer.
  5. Choose Edit->Fill, and fill the selection with white.
  6. Delete the layer named "Background". You should now see a mostly transparent background with faint hints of white text.
  7. Click File->Save For Web. Choose the Format "PNG-24" and Save.
  8. Rename the PNG file you just saved to "<YourFontName> 16x16.png". (the "16x16" means that the graphic contains 16 # 16 frames worth of characters.
  9. Back in Bitmap Font Builder, click File->Save Font Widths (INI Format). Save this in the same directory where you saved the PNG. Rename the exported INI file to "<YourFontName> 16x16.ini" where the first part of the file name matches the PNG you exported.
  10. Done! The PNG and the INI file are your new font. Move them into your theme's Fonts folder.

StepMania will also look for the following optional lines in a font INI file:

  • CapitalsOnly=<0|1>: If 1, then StepMania will use the capital letter frames in place of the lower case letter frames. If not specified, StepMania will use 0 for this value.
  • DrawExtraPixelsLeft=<0..32>: If letters of your font are being chopped off on the left size, try increasing this value. If not specified, StepMania will use 0 for this value.
  • DrawExtraPixelsRight=<0..32>: If letters of your font are being chopped off on the right size, try increasing this value. If not specified, StepMania will use 0 for this value.
  • AddToAllWidths=<0..32>: If specified, this value will be added to the width of every character in the font. Increase this value if the width of all characters changes uniformly; for example, if you add a border to each character.
  • AdvanceExtraPixels=<0..32>: The value in this line determines the amount of space to advance between each character. This is usually small, as most fonts include spacing between characters in the body of the character. Increase this value to increase character spacing in your font. If not specified, StepMania will use 1 for this value.
  • ScaleAllWidthsBy=<0.0...2.0>: The width of every character in the font be multipled by this value. If not specified, StepMania will use 1 for this value.
  • LineSpacing=<0..64>: This controls the spacing in pixels between lines of text. This value is only used in text items that have multiple lines. If not specified, StepMania will use the height of the frames in your texture (which is 32 pixels for 512x512 graphics).
  • Top=<0..63>: This indicates the top of a typical capital letter, from the top of the frame. If not specified, this will be derived from LineSpacing.
  • Baseline=<0..63>: This indicates the baseline of the font, from the top of the frame. If not specified, the baseline is derived from LineSpacing.


Graphics: This folder contains graphics used in all of the screens. These graphics are the meat and potatoes of a theme. These graphics can be of any dimension. For example, your theme could have a "title menu logo dance.png" graphic that is 640x480 - which would take up the whole screen!

Numbers (For 3.9 only)

Numbers: This folder contains graphics used to render numbers. Every graphic in this folder must be 5 frames by 3 frames (5x3) and follow the standard layout (see the Numbers graphics in the theme named "default" for examples).


Sounds: This folder contains sounds. Sounds may be in OGG, MP3, or WAV format.


metrics.ini:A metric is simply values that can alter the appearance of the game. metrics.ini is a large list of values that will allow you to alter things like the position of elements in the menus, and the order of menu screens.

There is no documentation or explaination of these values other than the value name. Because the theme "default" implements all possible theme elements and metrics, the metrics file "Themes\default\metrics.ini" contains a complete list of all possible metrics.

DO NOT EDIT the file "Themes\default\metrics.ini". Instead, create a blank file "metrics.ini" in your theme folder, and override only those values you want to customize for your theme using default's metrics.ini to see what values are possible.

When StepMania looks to load a theme element from one of these folders, it will first look in the folder of the currently selected theme. If the element is not found in this folder, StepMania then look for the theme element in the theme folder called "default". The theme "default" is a base theme and guaranteed that a theme is usable even if it is missing elements.

This "fallback" system has other advantages too. User-created themes can override as many or as few theme elements as the author pleases. For example, you could create a theme called "MySuperTheme" which does nothing more than override the title menu logo. Here's how you would create this theme:

  • Create a new folder in "Themes" called "MySuperTheme"
  • Open the MyStepMania folder. Create a folder inside called "Graphics".
  • Copy the file "Themes\default\Graphics\title menu logo dance.png" into your Graphics folder "Themes\MySuperTheme\Graphics".
  • Edit your new title menu graphic to be whatever you want.
  • Start StepMania, go to Appearance Options, and change your theme to "MySuperTheme".

Getting Started

The least complicated changes are sound and graphic replacements; you find the file you want to change, and then add a new file with the same name to your theme. Fonts are slightly trickier, because they require additional configuration and the use of the BFB program. BGAnimations require you to know some metrics and commands, but they are much simpler than working with metrics.ini, which has the most complex and gameplay-related material.

Thanks to (donated web hosting)