State Machines

Overview

Both AutoRef implementations use finite state machines (FSMs) to manage tournament match flow. This page provides comprehensive documentation on state transitions, event triggers, and command effects.

Elimination Stage State Machine

Visual Diagram

State Transition Table

Current State	Event/Trigger	Condition	Next State	Action
Idle	`>start`	`firstPick` and `firstBan` are set	`BanPhaseStart`	Engage automation
Idle	`>start`	Previously stopped	Previous state	Resume automation
BanPhaseStart	Auto	`firstBan == Red`	`WaitingForBanRed`	Request red ban
BanPhaseStart	Auto	`firstBan == Blue`	`WaitingForBanBlue`	Request blue ban
WaitingForBanRed	Player message	Valid map slot	`WaitingForBanBlue`	Record ban, switch turn
WaitingForBanRed	Player message	2 bans complete	`PickPhaseStart`	End ban phase
WaitingForBanBlue	Player message	Valid map slot	`WaitingForBanRed`	Record ban, switch turn
WaitingForBanBlue	Player message	2 bans complete	`PickPhaseStart`	End ban phase
PickPhaseStart	Auto	`firstPick == Red`	`WaitingForPickRed`	Request red pick
PickPhaseStart	Auto	`firstPick == Blue`	`WaitingForPickBlue`	Request blue pick
WaitingForPickRed	Player message	Valid map slot	`WaitingForStart`	Load map, start timer
WaitingForPickRed	Timer expires	90 seconds elapsed	`WaitingForPickBlue`	Stolen pick
WaitingForPickBlue	Player message	Valid map slot	`WaitingForStart`	Load map, start timer
WaitingForPickBlue	Timer expires	90 seconds elapsed	`WaitingForPickRed`	Stolen pick
WaitingForStart	BanchoBot	”All players are ready”	`Playing`	Start match
WaitingForStart	BanchoBot	”Countdown finished”	`Playing`	Start match
Playing	BanchoBot	”Match finished” + 4 maps played + 2 ban rounds	`SecondBanPhaseStart`	Trigger second ban phase
Playing	BanchoBot	”Match finished” + both teams at match point	`WaitingForStart`	Auto-pick tiebreaker
Playing	BanchoBot	”Match finished” + win condition met	`MatchFinished`	Announce winner
Playing	BanchoBot	”Match finished” + red picked last	`WaitingForPickBlue`	Next pick to blue
Playing	BanchoBot	”Match finished” + blue picked last	`WaitingForPickRed`	Next pick to red
SecondBanPhaseStart	Auto	`firstBan == Red`	`WaitingForBanBlue`	Request blue ban (opposite)
SecondBanPhaseStart	Auto	`firstBan == Blue`	`WaitingForBanRed`	Request red ban (opposite)
Any waiting/playing state	`!panic`	Anyone	`MatchOnHold`	Abort timers, ping referees
MatchOnHold	`>panic_over`	Referee only	`WaitingForStart`	Resume with 10s timer
Any pick/ban/waiting state	`!timeout`	Red team + timeout available	`OnTimeout`	Start 120s timeout
Any pick/ban/waiting state	`!timeout`	Blue team + timeout available	`OnTimeout`	Start 120s timeout
OnTimeout	BanchoBot	”Countdown finished”	Previous state	Resume match
Any non-Idle state	`>stop`	Referee only	`Idle`	Pause automation

Event Triggers

BanchoBot Events

Message Pattern	Effect
`Created the tournament match`	Extract MP link ID, join lobby
`finished playing (Score: X,`	Record player score (regex)
`The match has finished!`	Process scores, check win condition
`All players are ready`	Start match from WaitingForStart
`Countdown finished`	Start match or end timeout
`Changed beatmap`	Confirmation (awaited by commands)

Player Events

Input	State Required	Effect
`NM1`, `HD2`, etc.	`WaitingForPickRed/Blue`	Pick map if valid
`NM1`, `HD2`, etc.	`WaitingForBanRed/Blue`	Ban map if valid
`!timeout`	Pick/Ban/WaitingForStart	Request timeout (once per team)
`!panic`	Any active state	Trigger emergency stop

Referee Commands

Command	Effect on State Machine
`>start`	`Idle` → `BanPhaseStart`
`>stop`	Any → `Idle`
`>panic_over`	`MatchOnHold` → `WaitingForStart`
`>timeout`	Current → `OnTimeout`
`>firstpick [team]`	Sets `firstPick` (required before start)
`>firstban [team]`	Sets `firstBan` (required before start)
`>setmap [slot]`	Requires `Idle` state, doesn’t change state
`>maps`	No state change (informational)
`>invite`	No state change (sends invites)
`>finish`	Closes lobby (should use `/endref` instead)

Win Condition Logic

int pointsToWin = (currentMatch.Round.BestOf - 1) / 2 + 1;
bool redWin = matchScore[0] == pointsToWin;
bool blueWin = matchScore[1] == pointsToWin;

Examples:

Best of 7: First to 4 points wins
Best of 11: First to 6 points wins
Best of 13: First to 7 points wins

Tiebreaker Trigger

if (pickedMaps.Count == currentMatch.Round.BestOf - 1)
{
    // Both teams are at match point
    await PreparePick("TB1");
}

Example (Best of 7):

Score reaches 3-3 after 6 maps
Tiebreaker is automatically picked
No player input required

Double Ban Round Logic

if (currentMatch.Round.BanRounds == 2 && pickedMaps.Count == 4)
{
    currentState = MatchState.SecondBanPhaseStart;
}

Flow:

Initial bans: 2 per team (4 maps banned)
First picks: 4 maps played
Second ban phase triggers
Second bans: 2 per team (8 maps total banned)
Continue picks until win condition

Stolen Pick Mechanism

If a team doesn’t pick within 90 seconds:

if (content.Contains("Countdown finished") && sender == "BanchoBot")
{
    // Switch to opponent with 60-second timer
    currentState = MatchState.WaitingForPickBlue; // or Red
    isStolenPick = true;
    await SendMessageBothWays("!mp timer 60");
}

Effect on Pick Order:

lastPick is set to the team that should have picked
This ensures pick order alternates correctly on next map

Qualifiers Stage State Machine

Visual Diagram

State Transition Table

Current State	Event/Trigger	Condition	Next State	Action
Idle	`>start`	Not previously stopped	`Idle`	Reset map index, load first map
Idle	`>start`	Previously stopped	Previous state	Resume from previous state
Idle	Auto (from flow)	Maps remaining	`WaitingForStart`	Load next map, start 120s timer
Idle	Auto (from flow)	All maps played	`MatchFinished`	Announce completion
WaitingForStart	BanchoBot	”All players are ready”	`Playing`	Start match
WaitingForStart	BanchoBot	”Countdown finished”	`Playing`	Start match
Playing	BanchoBot	”Match finished”	`Idle`	Increment map index, 10s cooldown
Any active state	`!panic`	Anyone	`MatchOnHold`	Abort timers, ping referees
MatchOnHold	`>panic_over`	Referee only	`WaitingForStart`	Resume with 10s timer
Any non-Idle state	`>stop`	Referee only	`Idle`	Pause automation

Event Triggers

BanchoBot Events

Message Pattern	Effect
`Created the tournament match`	Extract MP link ID, join lobby
`The match has finished`	Increment map index, trigger cooldown
`All players are ready`	Start match from WaitingForStart
`Countdown finished`	Start match from WaitingForStart
`Changed beatmap`	Confirmation (awaited by commands)

Player Events

Input	State Required	Effect
`!panic`	Any active state	Trigger emergency stop

Referee Commands

Command	Effect on State Machine
`>start`	`Idle` → `Idle` (triggers flow)
`>stop`	Any → `Idle`
`>panic_over`	`MatchOnHold` → `WaitingForStart`
`>setmap [slot]`	Requires `Idle` state, doesn’t change state
`>invite`	No state change (sends invites)
`>finish`	Closes lobby (should use `/endref` instead)

Map Progression Flow

┌─────────────────────────────────────────┐
│ >start command                          │
│ - Set currentMapIndex = 0               │
│ - Set currentState = Idle               │
│ - Call PrepareNextQualifierMap()        │
└─────────────────────────────────────────┘
                  |
                  v
┌─────────────────────────────────────────┐
│ PrepareNextQualifierMap()               │
│ - Check if maps remaining               │
│ - Load map at currentMapIndex           │
│ - Apply mods (e.g., NM, HD, HR + NF)    │
│ - Start 120s timer                      │
│ - Set state to WaitingForStart          │
└─────────────────────────────────────────┘
                  |
                  v
┌─────────────────────────────────────────┐
│ WaitingForStart                         │
│ - Wait for players to ready up          │
│ - OR wait for timer to expire           │
└─────────────────────────────────────────┘
                  |
                  v
┌─────────────────────────────────────────┐
│ Playing                                 │
│ - Match is in progress                  │
│ - Wait for "Match finished" message     │
└─────────────────────────────────────────┘
                  |
                  v
┌─────────────────────────────────────────┐
│ Match Finished Event                    │
│ - Increment currentMapIndex++           │
│ - Set state to Idle                     │
│ - Start 10-second cooldown              │
└─────────────────────────────────────────┘
                  |
                  v
┌─────────────────────────────────────────┐
│ Cooldown Complete                       │
│ - Call PrepareNextQualifierMap()        │
│ - Loop back to top                      │
└─────────────────────────────────────────┘

Map Index Progression

Example Pool: 7 maps (NM1, NM2, HD1, HD2, HR1, HR2, DT1)

Event	currentMapIndex	Map Loaded	State
`>start`	0	NM1	WaitingForStart
Match finishes	1	NM2	WaitingForStart
Match finishes	2	HD1	WaitingForStart
Match finishes	3	HD2	WaitingForStart
Match finishes	4	HR1	WaitingForStart
Match finishes	5	HR2	WaitingForStart
Match finishes	6	DT1	WaitingForStart
Match finishes	7	(none)	MatchFinished

Exit Condition

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

When this triggers:

All maps have been played
currentMapIndex exceeds pool size
Automation announces completion
State set to MatchFinished (terminal state)

Common State Machine Patterns

Panic System

Both implementations share identical panic logic: Activation:

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

Recovery:

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

Key Properties:

Can be triggered by anyone in the lobby
Can only be cleared by the assigned referee
Immediately aborts all active timers
Pings Discord referee role for visibility
Always recovers to WaitingForStart with a 10-second timer

Timer System

Context	Duration	Command
Elimination: Map Ready	90 seconds	`!mp timer 90`
Elimination: Timeout	120 seconds	`!mp timer 120`
Qualifiers: Map Ready	120 seconds	`!mp timer 120`
Panic Recovery	10 seconds	`!mp timer 10`
Match Start Delay	10 seconds	`!mp start 10`
Stolen Pick Window	60 seconds	`!mp timer 60`

State Persistence

Both implementations support stop/resume:

private bool stoppedPreviously;
private MatchState previousState;

case "stop":
    previousState = currentState;
    currentState = MatchState.Idle;
    stoppedPreviously = true;
    break;

case "start":
    if (stoppedPreviously)
    {
        currentState = previousState;
        stoppedPreviously = false;
    }
    break;

Use Case:

Referee needs to manually intervene mid-automation
>stop pauses without losing state
>start resumes exactly where it left off

State Machine Comparison

Aspect	Elimination	Qualifiers
Total States	13	5
Player Input	Required (picks/bans)	Not required
Deterministic Flow	No (player-driven)	Yes (linear)
Win Condition	First to N points	Complete all maps
Timeout Support	Yes (per-team)	No
Pick Timer	90 seconds	N/A
Map Timer	90 seconds	120 seconds
Cooldown	None	10 seconds
Map Selection	Player choice	Sequential
Complexity	High	Low

Debugging State Machines

Logging Current State

Both classes expose currentState as internal, allowing test inspection:

Console.WriteLine($"Current State: {autoRef.currentState}");

Forcing State Transitions

For testing, states can be manually set:

autoRef.currentState = MatchState.WaitingForStart;
await autoRef.HandleIrcMessage(mockMessage);

Common Stuck States

State	Likely Cause	Fix
`WaitingForPickRed/Blue`	Player offline or confused	Referee types `>stop`, manually picks, `>start`
`WaitingForStart`	Timer expired but no reaction	Check panic mode; `>panic_over` if stuck
`MatchOnHold`	Panic never cleared	Referee types `>panic_over`
`OnTimeout`	Timeout countdown stuck	Wait for BanchoBot “Countdown finished”
`Idle`	Automation never started	Check if `firstPick`/`firstBan` are set (elimination)

Database Models

AutoRef System

Overview

Elimination Stage State Machine

Visual Diagram

State Transition Table

Event Triggers

BanchoBot Events

Player Events

Referee Commands

Win Condition Logic

Tiebreaker Trigger

Double Ban Round Logic

Stolen Pick Mechanism

Qualifiers Stage State Machine

Visual Diagram

State Transition Table

Event Triggers

BanchoBot Events

Player Events

Referee Commands

Map Progression Flow

Map Index Progression

Exit Condition

Common State Machine Patterns

Panic System

Timer System

State Persistence

State Machine Comparison

Debugging State Machines

Logging Current State

Forcing State Transitions

Common Stuck States

Build docs developers (and LLMs) love

Database Models

AutoRef System

​Overview

​Elimination Stage State Machine

​Visual Diagram

​State Transition Table

​Event Triggers

​BanchoBot Events

​Player Events

​Referee Commands

​Win Condition Logic

​Tiebreaker Trigger

​Double Ban Round Logic

​Stolen Pick Mechanism

​Qualifiers Stage State Machine

​Visual Diagram

​State Transition Table

​Event Triggers

​BanchoBot Events

​Player Events

​Referee Commands

​Map Progression Flow

​Map Index Progression

​Exit Condition

​Common State Machine Patterns

​Panic System

​Timer System

​State Persistence

​State Machine Comparison

​Debugging State Machines

​Logging Current State

​Forcing State Transitions

​Common Stuck States

​Related Documentation

Build docs developers (and LLMs) love

Overview

Elimination Stage State Machine

Visual Diagram

State Transition Table

Event Triggers

BanchoBot Events

Player Events

Referee Commands

Win Condition Logic

Tiebreaker Trigger

Double Ban Round Logic

Stolen Pick Mechanism

Qualifiers Stage State Machine

Visual Diagram

State Transition Table

Event Triggers

BanchoBot Events

Player Events

Referee Commands

Map Progression Flow

Map Index Progression

Exit Condition

Common State Machine Patterns

Panic System

Timer System

State Persistence

State Machine Comparison

Debugging State Machines

Logging Current State

Forcing State Transitions

Common Stuck States

Related Documentation