ppy/osu: Building and Playing the Lazer Client in C#

What ppy/osu is, and who the repository is actually for

ppy/osu is the source for the osu! game client released under the codename lazer. The README calls it "the future and final iteration" of the client and says the project "marks the beginning of an open era." It is a rhythm game, free to play, and the repository holds the client, not the website that serves beatmaps and scores. The homepage points at osu.ppy.sh for that side of the service.

The people who get the most out of this repository are not ordinary players. Players are told to install from a release alongside their existing stable client. The README frames the source tree as a place for two other groups: developers who want to build a custom ruleset, which the README describes as user-created gameplay variations that reuse the beatmap library, game engine and general UX, and contributors who want to change the client itself. The Templates directory is named as the starting point for rulesets, and the repository ships separate projects for the four built-in rulesets: osu, taiko, catch and mania, each with its own test project.

That split matters when you judge the project. The README is written for someone who will open a solution file, not for someone who just wants to click circles. If you are the second kind of person, the install section below is the only part you need.

How the C# solution is split, and what that means for a build

The top-level layout separates the engine from the game modes. osu.Game holds the shared client, osu.Desktop, osu.Android and osu.iOS hold the platform heads, and each ruleset has its own project plus test projects for desktop, Android and iOS. There is also osu.Game.Tournament and osu.Game.Benchmarks, so a tournament viewer and a benchmarking harness live in the same tree.

The README is explicit that you should not open the main osu.sln. Instead it tells you to load one of the platform-specific solution filters: osu.Desktop.slnf, osu.Android.slnf or osu.iOS.slnf. The stated reason is that a filter reduces dependencies and hides platforms you do not care about. This is a real constraint, not a style preference. A filtered solution changes which projects the IDE restores and builds, and the README says mobile builds may need sudo dotnet workload restore first to install the Android and iOS tooling.

Two helper scripts sit at the root for cross-repository work: UseLocalFramework and UseLocalResources, in .ps1 and .sh form. The README says they assume the relevant repositories are checked out in adjacent directories, with osu, osu-framework and osu-resources as siblings. If your checkout layout differs, those scripts will not find what they expect. The README does not describe how to undo the switch back to packaged dependencies.

Installing and running ppy/osu from the command line

If you only want to play, the README points at prebuilt releases: install.exe for Windows 10+ x64, a zipped osu.app for macOS 12+ with separate Intel and Apple Silicon downloads, an AppImage for Linux x64, an APK for Android 5+, and a TestFlight link for iOS 13.4+. The iOS link is capped by Apple at 10,000 users, and the README says it fills quickly and is reset occasionally. It asks users not to ask about resets.

For a source build, the stated prerequisite is a desktop platform with the correct .NET SDK installed. The README recommends an IDE with code completion, naming Visual Studio, JetBrains Rider, or Visual Studio Code with the EditorConfig and C# Dev Kit plugins. Clone and enter the repository first:

git clone https://github.com/ppy/osu
cd osu

To build and launch the desktop client from the command line, the README gives a single command:

dotnet run --project osu.Desktop

If that fails, the README suggests restoring NuGet packages with dotnet restore. For anything that measures performance, it says to add -c Release, because the default Debug configuration adds overhead that is large when you are testing local framework modifications. Before committing, the README asks you to run dotnet format, or the Format code command in your editor. The expected result of the run command is a launched game window, not console output.

Rulesets are the extension point, and the README stops at the doorway

The custom ruleset path is the most interesting thing here for a developer, and it is also the thinnest part of the documentation. The README says osu! is designed to allow user-created gameplay variations, that Templates exists to get you started, and that examples of custom rulesets can be found in a discussions thread. That is the whole of the guidance. There is no walkthrough of the ruleset interface, no list of what a ruleset must implement, and no statement of which parts of the engine are stable enough to depend on.

The repository layout does hint at the contract. Each built-in ruleset has a matching test project, and the README pushes you toward the osu! (Tests) configuration when building new components. That tells you the intended workflow is test-driven against the existing ruleset implementations, reading them as reference rather than following a specification. It is workable, but it means a ruleset author is reverse-engineering an API that the README does not promise to keep still.

For a hobby ruleset this is fine. For anything you intend to ship, the absence of a documented stability guarantee is the thing to weigh before you start.

Where the README leaves you on your own

Three gaps stand out. First, rollback. The README does not document how to revert a client update or return to an earlier release. Release tags exist in the form 2026.920.0-lazer and 2026.918.0-tachyon, and the changelog lives on the osu! site, but nothing in the README describes downgrading.

Second, platform support outside the table. The README says that if your platform is unsupported or unlisted there is still a chance you can run the release or build it manually, which is a hope rather than a commitment. There is no list of what is known to work.

Third, the status section is candid but not a schedule. It says the project is under constant development and that the team does its best to keep things stable, while encouraging players to install a release alongside stable osu!. That is an admission that lazer is not yet the default experience. A team building on this codebase should read it as: the client works, the interfaces move, and the README will not tell you when.

What to compare ppy/osu against

The obvious alternative is osu!stable, the previous client that the README refers to by name and expects many players to keep installed. The difference is not feature parity, it is process. Stable is a closed binary that users install and update; lazer is an MIT-licensed C# tree that you can clone, build, modify and cross-test against osu-framework and osu-resources. If your goal is to play, stable asks nothing of you. If your goal is to change how the game behaves, stable offers no path at all.

A second comparison is the ruleset ecosystem itself. The README points to a directory of custom rulesets built by others, which means the realistic alternative to writing your own is adopting someone else's, with the same undocumented interface underneath. That does not make writing one wrong, but it does mean you are not the only person working without a specification.

Licence and maintenance cost

The repository is MIT licensed, and the licence file is named LICENCE at the top level. MIT permits reuse, modification and redistribution with the copyright notice and permission notice included. That is permissive enough for a ruleset or a fork. It says nothing about the osu! service, the beatmap catalogue or the osu.ppy.sh website, which are separate from this repository and are not covered by the licence file here. Treat the licence as covering the client code only.

On maintenance, the last push to master was on 2026-09-20, and the most recent release listed is 2026.920.0-lazer from the same day, with two tachyon releases in the preceding ten days. The README states the project is under constant development. The practical cost for a fork is that you are tracking a moving tree: the README's own advice to use solution filters exists because the full solution carries platforms you may not need, and the local framework scripts assume a sibling-directory layout you have to maintain. Budget for periodic rebases rather than a one-time checkout.

Editorial conclusion

Adopt ppy/osu if you want to build a custom ruleset, cross-test changes against osu-framework or osu-resources, or run the lazer client on a platform the release table does not cover. Do not adopt it if you want a stable release cadence with documented rollback and upgrade paths, because the README does not describe either. Before cloning, verify that the .NET SDK version required by global.json is installed and that you will load a platform-specific .slnf rather than the full solution.

Frequently asked questions

Official sources

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