Add way of realtime interfacing with multiplayer rooms from outside the game

[bdach]

Which is corporate-speak for "add something like what bancho does with multiplayer rooms back, but maybe with less IRC this time".

ppy/osu#16392 mentions that this would "live in web", but at this time I am unsure we want to mix web into this and also use a text-based interface again rather than an actual API. For one, there are reliability and performance concerns with web (ppy/osu-infrastructure#33). For another, spectator server will 99% have to be involved here anyway because some commands that are required interface with ephemeral memory-only state that only spectator server currently has access to.

The way mp channels via IRC work have made people very accustomed to interfacing with multiplayer in realtime via it exclusively. To the degree that while we have API endpoints for retrieving match events, they seem to be considered unsuitable for use because they're not realtime and require polling.

Scope of work

Retrieving events that occur in the match in real-time

Basically something like MultiplayerEventLogger but bolted to a web socket. Plus probably adding a few new event types to log (need to review bancho internals for what it's emitting).

Controlling a match in real-time

Basically !mp commands.

List of commands that bancho provides

• ✅ MAKE <name> / MAKEPRIVATE <name> - creates new lobby with given name
• 🚧 LOCK - prevents room and team switches
• 🚧 UNLOCK - allows room and team switches
• 🚧 SIZE <size> - sets number of slots in room
• ✅ SET <teammode> <scoremode> <size> - changes room properties
• 🚧 MOVE <username|id> <slot> - moves player to slot in room
• ✅ INVITE <username> - invites player to room
• ✅ HOST <username|id> - changes room host
• 🚧 CLEARHOST - clears host
• ❌ SETTINGS - displays room info
• 🚧 CLOSE - closes room
• ✅ START [<time>] - starts play after time seconds (0 if missing)
• 🚧 BAN <username|id> - bans user from room
• ✅ KICK <username|id> - kicks user from room
• 🚧 TEAM <username|id> <team> - changes user team
• ✅ MAP <beatmapId> [<rulesetId>] - changes current playlist item beatmap and ruleset
• ✅ MODS <mods...> - sets the given mods
• ✅ ABORT - aborts ongoing match
• ❌ CHECKTIMER - shows countdown state
• 🚧 TIMER - begins a countdown
• 🚧 ABORTTIMER - aborts all ongoing countdowns
• ✅ NAME - changes lobby name
• ✅ PASSWORD - changes lobby password
• 🚧 ADDREF - adds a referee to room
• 🚧 REMOVEREF - removes a referee from room
• ❌ LISTREFS - lists all referees in room

Legend:

• ✅ already a function spectator server performs elsewhere but just needs to be exposed somehow
• 🚧 needs further work (in most cases the further work is Add back support for slots in multiplayer rooms #405)
• ❌ probably something I wouldn't put in an MVP

I would probably want this to not be text-based and instead be a proper API instead. Whether that's via a web socket, or plain HTTP, not sure at this time.

Plan of attack

For an MVP I am probably just going to expose a new hub raw, copy-paste / hack in as much as needed to get a semblance of an idea of what I'm building, and then reassess what I got from that. I know there were reservations about just having a SignalR hub as API because of potential lock-in into a proprietary $MSFT protocol, but if people really want a web socket, then I'm not sure there's many better options that aren't going to require us to reinvent what $MSFT already invented. (Think protocol definition, authorisation, delivery guarantees / retry...)

The scope of an MVP as I see it would be:

• Allows room management functions to spec (not necessarily all, just enough to demonstrate viability)
• Exposes changes to room state / other room events to spec (scoped similarly to above)
• Proper access rights management and authorisation
• Called from non-C# (js via signalr is probably fine to start)

Prior work

• wyReferee
• osu-tclient
• bancho.js - client for bancho
• referee-helper - osufrlive referee frontend

[peppy]

FWIW I know I mentioned having apprehensions about the SignalR direction but I'm also fine with giving it a try, as per your proposal. Was only a weak concern (and the concern is mostly whether consumers will be okay with that direction. there's good library coverage on paper but I guess we'll see)

[bdach]

This is a working comment that I will be updating with progress of the PoC.

Goals

• Interoperability with non-C# (js used in this case)
• Exposes changes to room state / other room events
• Proper access rights management and authorisation
• Allows room management functions

Preview

Screen.Recording.2025-12-18.at.13.08.10.mov

Findings

• CORS is an issue when wanting to consume a SignalR hub directly from a browser, so we'll either have to
  • require every user of it to set up their own proxy server, or
  • specify some CORS policy to allow this (probably not, chances are this is very unsafe, but I haven't thought of it very much because CORS is confusing and I forgot a lot of what I knew about it)
• If we're going to go down the "separate SignalR hub for refereeing" route, one issue is that we're using a very custom version of messagepack (custom resolver, union workarounds) that is very intertwined with client. We'd have to either
  • clean it up somehow so that it can work for all hubs uiformly, or
  • introduce a split-brain situation wherein the only supported transport for the referee hub is json.

Code

• spectator server: https://github.com/ppy/osu-server-spectator/compare/master...bdach:osu-server-spectator:referee-hub-poc?expand=1
• js client: https://github.com/bdach/osu-referee-client-poc