General

neosu uses and extends the bancho protocol.
While no official documentation exists, here is a great reference: https://github.com/Lekuruu/bancho-documentation/wiki.

Whenever "convars" or "variables" are mentioned, this means in-game variables, accessible by pressing Shift+F1.
The full list of variables is available here. This should give you a nice idea of how customizable neosu is for server admins.

You do NOT have to implement any of the features below; neosu will gracefully fallback to "vanilla" behavior.

Identification

Client Detection

Detect neosu clients via header on c. endpoint:

x-mcosu-ver: <version>

User Agent

API endpoints use this user agent:

Mozilla/5.0 (compatible; neosu/<version info>; +https://neosu.net/)

Score Submission

Enable score submission with header:

x-mcosu-features: submit=1

OAuth

Enabled Domains

OAuth authentication is automatically enabled for:

• neosu.local
• neosu.net

Login Flow

Implements OAuth 2.0 Authorization Code flow with PKCE.

Step 1: Authorization

When clicking the "Log in with osu!" button, neosu will open the browser to:

GEThttps://neosu.net/connect/start?challenge={b64(sha256(verification_bytes))}

Step 2: Code Exchange

The server should then generate an URL-safe code, which will be forwarded to neosu by having the player click on a link:

neosu://login/neosu.net/{code}

Step 3: Token Request

neosu will make a request to get the refresh token:

GEThttps://neosu.net/connect/finish?code={code}&proof={b64(verification_bytes)}

Step 4: Session Login

We use the c. endpoint login packet, with:

• username: $oauth
• password: {refresh_token}

Server returns cho-token like for regular clients.

API Requests

In requests where the username and password hash are passed as parameters, username will be $token and password hash will be {cho-token}.

This includes score submission, where the username is passed and hashed in the score data.

Score submission

Submitted scores have an extra neosu-mods section, containing base64-encoded data representing neosu-specific mods.

Leaderboards

Score lines have an extra section after the "has_replay" flag, containing base64-encoded data representing neosu-specific mods.

Custom Endpoints

Map submission

POSThttps://osu.neosu.net/web/neosu-submit-map.php

URL Parameters

• h: {cho-token}
• hash: map md5

Form data

• osu_file: .osu file data

Server should verify that the map md5 matches the file data.

Server Packets

128 PROTECT_VARIABLES

Marks variables as PROTECTED. Score submission disabled when value differ from defaults.

• u16: nb_variables
• [string]: variable name

129 UNPROTECT_VARIABLES

Removes PROTECTED flag. Scores submit regardless of variable value.

• u16: nb_variables
• [string]: variable name

130 FORCE_VALUES

Forces variables to specific values.

• u16: nb_variables
• [string, string]: variable name, variable value

131 RESET_VALUES

Resets variables to client-side value.

• u16: nb_variables
• [string]: variable name

132 REQUEST_MAP

Requests an .osu file from the client. Used for unranked/unavailable maps.

• string: map md5

Client should send the .osu file to the neosu-submit-map endpoint.