Theme System Overview


Enmerating Themes

StepMania enumerates themes by looking for directories inside of the <StepMania Program Dir>/Themes/


  • Themes/default
  • Themes/MyCoolTheme
  • Themes/para
  • Themes/pump

Theme elements

Themes are composed of smaller pieces called "theme elements". Theme elements are grouped together in directories by their type. For example, all graphics theme elements are inside of a theme's Graphics directory and all sound theme elements are inside of a theme's Sounds directory.

Theme element naming

Theme elements typically have one of the following formats:

  • [screen_name] [piece_name] - e.g. "ScreenTitleMenu background"
  • [c++_class_name] [piece_name] - e.g. "ScoreKeeperNormal numbers"

The C++ game code loads theme resources using unique theme element names.

Theme layering

Common theme file types

Files in a theme

  • metrics.ini
  • BGAnimations/
  • Fonts/
  • Graphics/
  • Numbers/ (3.9 only)
  • Languages/
  • Other/
  • Scripts/ (not 3.9)
  • Sounds/


This file is the heart of a theme. It:

  • defines menu screens, including the flow of screens and which choices appear on each screen
  • contains animation data
  • defines many miscellaneous theme values, such as number format strings, window titles, or color values

The file uses the standard .ini file format. Values are divided into groups, such as "[ScreenTitleMenu]" or "[PercentageDisplay]". The group names typically correspond to specific screens (e.g. ScreenTitleMenu, ScreenGameplayNormal) or correspond to specific C++ classes in the game code (PercentageDisplay, UnlockManager).


This directory contains animations that are used for:

  • screen backgrounds
  • screen "overlays"
  • screen "in" transitions
  • screen "out" transitions

BGAnimation elements may have the following types:

  • directory
  • .lua file (only for 2008 SM4 CVS/4 alphas/5)
  • .xml file (4 betas only)
  • .ini file (3.9 only)
  • .redir

File naming conventions


Common Command Names

  • Init: called on each node only once as the node initialized and before any children are initialized
  • Begin: called when a screen is about to be shown and can be called more than once

Thanks to (donated web hosting)