Tournament Table Balancing
Relevant source files
The following files were used as context for generating this wiki page:Introduction
Tournament Table Balancing is a critical system for Multi-Table Tournaments (MTTs) that ensures fairness as players are eliminated. Its primary purpose is to manage the distribution of players across multiple tables, preventing situations where some tables become short-handed while others remain full. The system automatically moves players or consolidates entire tables to maintain a roughly equal number of participants at each active table. The core rule is that no table should have more than one extra player compared to any other table.
This process is handled by the TournamentEngine, which is triggered every time a player is eliminated from the tournament. The engine employs two main strategies: moving individual players for minor adjustments and consolidating tables when the total number of players drops significantly.
Sources: components/rules-page.tsx:250-256, lib/tournament-engine.ts:559-562
Balancing Architecture
The table balancing logic is primarily managed within the TournamentEngine and supported by utility functions in the TableBalancer class. The process is initiated after a player's elimination is processed.
Sources: lib/tournament-engine.ts, lib/table-balancing-algorithm.ts
Triggering Event
The balancing process is not a standalone service but an integral part of the player elimination flow within the TournamentEngine. When eliminatePlayer is called, it removes the player from their table and then immediately calls balanceTables to check if any adjustments are needed.
The following sequence diagram illustrates this trigger mechanism.
This diagram shows how a player elimination event triggers the table balancing logic within the TournamentEngine.
Sources: lib/tournament-engine.ts:559-562, hooks/use-tournament.tsx:88-95
Core Logic (TableBalancer Class)
The TableBalancer class provides a set of static helper methods to determine the state of tables and calculate optimal distributions. While TournamentEngine contains the main implementation, TableBalancer offers the foundational algorithms.
This diagram shows the static methods available in the TableBalancer utility class.
Sources: lib/table-balancing-algorithm.ts:9-67
The key methods from this class are summarized below:
| Method | Description |
|---|---|
needsRebalancing | Checks if the difference in player count between the most and least populated tables exceeds a threshold. |
calculateOptimalTableCount | Calculates the minimum number of tables required for a given number of players. |
shouldBreakTable | Determines if a table should be broken up to consolidate players. |
redistributePlayers | Evenly distributes a list of players across a set of target tables using a round-robin method. |
Sources: lib/table-balancing-algorithm.ts:9-67
Balancing Process Flow
The balanceTables method in TournamentEngine orchestrates the entire balancing process. It decides whether to consolidate tables or simply move a player.
The following flowchart outlines the decision-making process within balanceTables.
This flowchart illustrates the logic inside the balanceTables function, showing how it decides between table consolidation and player movement.
Sources: lib/tournament-engine.ts:572-598
Strategy 1: Player Movement
When the imbalance between tables is small (specifically, when the difference between the most and least populated tables is greater than 1), the engine moves a single player.
- Selection: The
selectPlayerToMovefunction identifies a player to move from the table with the most players. For simplicity, the current implementation selects a random non-eliminated player from that table. - Movement: The
movePlayerfunction removes the selected player from their original table (fromTable) and adds them to the table with the fewest players (toTable). The player'stableIdis updated, and they are assigned a newseatNumber.
Sources: lib/tournament-engine.ts:587-598, lib/tournament-engine.ts:630-641, lib/tournament-engine.ts:643-651
Strategy 2: Table Consolidation
When the total number of players drops enough to fit onto fewer tables, the engine performs a more drastic re-organization.
- Trigger: The
shouldConsolidateTablesfunction is called. It calculates the minimum number of tables needed for the current player count (Math.ceil(totalPlayers / playersPerTable)) and returnstrueif the current number of active tables is greater than this optimal count. - Execution: If consolidation is needed, the
consolidateTablesmethod executes the following steps:- All players from all active tables are collected into a single array.
- The old tables are marked as inactive.
- A new set of tables (the optimal number) is created.
- The collected players are redistributed among the new tables using a round-robin algorithm to ensure an even spread. Each player is assigned a new
tableIdandseatNumber.
Sources: lib/tournament-engine.ts:599-628
Data Structures and Configuration
The balancing logic relies on specific data structures defined in types/tournament.ts and configuration parameters set during tournament creation.
Data Model
The relationship between the tournament, its tables, and its players is central to the balancing algorithm.
This ER diagram shows that a TOURNAMENT_STATE contains multiple TOURNAMENT_TABLEs, and each table contains multiple TOURNAMENT_PLAYERs.
Sources: types/tournament.ts
Key fields used during balancing include:
| Entity | Field | Type | Description |
|---|---|---|---|
TournamentTable | id | string | Unique identifier for the table. |
TournamentTable | players | array | An array of TournamentPlayer objects at the table. |
TournamentTable | isActive | boolean | Indicates if the table is currently in play. |
TournamentPlayer | tableId | string | The ID of the table the player is currently seated at. |
TournamentPlayer | seatNumber | number | The player's seat at their current table. |
Sources: types/tournament.ts:40-54
Configuration
The balancing behavior is influenced by the tournament's configuration, which is established when the tournament is created.
TournamentConfig Field | Type | Description | Source File |
|---|---|---|---|
playersPerTable | number | The maximum number of players that can be seated at a single table. | types/tournament.ts:21 |
minPlayers | number | The minimum players required to start the tournament. | types/tournament.ts:20 |
tournamentType | string | Defines the tournament format (e.g., headsup, regular). | components/tournament-lobby.tsx:30-90 |
Sources: types/tournament.ts:14-31, components/tournament-lobby.tsx:30-90
Conclusion
The Tournament Table Balancing system is an essential, event-driven feature that maintains competitive integrity in multi-table tournaments. By automatically responding to player eliminations, it dynamically reorganizes tables through two primary methods: moving individual players to correct minor imbalances and consolidating tables to handle larger reductions in the player field. This ensures that gameplay remains fair and consistent across the entire tournament as it progresses towards the final table.