Skip to main content

​
StepMania Documentation

The ultimate rhythm game engine for Windows, Linux, and macOS. Build custom themes, create challenging charts, and experience the most advanced open-source rhythm game platform.

Get startedBuild from source

​
Quick start

Get up and running with StepMania in minutes

1

Download StepMania

Download the latest release for your platform from the official website or build from source.
Download the Windows installer and run it. You’ll need the Microsoft Visual C++ Redistributable installed.
2

Launch and configure

Start StepMania and configure your input preferences. Navigate to Options → Config Key/Joy Mappings to set up your controller or keyboard.
For the best experience, use a dance pad or game controller. Keyboard is supported but may be limiting for advanced charts.
3

Add songs

Place your song packs in the Songs/ directory within your StepMania installation. StepMania supports multiple simfile formats including .sm, .ssc, .dwi, and .bms.Songs should be organized as:
Songs/
  GroupName/
    SongName/
      song.mp3
      song.sm
      banner.png
4

Start playing

Return to the main menu, select your preferred game mode, and choose a song. Hit the arrows in time with the music!
Start with easier difficulties (Beginner or Easy) to learn the timing system, then progress to harder charts.

​
Explore by topic

Everything you need to master StepMania

Game modes

Explore different play styles from regular play to nonstop courses and battle mode

Theming

Create custom themes with Lua scripting, metrics, and BGAnimations

Simfiles

Learn about chart formats, timing, and creating your own note patterns

Build from source

Compile StepMania for Windows, macOS, or Linux using CMake

Lua API

Access the complete Lua scripting API for themes and customization

Command line

Use command-line arguments for automation and advanced configuration

​
Key features

What makes StepMania powerful

​
Cross-platform

Native support for Windows, Linux, and macOS with consistent gameplay across all platforms

​
Lua scripting

Powerful Lua API for creating custom themes, screens, and gameplay modifications

​
Multiple formats

Support for .sm, .ssc, .dwi, .bms, and .ksf simfile formats with comprehensive timing options

​
Advanced modifiers

Extensive gameplay modifiers including speed changes, note transformations, and visual effects

​
Ready to start?

Download StepMania today and join thousands of players worldwide enjoying the ultimate rhythm game experience.

Installation guideView on GitHub

Build docs developers (and LLMs) love

Get started for freeTalk to us