feat: support double-elimination series games

This commit is contained in:
dahyeon committed 2026-07-07 17:34:59 -07:00
1 parent 2ee8c3807b
commit e188828423
16 files changed
+1176 -234

No files matched your search

@@ -43,6 +43,8 @@ export interface DoubleEliminationWalkover {
export interface DoubleEliminationBracketMatch {
bracketMatchId: string;
gameNumber: number;
gameCount: number;
requiredWins: number;
bracketSide: DoubleEliminationBracketSide;
roundNumber: number;
matchNumber: number;
@@ -95,6 +97,27 @@ export interface DoubleEliminationBracket {
export interface BuildDoubleEliminationBracketOptions {
resetFinalEnabled: boolean;
winnerBracketGameCount?: number;
}
export interface DoubleEliminationSeriesRule {
gameCount: number;
requiredWins: number;
}
export interface DoubleEliminationGameSlot {
gameNumber: number;
seriesGameNumber: number;
seriesGameCount: number;
seriesRequiredWins: number;
bracketMatch: DoubleEliminationBracketMatch;
}
export interface DoubleEliminationSeriesScore {
teamAIndex: number;
teamBIndex: number;
teamAWins: number;
teamBWins: number;
}
export interface CompleteDoubleEliminationBracketMatchParams {
@@ -127,8 +150,8 @@ export function buildDoubleEliminationBracket(
seeds,
bracketMatches:
seededTeamIndexes.length === 4
? buildFourTeamBracketMatches()
: buildEightTeamBracketMatches(),
? buildFourTeamBracketMatches(options)
: buildEightTeamBracketMatches(options),
placements: {},
events: [
{
@@ -142,6 +165,73 @@ export function buildDoubleEliminationBracket(
return bracket;
}
export function resolveDoubleEliminationSeriesRule(
params: {
bracketSide: DoubleEliminationBracketSide;
bracketMatchId: string;
roundNumber: number;
},
options: { winnerBracketGameCount?: number } = {},
): DoubleEliminationSeriesRule {
if (params.bracketSide === 'winner') {
return seriesRule(options.winnerBracketGameCount ?? 3);
}
return seriesRule(1);
}
export function buildDoubleEliminationGameSlots(
bracketMatches: DoubleEliminationBracketMatch[],
): DoubleEliminationGameSlot[] {
const slots: DoubleEliminationGameSlot[] = [];
let gameNumber = 1;
for (const bracketMatch of bracketMatches) {
const seriesGameCount = normalizeSeriesGameCount(bracketMatch.gameCount);
const seriesRequiredWins =
bracketMatch.requiredWins ?? requiredWinsForGameCount(seriesGameCount);
for (
let seriesGameNumber = 1;
seriesGameNumber <= seriesGameCount;
seriesGameNumber += 1
) {
slots.push({
gameNumber,
seriesGameNumber,
seriesGameCount,
seriesRequiredWins,
bracketMatch,
});
gameNumber += 1;
}
}
return slots;
}
export function resolveDoubleEliminationSeriesWinner(
series: DoubleEliminationSeriesScore | undefined,
bracketMatch: Pick<
DoubleEliminationBracketMatch,
'requiredWins' | 'teamAIndex' | 'teamBIndex'
>,
): number | undefined {
if (!series) return undefined;
const requiredWins = bracketMatch.requiredWins ?? 1;
if (
bracketMatch.teamAIndex &&
series.teamAWins >= requiredWins &&
series.teamAWins > series.teamBWins
) {
return bracketMatch.teamAIndex;
}
if (
bracketMatch.teamBIndex &&
series.teamBWins >= requiredWins &&
series.teamBWins > series.teamAWins
) {
return bracketMatch.teamBIndex;
}
return undefined;
}
export function reshuffleDoubleEliminationSeeds(
bracket: DoubleEliminationBracket,
rng: () => number = Math.random,
@@ -245,10 +335,13 @@ export function cancelDoubleEliminationBracketMatch(
bracketMatch.bracketMatchId,
);
const completedDescendant = next.bracketMatches.find(
(match) => descendants.has(match.bracketMatchId) && match.state === 'completed',
(match) =>
descendants.has(match.bracketMatchId) && match.state === 'completed',
);
if (completedDescendant) {
throw new Error('Cannot cancel because a downstream bracket match is completed.');
throw new Error(
'Cannot cancel because a downstream bracket match is completed.',
);
}
if (bracketMatch.bracketMatchId === 'GF') {
@@ -263,10 +356,20 @@ export function cancelDoubleEliminationBracketMatch(
(match) => match.bracketMatchId === descendantId,
);
if (!descendant) continue;
if (referencesBracketMatch(descendant.teamASource, bracketMatch.bracketMatchId)) {
if (
referencesBracketMatch(
descendant.teamASource,
bracketMatch.bracketMatchId,
)
) {
descendant.teamAIndex = undefined;
}
if (referencesBracketMatch(descendant.teamBSource, bracketMatch.bracketMatchId)) {
if (
referencesBracketMatch(
descendant.teamBSource,
bracketMatch.bracketMatchId,
)
) {
descendant.teamBIndex = undefined;
}
descendant.winnerTeamIndex = undefined;
@@ -351,9 +454,12 @@ function completeGrandFinal(
grandFinal.winnerTeamIndex !== winnerBracketTeamIndex
) {
bracket.resetFinalCreated = true;
const resetRule = seriesRule(1);
bracket.bracketMatches.push({
bracketMatchId: 'GF_RESET',
gameNumber: nextGameNumber(bracket),
gameCount: resetRule.gameCount,
requiredWins: resetRule.requiredWins,
bracketSide: 'reset-final',
roundNumber: 1,
matchNumber: 1,
@@ -418,118 +524,122 @@ function applySeedTeams(bracket: DoubleEliminationBracket): void {
}
}
function buildFourTeamBracketMatches(): DoubleEliminationBracketMatch[] {
function buildFourTeamBracketMatches(
options: BuildDoubleEliminationBracketOptions,
): DoubleEliminationBracketMatch[] {
return [
bracketMatch('WB_R1_M1', 1, 'winner', 1, 1, {
bracketMatch('WB_R1_M1', 1, 'winner', 1, 1, options, {
teamASource: seedSource(1),
teamBSource: seedSource(4),
winnerAdvancesTo: destination('WB_FINAL', 'A'),
loserAdvancesTo: destination('LB_R1_M1', 'A'),
}),
bracketMatch('WB_R1_M2', 2, 'winner', 1, 2, {
bracketMatch('WB_R1_M2', 2, 'winner', 1, 2, options, {
teamASource: seedSource(2),
teamBSource: seedSource(3),
winnerAdvancesTo: destination('WB_FINAL', 'B'),
loserAdvancesTo: destination('LB_R1_M1', 'B'),
}),
bracketMatch('WB_FINAL', 3, 'winner', 2, 1, {
bracketMatch('WB_FINAL', 3, 'winner', 2, 1, options, {
teamASource: winnerSource('WB_R1_M1'),
teamBSource: winnerSource('WB_R1_M2'),
winnerAdvancesTo: destination('GF', 'A'),
loserAdvancesTo: destination('LB_FINAL', 'B'),
}),
bracketMatch('LB_R1_M1', 4, 'loser', 1, 1, {
bracketMatch('LB_R1_M1', 4, 'loser', 1, 1, options, {
teamASource: loserSource('WB_R1_M1'),
teamBSource: loserSource('WB_R1_M2'),
winnerAdvancesTo: destination('LB_FINAL', 'A'),
}),
bracketMatch('LB_FINAL', 5, 'loser', 2, 1, {
bracketMatch('LB_FINAL', 5, 'loser', 2, 1, options, {
teamASource: winnerSource('LB_R1_M1'),
teamBSource: loserSource('WB_FINAL'),
winnerAdvancesTo: destination('GF', 'B'),
}),
bracketMatch('GF', 6, 'grand-final', 1, 1, {
bracketMatch('GF', 6, 'grand-final', 1, 1, options, {
teamASource: winnerSource('WB_FINAL'),
teamBSource: winnerSource('LB_FINAL'),
}),
];
}
function buildEightTeamBracketMatches(): DoubleEliminationBracketMatch[] {
function buildEightTeamBracketMatches(
options: BuildDoubleEliminationBracketOptions,
): DoubleEliminationBracketMatch[] {
return [
bracketMatch('WB_R1_M1', 1, 'winner', 1, 1, {
bracketMatch('WB_R1_M1', 1, 'winner', 1, 1, options, {
teamASource: seedSource(1),
teamBSource: seedSource(8),
winnerAdvancesTo: destination('WB_R2_M1', 'A'),
loserAdvancesTo: destination('LB_R1_M1', 'A'),
}),
bracketMatch('WB_R1_M2', 2, 'winner', 1, 2, {
bracketMatch('WB_R1_M2', 2, 'winner', 1, 2, options, {
teamASource: seedSource(4),
teamBSource: seedSource(5),
winnerAdvancesTo: destination('WB_R2_M1', 'B'),
loserAdvancesTo: destination('LB_R1_M1', 'B'),
}),
bracketMatch('WB_R1_M3', 3, 'winner', 1, 3, {
bracketMatch('WB_R1_M3', 3, 'winner', 1, 3, options, {
teamASource: seedSource(2),
teamBSource: seedSource(7),
winnerAdvancesTo: destination('WB_R2_M2', 'A'),
loserAdvancesTo: destination('LB_R1_M2', 'A'),
}),
bracketMatch('WB_R1_M4', 4, 'winner', 1, 4, {
bracketMatch('WB_R1_M4', 4, 'winner', 1, 4, options, {
teamASource: seedSource(3),
teamBSource: seedSource(6),
winnerAdvancesTo: destination('WB_R2_M2', 'B'),
loserAdvancesTo: destination('LB_R1_M2', 'B'),
}),
bracketMatch('WB_R2_M1', 5, 'winner', 2, 1, {
bracketMatch('WB_R2_M1', 5, 'winner', 2, 1, options, {
teamASource: winnerSource('WB_R1_M1'),
teamBSource: winnerSource('WB_R1_M2'),
winnerAdvancesTo: destination('WB_FINAL', 'A'),
loserAdvancesTo: destination('LB_R2_M2', 'B'),
}),
bracketMatch('WB_R2_M2', 6, 'winner', 2, 2, {
bracketMatch('WB_R2_M2', 6, 'winner', 2, 2, options, {
teamASource: winnerSource('WB_R1_M3'),
teamBSource: winnerSource('WB_R1_M4'),
winnerAdvancesTo: destination('WB_FINAL', 'B'),
loserAdvancesTo: destination('LB_R2_M1', 'B'),
}),
bracketMatch('WB_FINAL', 7, 'winner', 3, 1, {
bracketMatch('WB_FINAL', 7, 'winner', 3, 1, options, {
teamASource: winnerSource('WB_R2_M1'),
teamBSource: winnerSource('WB_R2_M2'),
winnerAdvancesTo: destination('GF', 'A'),
loserAdvancesTo: destination('LB_FINAL', 'B'),
}),
bracketMatch('LB_R1_M1', 8, 'loser', 1, 1, {
bracketMatch('LB_R1_M1', 8, 'loser', 1, 1, options, {
teamASource: loserSource('WB_R1_M1'),
teamBSource: loserSource('WB_R1_M2'),
winnerAdvancesTo: destination('LB_R2_M1', 'A'),
}),
bracketMatch('LB_R1_M2', 9, 'loser', 1, 2, {
bracketMatch('LB_R1_M2', 9, 'loser', 1, 2, options, {
teamASource: loserSource('WB_R1_M3'),
teamBSource: loserSource('WB_R1_M4'),
winnerAdvancesTo: destination('LB_R2_M2', 'A'),
}),
bracketMatch('LB_R2_M1', 10, 'loser', 2, 1, {
bracketMatch('LB_R2_M1', 10, 'loser', 2, 1, options, {
teamASource: winnerSource('LB_R1_M1'),
teamBSource: loserSource('WB_R2_M2'),
winnerAdvancesTo: destination('LB_R3_M1', 'A'),
}),
bracketMatch('LB_R2_M2', 11, 'loser', 2, 2, {
bracketMatch('LB_R2_M2', 11, 'loser', 2, 2, options, {
teamASource: winnerSource('LB_R1_M2'),
teamBSource: loserSource('WB_R2_M1'),
winnerAdvancesTo: destination('LB_R3_M1', 'B'),
}),
bracketMatch('LB_R3_M1', 12, 'loser', 3, 1, {
bracketMatch('LB_R3_M1', 12, 'loser', 3, 1, options, {
teamASource: winnerSource('LB_R2_M1'),
teamBSource: winnerSource('LB_R2_M2'),
winnerAdvancesTo: destination('LB_FINAL', 'A'),
}),
bracketMatch('LB_FINAL', 13, 'loser', 4, 1, {
bracketMatch('LB_FINAL', 13, 'loser', 4, 1, options, {
teamASource: winnerSource('LB_R3_M1'),
teamBSource: loserSource('WB_FINAL'),
winnerAdvancesTo: destination('GF', 'B'),
}),
bracketMatch('GF', 14, 'grand-final', 1, 1, {
bracketMatch('GF', 14, 'grand-final', 1, 1, options, {
teamASource: winnerSource('WB_FINAL'),
teamBSource: winnerSource('LB_FINAL'),
}),
@@ -542,11 +652,18 @@ function bracketMatch(
bracketSide: DoubleEliminationBracketSide,
roundNumber: number,
matchNumber: number,
options: BuildDoubleEliminationBracketOptions,
params: Partial<DoubleEliminationBracketMatch>,
): DoubleEliminationBracketMatch {
const rule = resolveDoubleEliminationSeriesRule(
{ bracketMatchId, bracketSide, roundNumber },
options,
);
return {
bracketMatchId,
gameNumber,
gameCount: params.gameCount ?? rule.gameCount,
requiredWins: params.requiredWins ?? rule.requiredWins,
bracketSide,
roundNumber,
matchNumber,
@@ -627,14 +744,35 @@ function assertSeedChangeAllowed(bracket: DoubleEliminationBracket): void {
}
}
function assertSupportedTeamCount(teamCount: number): asserts teamCount is 4 | 8 {
function assertSupportedTeamCount(
teamCount: number,
): asserts teamCount is 4 | 8 {
if (teamCount !== 4 && teamCount !== 8) {
throw new Error('Double elimination supports only 4 or 8 teams.');
}
}
function nextGameNumber(bracket: DoubleEliminationBracket): number {
return Math.max(...bracket.bracketMatches.map((match) => match.gameNumber)) + 1;
return (
Math.max(...bracket.bracketMatches.map((match) => match.gameNumber)) + 1
);
}
function seriesRule(gameCount: number): DoubleEliminationSeriesRule {
const normalizedGameCount = normalizeSeriesGameCount(gameCount);
return {
gameCount: normalizedGameCount,
requiredWins: requiredWinsForGameCount(normalizedGameCount),
};
}
function normalizeSeriesGameCount(gameCount: number | undefined): number {
if (!Number.isInteger(gameCount) || !gameCount || gameCount < 1) return 1;
return gameCount % 2 === 0 ? gameCount + 1 : gameCount;
}
function requiredWinsForGameCount(gameCount: number): number {
return Math.floor(gameCount / 2) + 1;
}
function cloneBracket(
@@ -660,10 +798,7 @@ function cloneBracket(
};
}
function shuffleInPlace<T>(
items: T[],
rng: () => number = Math.random,
): T[] {
function shuffleInPlace<T>(items: T[], rng: () => number = Math.random): T[] {
for (let index = items.length - 1; index > 0; index -= 1) {
const swapIndex = Math.floor(rng() * (index + 1));
[items[index], items[swapIndex]] = [items[swapIndex], items[index]];