Qualifiers Stage Automaton

Overview

AutoRefQualifiersStage handles the automated refereeing logic for Qualifier Lobbies. It manages a linear flow of maps with no picks/bans, cycling through the entire map pool sequentially. Namespace: ss.Internal.Management.Server.AutoRef

Class Definition

public partial class AutoRefQualifiersStage : IAutoRef

State Machine

State Enum

public enum MatchState
{
    Idle,
    WaitingForStart,
    Playing,
    MatchFinished,
    MatchOnHold
}

State Descriptions

State	Description
`Idle`	Cooldown/loading state between maps
`WaitingForStart`	Map loaded, timer active, waiting for players to ready up
`Playing`	Map in progress, waiting for completion
`MatchFinished`	All maps in the pool have been played
`MatchOnHold`	Panic mode - automation paused

State Transition Diagram

Key Methods

StartAsync()

Initializes the qualifier room and connects to Bancho.

public async Task StartAsync()

Behavior:

Loads QualifierRoom from database by matchId
Validates referee credentials
Loads round configuration and map pool
Retrieves list of players assigned to this room
Connects to Bancho IRC
Creates tournament lobby

StopAsync()

Saves match state and closes the lobby.

public async Task StopAsync()

Persisted Data:

MpLinkId: osu! match ID for score tracking

HandleIrcMessage()

Core event loop that drives the state machine.

internal async Task HandleIrcMessage(IIrcMessage msg)

Responsibilities:

Parse IRC messages from BanchoBot
Detect lobby creation and extract MP link ID
Handle !panic emergency protocol
Detect match completion
Process admin commands (prefix: >)
Drive state transitions via TryStateChange()

ExecuteAdminCommand()

Processes referee commands.

private async Task ExecuteAdminCommand(string sender, string[] args)

Available Commands:

Command	Syntax	Description
`>finish`	`>finish`	Closes the lobby
`>invite`	`>invite`	Invites all assigned players to the lobby
`>setmap`	`>setmap [slot]`	Manually sets a map (requires Idle state)
`>start`	`>start`	Engages automation and starts qualifier flow
`>stop`	`>stop`	Stops automation

StartQualifiersFlow()

Initializes the qualifier lifecycle.

private async Task StartQualifiersFlow()

Behavior:

Resets currentMapIndex to 0
Sets state to Idle
Calls PrepareNextQualifierMap() to load first map

PrepareNextQualifierMap()

Iterates to the next map in the pool and prepares it for play.

private async Task PrepareNextQualifierMap()

Logic:

if (currentMapIndex >= currentMatch.Round.MapPool.Count)
{
    await SendMessageBothWays(Strings.QualifiersOver);
    currentState = MatchState.MatchFinished;
    return;
}

var beatmap = currentMatch.Round.MapPool[currentMapIndex];
await SendMessageBothWays($"!mp map {beatmap.BeatmapID}");
await SendMessageBothWays($"!mp mods {beatmap.Slot[..2]} NF");
await SendMessageBothWays("!mp timer 120");

currentState = MatchState.WaitingForStart;

Flow:

Checks if all maps have been played
If finished, transitions to MatchFinished state
Otherwise, loads next map by BeatmapID
Applies mods based on slot prefix (e.g., NM, HD, HR)
Adds NF (No Fail) mod
Starts 120-second ready timer
Transitions to WaitingForStart

TryStateChange()

The state machine brain - evaluates Bancho messages and transitions states.

private async Task TryStateChange(string banchoMsg)

State Logic:

Idle State

case MatchState.Idle:
    return; // No transitions from idle except via admin commands

WaitingForStart State

case MatchState.WaitingForStart:
{
    if (banchoMsg.Contains("All players are ready") || 
        banchoMsg.Contains("Countdown finished"))
    {
        await SendMessageBothWays("!mp start 10");
        currentState = MatchState.Playing;
    }
    break;
}

Playing State

case MatchState.Playing:
{
    if (banchoMsg.Contains("The match has finished"))
    {
        currentMapIndex++;
        currentState = MatchState.Idle;
        
        _ = Task.Run(async () =>
        {
            await Task.Delay(10000); // 10-second cooldown
            await PrepareNextQualifierMap();
        });
    }
    break;
}

Map Pool Iteration

The qualifier flow is fully linear:

Start: >start command sets currentMapIndex = 0
Load Map: PrepareNextQualifierMap() loads map at current index
Play Map: Players ready up, timer expires, or all ready → map starts
Complete Map: Match finishes → increment currentMapIndex
Cooldown: 10-second delay before loading next map
Repeat: Go to step 2 until all maps are played
Finish: When currentMapIndex >= MapPool.Count, transitions to MatchFinished

Timer Management

Qualifiers use different timers than elimination matches:

Event	Timer Duration	Command
Map ready phase	120 seconds	`!mp timer 120`
Match start delay	10 seconds	`!mp start 10`
Map cooldown	10 seconds	`Task.Delay(10000)`
Panic recovery	10 seconds	`!mp timer 10`

Panic Protocol

Identical to elimination matches: Trigger: Anyone types !panic

if (content.Contains("!panic"))
{
    currentState = MatchState.MatchOnHold;
    await SendMessageBothWays("!mp aborttimer");
    await SendMessageBothWays($"<@&{REFEREE_ROLE_ID}> PANIC by {senderNick}");
}

Recovery: Referee types >panic_over

if (content.Contains(">panic_over") && senderNick == referee)
{
    await SendMessageBothWays(Strings.BackToAuto);
    currentState = MatchState.WaitingForStart;
    await SendMessageBothWays("!mp timer 10");
}

Player Invitations

The >invite command iterates through all players assigned to the room:

case "invite":
    foreach (var osuId in usersInRoom)
    {
        await SendMessageBothWays($"!mp invite #{osuId}");
        await Task.Delay(500);
    }
    break;

Players List:

Loaded from database during StartAsync()
Query: Players.Where(p => p.QualifierRoomId == matchId).Select(p => p.User.OsuID)
Stored in List<int> usersInRoom

Lobby Settings

Qualifiers use Head-to-Head mode:

private async Task InitializeLobbySettings()
{
    // TeamMode=0 (Head2Head), WinCondition=3 (ScoreV2), Slots=16
    await client.SendPrivateMessageAsync(lobbyChannelName, "!mp set 0 3 16");
    await client.SendPrivateMessageAsync(lobbyChannelName, 
        "!mp invite " + currentMatch.Referee.DisplayName.Replace(' ', '_'));
    await SendMessageBothWays($"Join this match via an IRC app with this command: \n- `/join {lobbyChannelName}`");
}

Settings:

Team Mode: 0 (Head-to-Head)
Win Condition: 3 (ScoreV2)
Slots: 16 (allows multiple players simultaneously)

Cooldown System

After each map, a 10-second cooldown prevents immediate transitions:

_ = Task.Run(async () =>
{
    await Task.Delay(10000);
    await PrepareNextQualifierMap();
});

Purpose:

Gives players time to review scores
Prevents spamming Bancho with rapid map changes
Allows for brief discussions between maps

Internal Fields

internal Models.QualifierRoom? currentMatch;
private readonly string matchId;
private readonly string refDisplayName;
internal IBanchoClient? client;
internal string? lobbyChannelName;
internal bool joined;
private bool stoppedPreviously;
private int currentMapIndex;
internal MatchState currentState;
internal MatchState previousState;
private int mpLinkId;
private List<int> usersInRoom = new();
private TaskCompletionSource<string>? chatResponseTcs;
private readonly Action<string, string> msgCallback;

Differences from Elimination Automaton

Feature	Qualifiers	Elimination
Team Mode	Head-to-Head (0)	TeamVs (2)
Map Selection	Linear (full pool)	Pick/Ban phases
Player Count	Multiple (1-16)	Two teams
State Complexity	Simple (4 states)	Complex (13 states)
Timeout System	None	Per-team tactical timeouts
Win Condition	Complete all maps	Best-of-N
Map Order	Sequential	Player-chosen
Timer Duration	120 seconds	90 seconds

Database Models

AutoRef System

Overview

Class Definition

State Machine

State Enum

State Descriptions

State Transition Diagram

Key Methods

StartAsync()

StopAsync()

HandleIrcMessage()

ExecuteAdminCommand()

StartQualifiersFlow()

PrepareNextQualifierMap()

TryStateChange()

Idle State

WaitingForStart State

Playing State

Map Pool Iteration

Timer Management

Panic Protocol

Player Invitations

Lobby Settings

Cooldown System

Internal Fields

Differences from Elimination Automaton

Build docs developers (and LLMs) love

Database Models

AutoRef System

​Overview

​Class Definition

​State Machine

​State Enum

​State Descriptions

​State Transition Diagram

​Key Methods

​StartAsync()

​StopAsync()

​HandleIrcMessage()

​ExecuteAdminCommand()

​StartQualifiersFlow()

​PrepareNextQualifierMap()

​TryStateChange()

​Idle State

​WaitingForStart State

​Playing State

​Map Pool Iteration

​Timer Management

​Panic Protocol

​Player Invitations

​Lobby Settings

​Cooldown System

​Internal Fields

​Differences from Elimination Automaton

​Related Documentation

Build docs developers (and LLMs) love

Overview

Class Definition

State Machine

State Enum

State Descriptions

State Transition Diagram

Key Methods

StartAsync()

StopAsync()

HandleIrcMessage()

ExecuteAdminCommand()

StartQualifiersFlow()

PrepareNextQualifierMap()

TryStateChange()

Idle State

WaitingForStart State

Playing State

Map Pool Iteration

Timer Management

Panic Protocol

Player Invitations

Lobby Settings

Cooldown System

Internal Fields

Differences from Elimination Automaton

Related Documentation