Etterna: a keyboard-first rhythm game that grew out of StepMania 5

A StepMania 5 fork that stopped looking like its parent

Etterna began as a fork of StepMania 5 at version 5.0.12 and has since evolved into its own game. The repository description calls it an advanced cross-platform rhythm game similar to Dance Dance Revolution, and the README is explicit that the focus is keyboard players. Over the fork's lifetime the project added in-game multiplayer and the Etterna Online scoreboard, hosted at etternaonline.com, and the README states the community has grown to more than 4,000 players. That history explains the shape of the code today. A fork that only added charts would still look like StepMania, but a fork that added a networked match mode and a leaderboard service has to own a server component as well as a game client. The licence notice says plainly that Etterna uses the MIT License because it is a derivative of StepMania 5, which sets the legal floor for everything that follows.

Where the keyboard-first work lives in the repository tree

The top-level layout shows what a rhythm engine needs to carry. Data/ holds the built-in game data, Songs/ the music, Themes/ the visual sets, NoteSkins/ the note graphics, Scripts/ the Lua scripting layer, and Announcers/, BGAnimations/, BackgroundEffects/ and BackgroundTransitions/ the presentation pieces that a rhythm game fires in time with a chart. src/ holds the C++ engine, CMakeLists.txt and CMake/ drive the build, extern/ holds third-party code, and Docs/ carries the developer documentation. GameTools/ and config/ sit alongside tooling and settings, with format.sh and format-check.sh at the root and a .clang-format file that defines the style. The project also keeps STEPMANIA.TXT and CHANGELOG.md at the root, which is where the ancestry remains visible. None of this layout is documented in prose beyond the file names, so it is best read as a map rather than as a specification.

Getting a build from the releases page, and the macOS quarantine step

Installation starts on the GitHub Releases page, where you download the file for your operating system. On Windows you run the installer and you are done. On Linux the README says there should be no extra steps, and that if the build does not work you should follow the build instructions to install the missing dependencies. macOS needs one extra step, because the binary is not signed and Gatekeeper quarantines the download. The fix is a single attribute command run in the folder where you downloaded the disk image:

xattr -d com.apple.quarantine ./Etterna*.dmg

After that, mount the disk image, copy the Etterna folder to a location of your choice and run the executable. The wildcard in the command is deliberate: it matches the Etterna disk image whatever version number the file carries. Running it from the downloads folder is what the README suggests, since the attribute is set on the file you actually downloaded.

Building from source is delegated to Docs/Building.md

The README does not contain build commands. It points at Building.md inside Docs/ and says that, because Etterna is cross-platform, you should be able to build on any recent version of Windows, macOS or Linux. That single line is the whole build section, which tells you something about where the project's effort goes: the CI workflow badge and the Coverity scan badge at the top of the README suggest that continuous integration and static analysis carry the verification load that a long README would otherwise. The same delegation applies to contributions. Docs/Contributing.md holds the task list, and the README asks would-be contributors to read the building document first. Contributors to the multiplayer side are pointed at a separate repository, NodeMultiEtt, which hosts the nodejs server and its documentation, and the README is explicit that you still need the client built and running for that work to matter.

Two licences inside one binary: MIT code and GPL audio libraries

The licence story is the part of this project most likely to surprise an engineer who assumes a single MIT file settles everything. The game itself is MIT, which the README says permits modifying, selling, distributing and sublicensing, with two requests attached: include a reference to the GitHub repository in derivatives, and do not hold the authors liable when something breaks. That is the MIT terms as required by being a derivative of StepMania 5. But Etterna also uses the MAD library and FFMPEG codecs, and the README states that those libraries, when built, use the GPL license. So a shipped build carries GPL licensed components alongside MIT licensed game code. This is not legal advice, and the README does not walk through the distribution obligations, but the practical point stands: anyone packaging Etterna into a product has to account for the GPL parts separately from the MIT parts, and the README does not explain how.

The scoreboard, the Discord servers and where bugs actually go

Etterna splits its community surfaces into distinct pieces. Etterna Online at etternaonline.com is the online scoreboard. The Discord link in the README opens the Etterna Community server, while a second invite goes to the Etterna Dev Group, which the README describes as the development Discord for people who want to know where they could start contributing. News about releases runs through those channels rather than a mailing list. For faults, the project uses GitHub's issue tracker and asks people to open an issue from the Issues tab and use the Bug report template, which is the shape you would want for a game where a crash report and a chart file mean very different things to a maintainer. The README credits the original StepMania developers and contributors, plus Jet Brains for free licenses and Coverity for free scans.

Doxygen and LuaDoc coverage that the project admits is thin

Etterna publishes two kinds of developer documentation. The C++ side runs through Doxygen and the Lua side through LuaDoc, and both are hosted at docs.etterna.dev. The README is unusually candid about their state, saying both still need a lot of work before they have decent coverage, and it explains the publishing rule that any commit to the develop branch immediately updates the sites. Two things follow from that. First, the hosted docs describe the develop branch rather than the tagged release you are running, so reading them while debugging a 0.75.1 build can send you into code that has not shipped. Second, the documentation is a genuine open gap that the project itself flags, which makes the API surface something you have to read from the source in src/ rather than from a reference manual. The version history is easier to trace: v0.75.0 was tagged as the Etterna 10th Anniversary release and v0.75.1 followed as a hotfix.

Where Etterna is the wrong choice

Two boundaries make this the wrong tool for some people. If you want the upstream StepMania 5 code, Etterna is the wrong fork, because the whole point of this one is that it diverged into a game with its own multiplayer and its own online services. If you are on macOS and want a signed, double-clickable application, this project will not give you one; the README is explicit that the binary is unsigned and that you have to remove the quarantine attribute yourself. A third constraint is quieter. The README says the Doxygen and LuaDoc coverage still needs a lot of work, so for anyone embedding the engine or the Lua scripting layer in their own work, the learning curve is reading source code rather than reading a manual. The scoreboard side has a similar property: Etterna Online is one service run by this project, and the server for in-game multiplayer lives in a separate repository, NodeMultiEtt.

Editorial conclusion

Etterna fits players who want arrow-key rhythm play with an active scoreboard and match mode, and developers who want to work on a game that still takes community pull requests. It does not fit someone who wants the upstream StepMania 5 codebase, a signed macOS binary, or a documented build with in-page instructions. Before committing, read Docs/Building.md, check that the release asset matches your platform, and remember that any binary you download ships GPL licensed MAD and FFMPEG components alongside the MIT licensed game code.

Frequently asked questions

Official sources

1. etternagame/etterna on GitHub
2. License: MIT
3. Project website
4. README
5. Releases