Skip to main content

​
Overview

Qualifier lobbies are fully automated rooms where players sequentially play through a fixed map pool. The AutoRef system handles room creation, map cycling, timer management, and scoring without human intervention. Unlike elimination matches, qualifiers follow a linear workflow with no picks or bans—just a straightforward progression through all maps in the pool.

​
How Qualifier Lobbies Work

​
Sequential Map Pool Playthrough

The automaton iterates through the entire map pool in order:
  1. Initialization: The referee engages auto mode after all players join
  2. Map Loading: Each map is loaded automatically with correct mods applied
  3. Ready Timer: 120-second countdown starts for players to ready up
  4. Play: Map starts when all players ready or countdown ends
  5. Cooldown: 10-second buffer between maps
  6. Repeat: Process continues until all maps are played

​
Player Management

Players are assigned to qualifier rooms via the database. The referee can:
  • Invite all assigned players with a single command
  • Monitor who joins via Discord thread logs
  • Manually add players if needed during the lobby

​
Room Settings

Qualifier rooms use Head-to-Head mode with ScoreV2 win condition and support up to 16 slots.
Settings are automatically configured on lobby creation: 
!mp set 0 3 16
  • TeamMode: 0 (Head-to-Head)
  • WinCondition: 3 (ScoreV2)
  • Slots: 16

​
State Machine Workflow

The qualifier automaton operates through a finite state machine to ensure safe, linear progression:

​
State Descriptions

StateDescription
IdleSystem waiting for processing or initialization. Safe state for manual commands.
WaitingForStartMap selected and loaded. Timer active. Waiting for players to ready up.
PlayingMap currently being played. System monitoring for “Match Finished” message.
MatchFinishedEntire pool has been played. Automaton complete.
MatchOnHoldPanic Mode. All automation paused. Awaiting manual intervention.

​
Administrative Commands

Commands are prefixed with > and can be issued via IRC or Discord by the assigned referee.
1

Invite Players

>invite
Iterates through all players assigned to the room in the database and sends !mp invite #<osuId> for each. Includes 500ms delay between invites to prevent rate limiting.
2

Start Automation

>start
Engages the automatic flow. Loads the first map from the pool and begins the state machine cycle. Can only be triggered when the automaton is in Idle state.
Ensure all players are in the lobby before starting automation. While players can join mid-lobby, it’s recommended to start with everyone present.
3

Stop Automation

>stop
Stops the automaton and returns manual control to the referee. The current state is preserved, allowing you to resume with >start where you left off.
4

Set Specific Map

>setmap [slot]
Manually sets a specific map from the qualifiers mappool with proper mods. Can only be used when the automaton is idle (not running).Example:
>setmap NM3
This loads the third NoMod map with mods NM NF and starts a 90-second timer.
5

Force Close

>finish
Forces the match to close immediately by sending !mp close to Bancho. Use this when the lobby needs to be terminated early.
Always use /endref in Discord after closing the lobby to save all changes to the database.

​
Safety and Logging

​
Discord Thread Integration

Every qualifier lobby gets its own Discord thread where:
  • All IRC messages are mirrored in real-time
  • Referee commands are logged
  • Player join/leave events are tracked
  • Match results are posted automatically

​
Manual IRC Access

When a match starts, the bot outputs an IRC join command in Discord: 
Join this match via an IRC app with this command:
- /join #mp_123456789
Referees can use this to manually join the lobby if:
  • The integrated server experiences connection issues
  • Manual intervention is needed during panic mode
  • They want to observe the lobby directly

​
Panic Protocol

See Panic Protocol for details on emergency override procedures.

​
Best Practices

1

Pre-Lobby Setup

  1. Verify all players are assigned in the database
  2. Confirm the map pool is correctly configured for the round
  3. Ensure the referee IRC credentials are linked via /linkirc
2

During Lobby

  1. Use >invite to bring all players into the room
  2. Wait for all players to confirm they’re ready in chat
  3. Engage automation with >start
  4. Monitor the Discord thread for any issues
  5. Use !panic if any disputes arise
3

Post-Lobby

  1. Wait for all maps to complete (state reaches MatchFinished)
  2. Verify scores were recorded in Discord thread
  3. Use /endref [match-id] in Discord to save and archive
  4. Import scores via /importscores with the MP link ID
The automaton includes a 10-second cooldown between maps to give players time to review scores and prepare for the next map.

​
Technical Details

​
Map Loading Process

For each map in the pool: 
// Load beatmap by ID
await SendMessageBothWays($"!mp map {beatmap.BeatmapID}");

// Apply mods (first 2 characters of slot + NF)
await SendMessageBothWays($"!mp mods {beatmap.Slot[..2]} NF");

// Start 120-second ready timer
await SendMessageBothWays("!mp timer 120");
Mods are automatically derived from the map slot (e.g., NM1 → NM NF, HD2 → HD NF).

​
State Transitions

The state machine is driven by BanchoBot messages:
  • “All players are ready” → Immediately starts match
  • “Countdown finished” → Starts match if players aren’t all ready
  • “The match has finished” → Increments map index and returns to Idle
Source reference: AutoRefQualifiersStage.cs:330-365

Build docs developers (and LLMs) love

Get started for freeTalk to us