Tournaments
Relevant source files
The following files were used as context for generating this wiki page:The tournament system provides a structured, competitive poker experience where players compete until one player holds all the chips. The system is managed by a central TournamentEngine that handles the entire lifecycle, from registration to prize distribution. Players can choose from various tournament formats, including Heads-Up, Turbo, and Bounty tournaments, each with a unique configuration for blind structures, player counts, and prize pools.
The user interface for tournaments is built with React components that interact with the engine via the useTournament hook. This hook provides a clean interface for creating, joining, and starting tournaments, while also supplying real-time state updates to the UI, such as blind level changes, player counts, and prize pool information.
Architecture Overview
The tournament feature is built around a central TournamentEngine singleton that manages all tournament logic. React components interact with this engine through the useTournament hook, which abstracts the engine's methods and provides reactive state to the UI.
This diagram shows the high-level interaction between the UI components, the state management hook, and the core engine.
Tournament Lifecycle
A tournament progresses through several distinct phases, managed by the TournamentEngine. The lifecycle begins with registration and ends when the tournament is complete and prizes are awarded.
The TournamentPhase type defines the possible states:
- registration: Players can join the tournament.
- late-registration: A period after the tournament starts where players can still join.
- running: The tournament is active, and hands are being played.
- break: A scheduled pause in play.
- final-table: The tournament has been consolidated to a single, final table.
- completed: A winner has been determined.
Sources: types/tournament.ts:1-3
Data Models
The tournament system relies on a set of well-defined types to manage its state and configuration. These are all defined in types/tournament.ts.
This ER diagram illustrates the relationships between the main tournament data structures.
Sources: types/tournament.ts
TournamentConfig
This interface defines the static configuration for a tournament.
| Property | Type | Description |
|---|---|---|
id | string | Unique identifier for the tournament. |
name | string | Display name of the tournament. |
buyIn | number | The cost to enter the tournament (contributes to prize pool). |
entryFee | number | The fee for entering (does not go to prize pool). |
startingChips | number | The number of chips each player starts with. |
maxPlayers | number | The maximum number of players allowed. |
minPlayers | number | The minimum number of players required to start. |
playersPerTable | number | The number of players at each table. |
lateRegistrationMinutes | number | Duration for late registration. |
blindStructure | BlindLevel[] | An array defining the blind levels. |
prizePoolPercentages | number[] | Payout structure, e.g., [50, 30, 20]. |
tournamentType | TournamentType | The type of tournament (e.g., regular, bounty). |
bountyAmount | number (optional) | The bounty value per player in bounty tournaments. |
addOnConfig | AddOnConfig (optional) | Configuration for add-ons. |
rebuyConfig | RebuyConfig (optional) | Configuration for rebuys. |
Sources: types/tournament.ts:19-36
TournamentState
This interface represents the dynamic state of a running tournament.
| Property | Type | Description |
|---|---|---|
config | TournamentConfig | The configuration object for this tournament. |
phase | TournamentPhase | The current phase of the tournament. |
currentBlindLevel | number | The index of the current blind level. |
blindLevelTimeRemaining | number | Seconds remaining until the next blind level. |
totalPrizePool | number | The current total prize pool. |
registeredPlayers | TournamentPlayer[] | List of all registered players. |
tables | TournamentTable[] | The active tables in the tournament. |
remainingPlayers | number | The number of players still in the tournament. |
breakTimeRemaining | number (optional) | Seconds remaining in the current break. |
isAddOnAvailable | boolean (optional) | Flag indicating if add-ons can be purchased. |
isRebuyAvailable | boolean (optional) | Flag indicating if rebuys can be purchased. |
Sources: types/tournament.ts:60-78
BlindLevel
Defines a single level in the tournament's blind structure.
| Property | Type | Description |
|---|---|---|
level | number | The level number. |
smallBlind | number | The small blind amount. |
bigBlind | number | The big blind amount. |
ante | number (optional) | The ante amount for this level. |
duration | number | The duration of the level in seconds. |
isBreak | boolean (optional) | If true, this level is a break. |
Sources: types/tournament.ts:5-12
Core Logic: TournamentEngine
The TournamentEngine class, implemented as a singleton, is the heart of the tournament system. It manages the state and logic for all tournaments.
Sources: lib/tournament-engine.ts:10-17
Key Methods
createTournament(config: TournamentConfig): Initializes a new tournament with the given configuration and sets its phase toregistration.registerPlayer(tournamentId, playerId, playerName): Adds a player to a tournament, updates player counts, and increases the prize pool.startTournament(tournamentId): Starts the tournament if the minimum number of players has been met. It shuffles players, creates tables, and sets the phase torunning.advanceBlindLevel(tournamentId): Moves the tournament to the next blind level, updates timers, and handles transitions to/from break phases.eliminatePlayer(tournamentId, playerId, eliminatorId?): Removes a player from the tournament, updates counts, handles bounties, and triggers table balancing.balanceTables(tournament): A private method that ensures tables have a roughly equal number of players. It can move players or consolidate tables.processRebuy(tournamentId, playerId): Allows a player to rebuy chips if the tournament configuration and player state permit it.processAddOn(tournamentId, playerId): Allows a player to purchase an add-on during the designated period.updateTimer(tournamentId, deltaSeconds): Called periodically to decrement blind or break timers and trigger level advances.
Sources: lib/tournament-engine.ts
Tournament Start Flow
The following sequence diagram shows how a user registers for and starts a tournament from the TournamentLobby.
Tournament Types and Structures
The system supports several predefined tournament types, each with a distinct blind structure.
Sources: components/tournament-lobby.tsx:28-91
| Type | Description | Blind Structure Method |
|---|---|---|
regular | A standard tournament format. | TournamentEngine.getDefaultBlindStructure() |
turbo | A fast-paced format with shorter blind levels (5 mins). | TournamentEngine.getTurboBlindStructure() |
headsup | A 1-on-1 bracket-style tournament. | TournamentEngine.getHeadsUpBlindStructure() |
bounty | Players earn a cash prize (bountyAmount) for eliminating opponents. | TournamentEngine.getDefaultBlindStructure() |
Sources: components/tournament-lobby.tsx:28-91, lib/tournament-engine.ts:19-86
Blind Structures
The TournamentEngine provides static methods to generate different blind structures. For example, the default structure includes 10-minute levels and scheduled 15-minute breaks.
// Example from TournamentEngine.getDefaultBlindStructure()
[
{ level: 1, smallBlind: 25, bigBlind: 50, ante: 0, duration: 600 }, // 10 min
{ level: 2, smallBlind: 50, bigBlind: 100, ante: 0, duration: 600 },
// ...
{ level: 5, smallBlind: 0, bigBlind: 0, duration: 900, isBreak: true, breakDuration: 900 }, // 15-min break
// ...
]
Sources: lib/tournament-engine.ts:20-37
UI Components
Several React components are dedicated to the tournament experience.
TournamentLobby: The entry point for all tournaments. It lists available tournaments, shows their configurations (buy-in, prize pool, structure), and handles the registration and start process.
Sources: components/tournament-lobby.tsxTournamentStructure: A component that displays the full blind structure and prize distribution for a selected tournament. It highlights the current level during gameplay.
Sources: components/tournament-structure.tsxTournamentTableInfo: An overlay displayed during gameplay that shows critical live information, such as the tournament name, current blinds, time until the next level, and the number of players remaining.
Sources: components/tournament-table-info.tsxRulesPage: Provides detailed rules for different game types, including Multi-Table Tournaments (MTT) and Sit and Go (SNG) formats, explaining concepts like table balancing, rebuys, and add-ons.
Sources: components/rules-page.tsx:220-281