Skip to main content

​
Overview

The Panic Protocol is a built-in fail-safe mechanism that allows human referees to instantly override automation in case of edge cases, disputes, technical issues, or any situation requiring manual intervention. Panic mode is a global interrupt that can be triggered by anyone in the lobby and immediately halts all automated processes.
Panic mode is the safety net that ensures tournaments comply with regulations requiring human oversight of automated systems.

​
What Triggers Panic Mode

Panic mode can be triggered in several scenarios:

​
Player-Initiated

  • Disputed scores: A player believes the score was calculated incorrectly
  • Technical issues: Lag, disconnections, or client crashes during a map
  • Rule violations: Suspicion of cheating or unfair play
  • Map issues: Wrong map loaded or incorrect mods applied

​
Referee-Initiated

  • System malfunction: The automaton behaves unexpectedly
  • Connection issues: IRC connection unstable or dropping messages
  • Match irregularities: Something doesn’t match the expected flow
  • Safety precaution: Proactive intervention to prevent issues

​
Automatic Triggers

While not explicitly automatic, panic should be used when:
  • State machine enters an unexpected state
  • Timers fail to start or abort
  • BanchoBot commands don’t execute as expected
  • Scores are missing or incomplete

​
How to Trigger Panic

​
The !panic Command

Anyone in the lobby can type: 
!panic
What happens immediately:
  1. All active timers are aborted (!mp aborttimer)
  2. State machine transitions to MatchOnHold
  3. All referees are pinged in Discord
  4. A notification is posted with who triggered panic
1

Panic Triggered

[Player] !panic
[AUTO] !mp aborttimer
[AUTO] <@REFEREE_ROLE_ID> PANIC MODE ACTIVATED by Player
2

Automation Halts

The automaton enters MatchOnHold state:
  • No further automatic actions are taken
  • State machine waits indefinitely
  • Manual commands still work (referee can use IRC)
3

Referee Investigates

The referee:
  1. Reads the Discord thread to understand context
  2. Communicates with players in IRC
  3. Reviews what happened before panic
  4. Determines the correct course of action

​
Manual Intervention Workflow

Once panic mode is active, the referee takes over:

​
Step 1: Join the Lobby Manually

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
Use this command in your IRC client to join the lobby manually.
Popular IRC clients for osu! referees:
  • HexChat (Windows, Linux)
  • Textual (macOS)
  • IRCCloud (Web-based)
  • osu! in-game chat (built-in IRC)

​
Step 2: Assess the Situation

Review the Discord thread logs to understand:
  • What was happening when panic was triggered
  • Which map was being played (or was about to be played)
  • Current score and match state
  • Who triggered panic and why

​
Step 3: Manual Control

While in MatchOnHold, you have full manual control: Manual IRC Commands Available: 
!mp abort          # Abort current map
!mp map <id>       # Load a different map
!mp mods <mods>    # Change mods
!mp start          # Start the match manually
!mp invite <user>  # Invite a player
!mp settings       # Check current lobby settings
The bot will not interfere while in panic mode.

​
Step 4: Resolve the Issue

Common resolutions:
IssueResolution
Wrong map loadedUse !mp map <id> to load correct map
Incorrect modsUse !mp mods to fix mods
Player disconnectedWait for reconnect, use !mp invite
Disputed scoreReplay the map manually
Automation errorManually complete current map, then resume

​
Step 5: Communicate with Players

Keep players informed via IRC chat: 
Ref: The issue has been resolved. We will replay this map.
Ref: Scores from the previous attempt will not count.
Ref: Please ready up when you're ready to continue.

​
Resuming Automation

​
The >panic_over Command

Only the assigned referee can resume automation: 
>panic_over
What happens:
  1. System posts: “The automated refereeing system is back online”
  2. State transitions to WaitingForStart
  3. A 10-second timer is automatically started
  4. Automation resumes from the prepared state
1

Ensure Match is Ready

Before resuming:
  • Correct map is loaded
  • Correct mods are applied
  • All players are in the lobby
  • Any disputes are resolved
2

Resume Automation

>panic_over
The automaton will:
  1. Start a 10-second countdown
  2. Wait for players to ready up
  3. Resume normal state machine flow
3

Monitor Resumption

Watch the Discord thread to ensure:
  • The timer starts correctly
  • Players ready up
  • The map begins as expected
  • Automation continues smoothly
Only the assigned referee can use >panic_over. This is verified by checking:
if (sender != currentMatch.Referee.DisplayName.Replace(' ', '_'))
    return;
Source reference: AutoRefQualifiersStage.cs:202, AutoRefEliminationStage.cs:294

​
Safety Guarantees

The panic protocol provides several safety guarantees:

​
1. Universal Access

Anyone can trigger panic—not just referees or staff: 
if (content.Contains("!panic"))
{
    currentState = MatchState.MatchOnHold;
    // ...
}
This ensures players can always stop automation if something goes wrong.

​
2. Immediate Effect

Panic is processed before state machine logic: 
// Emergency Protocols (!panic)
// Decoupled from the main State Machine to ensure 
// it works regardless of the current state.
if (content.Contains("!panic"))
{
    // Handle panic
}

// Then drive state machine
await TryStateChange(senderNick, content);
Source reference: AutoRefQualifiersStage.cs:200-226, AutoRefEliminationStage.cs:292-316

​
3. Complete Halt

When MatchOnHold is active: 
if (currentState == MatchState.Idle) return;
The state machine does nothing. No automatic transitions, no timer starts, no map loads.

​
4. Full Logs Retained

All IRC messages are mirrored to Discord in real-time, including:
  • Chat before panic was triggered
  • The panic trigger itself
  • All manual referee commands
  • Actions taken during panic mode
  • Resumption of automation
This creates a complete audit trail for tournament staff.

​
5. Referee Notification

When panic is triggered, all referees are pinged: 
await SendMessageBothWays(
    string.Format(Strings.Panic, 
        Environment.GetEnvironmentVariable("DISCORD_REFEREE_ROLE_ID"), 
        senderNick)
);
This ensures rapid response even if the assigned referee is temporarily unavailable. Source reference: AutoRefQualifiersStage.cs:213-215, AutoRefEliminationStage.cs:305-307

​
Best Practices

​
For Referees

1

Always Monitor the Thread

Keep the Discord thread open during matches to catch panic triggers immediately.
2

Have IRC Client Ready

Keep an IRC client logged in and ready to join with the /join command.
3

Communicate Clearly

When taking manual control:
  1. Announce your presence in IRC
  2. Explain what you’re doing
  3. Tell players when to expect resumption
  4. Confirm when automation is resuming
4

Document Issues

Note what caused the panic in the Discord thread for future reference and system improvement.

​
For Players

1

Use Panic Responsibly

Only trigger !panic when there’s a legitimate issue:
  • Technical problems
  • Scoring errors
  • Map/mod mistakes
  • Rule violations
2

Explain the Issue

After triggering panic, immediately explain in chat:
Player: !panic
Player: The wrong map loaded, this should be HD2 not HD3
3

Wait for Referee

Don’t continue playing or issue commands. Wait for the referee to take control.
4

Follow Instructions

Once the referee arrives, follow their instructions for resolving the issue.

​
Common Panic Scenarios

​
Scenario 1: Wrong Map Loaded

Player: !panic
Player: This is NM2 but I picked NM3

Ref joins via IRC
Ref: I see the issue, loading NM3 now
Ref: !mp map 123456
Ref: !mp mods NM NF
Ref: Ready up when you're good to go
Ref: >panic_over

[AUTO] The automated refereeing system is back online
[AUTO] !mp timer 10

​
Scenario 2: Player Disconnection Mid-Map

Player1: !panic
Player1: Player2 disconnected

Ref joins via IRC
Ref: Understood, we'll wait for them to reconnect

[5 minutes later]

Ref: Player2 is back, restarting this map
Ref: !mp abort
Ref: Everyone ready?
Ref: >panic_over

[AUTO] The automated refereeing system is back online

​
Scenario 3: Score Calculation Error

Player: !panic
Player: I scored higher but the bot gave the point to the opponent

Ref joins via IRC
Ref: Let me check the logs
Ref: [Reviews Discord thread]
Ref: You're correct, I'm manually awarding the point
Ref: The score is now 3-2 in your favor
Ref: Continuing from here
Ref: >panic_over

​
Technical Implementation

​
Panic Detection

Both qualifier and elimination automatons check for !panic in every IRC message: 
else if (content.Contains("!panic"))
{
    currentState = MatchState.MatchOnHold;
    await SendMessageBothWays("!mp aborttimer");

    await SendMessageBothWays(
        string.Format(Strings.Panic, 
            Environment.GetEnvironmentVariable("DISCORD_REFEREE_ROLE_ID"), 
            senderNick)
    );
}
Source reference: AutoRefQualifiersStage.cs:208-216, AutoRefEliminationStage.cs:300-307

​
Panic Recovery

Recovery requires the assigned referee: 
if (content.Contains(">panic_over") && 
    senderNick == currentMatch!.Referee.DisplayName.Replace(' ', '_'))
{
    await SendMessageBothWays(Strings.BackToAuto);
    currentState = MatchState.WaitingForStart;
    await SendMessageBothWays("!mp timer 10");
}
Source reference: AutoRefQualifiersStage.cs:202-207, AutoRefEliminationStage.cs:294-299

​
State Machine Bypass

Panic handling is decoupled from the main state machine: 
// 2. Emergency Protocols (!panic)
// Decoupled from the main State Machine to ensure 
// it works regardless of the current state.
if (content.Contains(">panic_over") && ...)
{
    // Handle recovery
}
else if (content.Contains("!panic"))
{
    // Handle panic
}

// 3. Drive the State Machine
await TryStateChange(senderNick, content);
This ensures panic works even if the state machine is in an unexpected state.

Build docs developers (and LLMs) love

Get started for freeTalk to us