Bracket Logic & Top Cut

Overview

The BBX Platform facilitates the transition from Swiss-style qualifying rounds to a Single-Elimination "Top Cut" bracket. This process ensures that top-performing players from the Swiss standings are seeded into a final tournament tree to determine the overall champion.

Qualification & Seeding

The transition to the bracket is governed by the Cut Size defined during tournament creation (e.g., Top 4, Top 8, or Top 16).

Swiss Standings Logic

Players are ranked based on the following tie-breaking hierarchy:

Match Wins: Total number of rounds won.
Buchholz Score: The sum of the wins of all opponents a player has faced (measures strength of schedule).
Point Differential: The net difference between points scored and points allowed.

The system highlights qualifying players in the Standings view, allowing organizers to see exactly who will advance before the cut is officially made.

Transitioning to Top Cut

Once the Swiss phase is concluded, the Tournament Organizer must manually trigger the bracket generation.

Proceed to Top Cut

In the Admin Console, use the Proceed to Top Cut action. This performs the following:

Identifies the top $N$ players (where $N$ is the cut_size).
Generates the initial bracket matches based on standard tournament seeding (e.g., 1st seed vs. $N$th seed).
Transitions the tournament stage from swiss to top_cut.

// Internal Action Reference
// This action seeds the bracket and initializes Round 1 of the Top Cut.
const res = await proceedToTopCutAction(tournamentId);

Bracket Management

The Top Cut operates on a round-by-round basis. Matches must be completed and reported before the tournament can progress to the next stage of the tree.

Reporting Scores

Administrators report scores via the Admin Console. Each match tracks:

Score A / Score B: Individual points for each participant.
Finish Type: (e.g., Spin, Burst, Out-of-Bounds).
Winner ID: Automatically assigned based on the higher score.

Advancing the Round

Unlike Swiss rounds, which may allow for concurrent reporting, the bracket requires all matches in Round N to be complete before Round N+1 can be generated.

Navigate to the Admin Console.
Ensure all "Pending Matches" for the current round are cleared.
Click Advance Bracket to Next Round.

This action identifies the winners of the current bracket round and moves them into the appropriate slots for the subsequent round.

Bracket Visualization

The public Bracket Page (/t/[id]/bracket) provides a real-time visualization of the tournament tree.

Visual Indicators

Winner Highlighting: Winning participants are highlighted in the primary theme color.
Score Display: Final scores for completed matches are shown on the right side of each participant node.
Finals & Champion: The final match is given a distinct visual treatment, often including a trophy icon and the "Finals" label.

Match Node Structure

Each node in the bracket displays:

Participant ID: A shortened UUID or the participant's registered name.
Seed Logic: Implicitly handled by the match_number and bracket_round within the database.
Status: Pending matches are shown as neutral, while completed matches show the victor.

Data Structure: Top Cut Matches

For developers or advanced users querying the API/Database, Top Cut matches are identified by the stage field.

-- Example: Fetching the current state of the Top Cut
SELECT match_number, bracket_round, winner_id, status
FROM matches
WHERE tournament_id = 'your-id' 
  AND stage = 'top_cut'
ORDER BY bracket_round ASC, match_number ASC;