USC Multiplayer Protocol Documentation

The USC Multiplayer server uses JSON packets with topics.

Each packet consists of a serialized JSON object with a topic field. This topic field will direct the packet to the correct subscriber.

This documentation lists defined topics for both the server and the client as well as their fields and other information.

To see how to JSON send packets over the network see tcp_protocol.md

Table of Contents

Client.proto

Top

These are the packets the server sends to the client

game.scoreboard

FieldTypeLabelDescription
users Types.gamescore repeated

game.started

Sent to users in a room when the game has started

FieldTypeLabelDescription
hard bool

True if the user has excessive rate enabled

mirror bool

True if the user has mirror enabled

game.sync.start

Tells the client to start the song (all players are synced)

FieldTypeLabelDescription
users Types.user repeated

Information about the players in the match

room.update

Sent to users when a room has been changed

FieldTypeLabelDescription
users Types.user repeated

List of users in the room

do_rotate bool

Whether the room rotates host or not

start_soon bool

Set to true if the game is about to start

song string

Folder name of the current song
Set to null if no song

diff uint32

Index of the current selected difficulty
Set to null if no song

level uint32

Level of the current selected difficulty
Set to null if no song

hash string

Selective hash of the audio file (0x8000 bytes) *Deprecated*

audio_hash string

Selective hash of the audio file (0x8000 bytes)

chart_hash string

Normalized hash of chart file (see USC for more details)

host string

The UUID of the current host
If the room is currently in game, this field is not present

hard_mode bool

Whether the current user has excessive rate enabled or not

server.error

Sent on a fatal error. The server will most likely disconnect the user after this

FieldTypeLabelDescription
error string

Description of the error

server.info

List of the current lobby rooms

Sent when lobbies change

FieldTypeLabelDescription
version string

Version of the server

userid string

UUID of the current user

refresh_rate int32

The refresh rate of the scoreboard (how often to send scores)

server.room.badpassword

Sent when the wrong password was used for a room

server.room.joined

Sent in response to server.room.join

FieldTypeLabelDescription
room Types.room

The room that has been joined

server.rooms

FieldTypeLabelDescription
rooms Types.room repeated

List of lobbies on the server

Types.proto

Top

These are types used by packets

Note: These are not message topics!

Types.gamescore

FieldTypeLabelDescription
id string

The UUID of the user this score belongs to

name string

The display name of the user this score belongs to

score int32

The value of the score

Types.room

FieldTypeLabelDescription
id string

The UUID of the room

current int32

Number of users currently in the room

max int32

Max number of users for the room

name string

Name of the room

ingame bool

Whether the room is current in game

password bool

Set if the room has a password

join_token string

Token that can be used to join a room without a password

Types.user

FieldTypeLabelDescription
id string

The UUID of this user

name string

The display name of the user

ready bool

Whether the user is ready or not

missing_map bool

Whether the user is missing the song or not

level int32

User's selected level for the current song
0 = no selected level

score int32

User's last final score
If no score, this field will not be present

combo int32

User's last max combo
If no score, this field will not be present

clear int32

User's clear status
0: Exited
1: Failed
2: Clear
3: Hard Clear
4: Full Combo
5: Perfect
If no score, this field will not be present

extra_data string

Exists if the user has provided any extra data.