Direct Encounter

Direct Encounter computes the Direct Encounter tiebreak — a FIDE method that compares players' scores from games played only against each other — following the FIDE Tiebreak Regulations (section 6). TypeScript, zero runtime dependencies.

Installation

npm install @echecs/direct-encounter
Copy

Quick Start

import { directEncounter } from '@echecs/direct-encounter';
import type { Game, GameKind, Player } from '@echecs/direct-encounter';

// Players A, B, C are tied on points
const players = [{ id: 'A' }, { id: 'B' }, { id: 'C' }];
// games[n] = round n+1; Game has no `round` field
const games: Game[][] = [
  [{ black: 'B', result: 1, white: 'A' }], // round 1
  [{ black: 'C', result: 0.5, white: 'A' }], // round 2
  [{ black: 'C', result: 0, white: 'B' }], // round 3
];

const score = directEncounter('A', games, players);
// Returns A's score from games played against other tied players (B and C)
Copy

API

directEncounter(playerId, games, players)

directEncounter(playerId: string, games: Game[][], players: Player[]): number
Copy

Returns the total points playerId scored against the players in the players array (the tied group). Pass the subset of players who share the same tournament score as playerId.

Round order follows array position: games[0] = round 1, games[1] = round 2, etc. The optional kind?: GameKind field identifies unplayed rounds ('forfeit-loss' | 'forfeit-win' | 'full-bye' | 'half-bye' | 'pairing-bye' | 'zero-bye'); the function excludes all byes from the score.

Per the FIDE C.07 6.1.1 default, forfeit encounters are excluded from the Direct Encounter score. Use the /forfeits subpath export to include them.

Also exported as tiebreak — an alias for directEncounter:

import { tiebreak } from '@echecs/direct-encounter';
Copy

When all tied players have identical Direct Encounter scores (the common case in Swiss), this tiebreak is inconclusive. Apply the next tiebreak in the ordering.

Types

import type { Game, GameKind, Player, Result } from '@echecs/direct-encounter';
Copy

Type	Shape / Values
Player	{ id: string }
Result	0 | 0.5 | 1
Game	{ black: string; white: string; result: Result; kind?: GameKind }
GameKind	'forfeit-loss' | 'forfeit-win' | 'full-bye' | 'half-bye' | 'pairing-bye' | 'zero-bye'

/forfeits subpath export

import {
  directEncounterForfeits,
  tiebreak,
} from '@echecs/direct-encounter/forfeits';
Copy

FIDE C.07 6.1.1 (included variant) — Direct Encounter including forfeit encounters. Identical to the base directEncounter, except that encounters forfeited by a tied opponent count towards the score instead of being excluded.

tiebreak is an alias for directEncounterForfeits.

Contributing

Contributions are welcome. Please open an issue at github.com/echecsjs/direct-encounter/issues.