Swiss Pairing Engine

Overview

The BBX Swiss Pairing Engine is the core logic responsible for managing the "Swiss" stage of tournaments. Unlike single-elimination brackets, the Swiss system ensures all participants play a set number of rounds, regardless of whether they win or lose. The engine dynamically pairs players with similar win-loss records to ensure competitive integrity throughout the event.

Ranking and Standings

The engine determines player rank using three distinct metrics. If two players have the same score in the first metric, it moves to the second, and then the third (tie-breakers).

1. Match Wins (Primary)

The primary ranking factor is the total number of matches won. Each match victory grants 1 point toward the standings.

2. Buchholz Score (Secondary)

The Buchholz score is the primary tie-breaker. It is calculated by summing the match wins of all opponents a participant has faced.

• Why it matters: It rewards players who have faced a "strength of schedule" advantage. If two players have the same win-loss record, the one who played against opponents with higher total wins will rank higher.

3. Point Differential (Tertiary)

If players are still tied after the Buchholz calculation, the engine looks at the Point Differential.

• Calculation: (Total Points Scored) - (Total Points Conceded)
• This metric encourages players to win their matches by the largest margin possible.

Managing the Swiss Stage

Tournament organizers manage the Swiss Engine through the Admin Console. The engine automates the generation of pairings based on the current standings.

Advancing Rounds

Once all matches in a current Swiss round are marked as complete, the admin can trigger the next round.

// Example of the action triggered by the Admin Console
const result = await advanceBracketAction();

if (result.success) {
    console.log("Next round pairings generated.");
}

Key Behaviors:

• Pairing Logic: The engine identifies players with identical records (e.g., all 2-0 players) and pairs them randomly against each other.
• Avoid Repeat Matches: The engine attempts to ensure that no two participants face each other more than once during the Swiss stage.
• Byes: If there is an odd number of participants, the engine automatically assigns a "BYE" (a win with 0 point differential) to the lowest-ranked player who has not yet received one.

Automatic Scoring

For large events, admins can use the "Auto-Score" utility to finalize rounds where scores are predetermined or for testing purposes.

// Internal utility to finalize a round based on current inputs
await autoScoreRoundAction(tournamentId, roundNumber);

The "Top Cut" Transition

After the predetermined number of Swiss rounds (typically 5 for local events), the engine facilitates the transition to a Single Elimination bracket, known as the Top Cut.

1. Qualification: The engine identifies the top $N$ players (defined by the cut_size, e.g., Top 8 or Top 16) based on the Swiss Standings.
2. Seeding: The #1 seed from Swiss plays the lowest qualifying seed (#8 or #16), and so on.
3. Finalization: Once the "Proceed to Top Cut" action is confirmed, the Swiss stage is locked, and the tournament shifts into bracket mode.

Viewing Standings

Participants can monitor their current rank and tie-breaker stats in real-time via the /standings page. This view provides:

• Rank: Current position in the tournament.
• Status: A visual indicator (highlighted rows) showing if the player is currently within the "Qualifying Zone" for the Top Cut.
• Detailed Stats: Individual breakdowns of Wins, Buchholz, and Pt. Diff.

| Rank | Participant | Wins | Buchholz | Pt. Diff | Status | | :--- | :--- | :--- | :--- | :--- | :--- | | 1 | PlayerAlpha | 3 | 12 | +15 | Qualifying | | 2 | PlayerBeta | 3 | 10 | +8 | Qualifying | | 3 | PlayerGamma | 2 | 14 | +2 | - |