StepMania: one engine, three build systems, and terms that change with your audio decoder

One engine for a living room and an arcade cabinet

StepMania is an advanced cross-platform rhythm game for home and arcade use, written in C++ and aimed at Windows, Linux and OS X. A single project serves two very different operators, and the tree shows how much of the work happens outside the compiler. Engine code sits in `src/`, `Program/` and `Utils/`. Beside it sit the folders an operator swaps at the venue: `Songs/`, `Courses/`, `NoteSkins/`, `Themes/` and `Characters/`. For a home player, dropping a song folder into that structure is the normal customisation path. For an arcade cabinet, those same folders are the venue configuration.

Two support channels are named, and only two: a website at https://www.stepmania.com/ and an IRC channel at irc.freenode.net/#stepmania-devs. No package index, no container image and no distribution-specific package name appears anywhere in the documentation, so the way you obtain a binary depends entirely on the platform you already run. The topics list is short as well, covering game, lua, rhythm-game and stepmania, which tells you the scripting surface is Lua and the domain is rhythm play rather than a general game framework.

Windows needs a redistributable installed before the first launch

A prebuilt Windows binary begins with a prerequisite rather than a download. Windows users are expected to have the `Microsoft Visual C++ x86 Redistributable for Visual Studio 2015` installed before the game runs, and anyone on an x64 machine needs the x64 redistributable as well. Windows 7 is the stated minimum supported version. Mac OS X users need 10.6.8 or higher. Linux users should receive everything they need from the package manager of their choice, which makes that platform the shortest route to a first run of the three.

Nothing beyond those prerequisites is documented. There is no described first-run wizard, no default song selection, no keybinding step and no account of what the game shows on launch. The `Manual/` and `Docs/` directories are where a new user has to learn the rest, and neither is explained in the README. A close reading turns up a version mismatch too: the prerequisite text is written against Visual Studio 2015 and an OS X floor of 10.6.8, while the newest listed builds belong to the 5.1 line. Those paragraphs were written in a different era from the code they gate.

Three build systems share one tree and only one path is documented

The README points compilers at CMake and sends them to the `Build` directory for details, and the top of the tree is consistent with that. `CMakeLists.txt`, `StepmaniaCore.cmake` and a `CMake/` directory form the modern path. Next to them sit `configure.ac`, `autogen.sh` and `Makefile.am` from autoconf, plus an `Xcode/` directory for macOS. Continuous integration is wired through `.travis.yml`, `.appveyor.yml` and a `.github/` directory, while `.gitmodules` alongside an `extern/` folder indicates that dependencies are pulled in as submodules rather than vendored into the tree.

These are file names at the top of the repository, not a command sequence:

CMakeLists.txt
StepmaniaCore.cmake
autogen.sh
configure.ac
Makefile.am

No command line is given for any of them. A builder following the autoconf route is working from files the README never explains, and so is anyone opening the Xcode project, because the documentation stops at CMake. Expect a failed first build on either path to leave you reading the script itself rather than a written procedure.

Content directories are the runtime interface, not build inputs

A block of directories at the top level sits beside the build files and carries the content the game draws and plays. `Data/` and `Scripts/` sit next to `BGAnimations/`, `BackgroundEffects/`, `BackgroundTransitions/` and `Announcers/`, a set of names for the layers a theme assembles while the game runs. `NoteSkins/` covers note appearance, `Themes/` the surrounding interface, `Characters/` the on-screen figures. Elsewhere `Docs/`, `Manual/` and `_assets/` hold documentation and raw material, while `Installer/`, `icons/`, `stepmania.nsi` and `stepmania.desktop` cover Windows packaging and the Linux desktop entry.

Keeping the installer script and the desktop entry inside the versioned tree means packaging changes travel with engine changes instead of sitting in a separate repository. What none of it documents is the file format for any one of those directories. The README says nothing about theme structure, note skin geometry, the layout of a course file or the scripting hooks a theme can use, so a content author is left with the folder names and the `Docs/` folder as the starting point.

Lua is the scripted extension point and its tutorial sits off the repository

Lua is one of the project's topics, `Scripts/` exists as a directory, and the README points Lua authors at two separate places. One is the API reference, which the README says can be found in the Docs folder, so half of that documentation travels inside the tree at `Docs/`. The other is a tutorial hosted at https://quietly-turning.github.io/Lua-For-SM5/, on a different domain from https://www.stepmania.com/.

A project whose scripts are Lua therefore splits its learning path between an in-tree reference and a page published elsewhere, and the tutorial is titled for SM5 while the default branch is named `5_1-new`. Whether those pages describe the branch you are compiling is something the README does not state, and the gap matters because a script written against one branch can fail on another with no compatibility note in the tree. Anyone building themes or custom behaviour needs to budget time for that check rather than assuming the tutorial matches the checkout.

The source is MIT, the bundled songs are CC-NC, the codecs are GPL

Licence reading is where this tree stops being simple: the source is under the MIT license, the songs bundled in `Songs/` are under CC-NC, and the MAD library together with FFmpeg codecs build as GPL when compiled with the engine code. Three different terms sit inside one repository, and which of them reach your binary depends on the audio decoder you compile in.

The engine's own conditions are permissive in a specific way. You may do what you like with the game, including selling products made with it. You may not sell the game with the included songs, you may not claim to have created the engine yourself or remove the credits, and you may not withhold source code for a build that differs from an official MP3-capable build. Linking back to http://www.stepmania.com/ is appreciated but not required. For anyone shipping something commercial, the split is straightforward in practice: bring your own songs, leave the bundled ones behind, and publish the source for any build you assembled yourself.

The branch says 5.1 while the newest listed build is a 2018 beta

The default branch is `5_1-new`, a name that describes the 5.1 line rather than a build you can download. The three newest listed versions are all beta builds: `v5.1.0a3` dated 2016-09-05, `v5.1.0-b1` dated 2018-01-25 and `v5.1.0-b2` dated 2018-07-24. No stable 5.1 build appears among them, and the a3, b1 and b2 suffixes say so plainly.

Work continues regardless. The last push was on 2026-08-22 and the repository is not archived, so commits are landing on a branch whose name refers to a line that never left beta. That combination is the detail a skim misses: cloning `5_1-new` hands you code that no numbered build matches, and the version in the branch name is a destination rather than a version you are running. A reproducible build therefore has to record an exact commit instead of the branch, and the project publishes no mapping from commits to builds.

The packaged binary and your own build are the two real choices

The comparison worth making here is between the two ways this engine reaches a machine, not against other projects. A prebuilt package saves you a toolchain and costs you the prerequisites above, which on Windows means the x86 redistributable for Visual Studio 2015 and a Windows 7 floor, and on OS X a 10.6.8 floor. Building from CMake costs a compiler, CMake itself and the submodule checkout that `.gitmodules` pulls in, and it hands you a binary whose contents you chose, including or excluding the codec libraries that carry the extra terms. An arcade operator faces the sharper version of that trade-off, since a cabinet cannot be repaired by a visitor who cannot download a package.

The wrong-tool cases are concrete rather than philosophical. Reach for something else if you need a numbered stable build, if your deployment target cannot satisfy the redistributable requirement, or if you need Lua API documentation matching your branch and find it neither in `Docs/` nor on the linked page. Before committing either way, check the platform minimums against your fleet, decide which audio decoder your distribution can carry, and open `Docs/` to see what the branch you cloned actually documents.

Editorial conclusion

Adopt StepMania when you need one rhythm engine to serve a home install and an arcade cabinet, and you are willing to compile it yourself through CMake or to track a package someone else built. Do not adopt it when a numbered stable build matters, because every listed version still carries a beta suffix, and the branch you clone moves past all of them. Verify three things before you commit a machine fleet: the platform minimums, which audio decoder your build compiles in, and whether the `Docs/` folder carries a Lua API reference matching the branch you cloned.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. stepmania/stepmania on GitHub