Skip to main content

Multi-Sport Format Support

The ScoringEngine supports a wide range of scoring formats across multiple sports through the matchUpFormat code grammar. This page covers common format patterns and sport-specific examples.

Format String Grammar​

A matchUpFormat code describes the complete scoring structure of a match. The grammar follows a hierarchical pattern:

SET<count>[XA] - S:<setFormat>[/<tiebreakFormat>] [-F:<finalSetFormat>]

See the matchUpFormat Codes page for the full grammar specification.

Standard Tennis Formats​

Best of 3 Sets with Tiebreak at 6-6​

const engine = new ScoringEngine({ matchUpFormat: 'SET3-S:6/TB7' });
// 3 sets, games to 6, tiebreak at 6-6 to 7 points

Best of 5 Sets with Match Tiebreak in Final Set​

const engine = new ScoringEngine({ matchUpFormat: 'SET5-S:6/TB7-F:TB10' });
// 5 sets, tiebreak at 6-6, final set is a match tiebreak to 10

Best of 3 Sets, No-AD Scoring​

const engine = new ScoringEngine({ matchUpFormat: 'SET3-S:6NOAD/TB7' });
// No-advantage scoring: deciding point at deuce (receiver chooses side)
engine.isNoAd(); // true

Best of 3 Sets, No Final Set Tiebreak (Advantage Set)​

const engine = new ScoringEngine({ matchUpFormat: 'SET3-S:6/TB7-F:6' });
// Regular tiebreak in sets 1-2, advantage set (no tiebreak) in set 3
engine.hasFinalSetTiebreak(); // false

Tiebreak-Only Formats​

For sports like pickleball, badminton, squash, and table tennis where each "set" is a single tiebreak-style game played to a target number of points.

Pickleball (Best of 3, Games to 11)​

const engine = new ScoringEngine({ matchUpFormat: 'SET3-S:TB11' });
// 3 games to 11 points, win by 2
engine.getTiebreakAt(); // null (entire set is a tiebreak)

Badminton (Best of 3, Games to 21)​

const engine = new ScoringEngine({ matchUpFormat: 'SET3-S:TB21' });

Squash (Best of 5, Games to 11)​

const engine = new ScoringEngine({ matchUpFormat: 'SET5-S:TB11' });
engine.getSetsToWin(); // 3

Table Tennis (Best of 7, Games to 11)​

const engine = new ScoringEngine({ matchUpFormat: 'SET7-S:TB11' });
engine.getSetsToWin(); // 4

No-AD Tiebreak (Deciding Point)​

const engine = new ScoringEngine({ matchUpFormat: 'SET3-S:TB11NOAD' });
// At 10-10, next point wins (no requirement to win by 2)

Timed Formats​

For sports with timed segments (periods, halves, quarters).

Timed Periods with Points​

const engine = new ScoringEngine({ matchUpFormat: 'SET7XA-S:T10P' });
// 7 timed segments of 10 minutes each, points scored during segments
// XA = exactly all 7 segments played, A = aggregate scoring

After a timed segment ends:

// Points are added during play
engine.addPoint({ winner: 0 });
engine.addPoint({ winner: 1 });
engine.addPoint({ winner: 0 });

// When segment timer expires
engine.endSegment();
// Segment score is finalized, next segment begins

Consecutive Game Formats​

The -G:NC modifier indicates N consecutive games within a set, used by formats like TYPTI.

const engine = new ScoringEngine({ matchUpFormat: 'SET3-S:6/TB7-G:3C' });
// Standard tennis with 3 consecutive games per rotation

Aggregate Scoring​

The -A modifier switches from "first to win N sets" to "play all sets, aggregate total."

const engine = new ScoringEngine({ matchUpFormat: 'SET7XA-S:TB11' });
// Play all 7 sets, winner determined by aggregate point total across all sets

Sets won are not consulted. Every set must be recorded, and a tied total names no winner until a deciding point breaks it.

Exactly N Sets​

The X modifier means exactly N sets are played (no early termination).

const engine = new ScoringEngine({ matchUpFormat: 'SET7XA-S:T10P' });
// Exactly 7 segments, all played regardless of score

A non-aggregate exactly format is decided on sets won, but only once all N sets are recorded:

  • Reaching setsToWin before the last set is a lead, not a win. Five sets to side 1 in SET9X-S:T10 names no winner while four remain to play (since 7.6.0).
  • Once every set is played, the side with more sets wins, however many it took: a 3-0 sweep of SET3X-S:T10 is a win. A level count (2-2 in SET4X-S:T10) names no winner, so a score that names one is refused (since 7.5.0).
  • No set beyond N is recorded; a score with an extra set is refused (since 7.5.0).

An aggregate exactly format (XA) may record one set more than N: a level total goes to a sudden-death decider (-F:), which is set N + 1 and not one of the N sets (since 7.5.0).

Format Introspection​

The ScoringEngine provides methods to query format properties without parsing format strings manually:

const engine = new ScoringEngine({ matchUpFormat: 'SET3-S:6NOAD/TB7-F:TB10' });

engine.isNoAd(); // true — No-AD scoring
engine.getSetsToWin(); // 2 — best of 3
engine.getTiebreakAt(); // 6 — tiebreak at 6-6
engine.hasFinalSetTiebreak(); // true — final set is a match tiebreak
engine.getFormatStructure(); // Full parsed structure for advanced use

Mixed-Mode Input​

The ScoringEngine supports mixing input levels within the same match. This is useful when a tracker joins mid-match and needs to enter set scores for completed sets, then switch to point-by-point tracking.

const engine = new ScoringEngine({ matchUpFormat: 'SET3-S:6/TB7' });

// Enter completed sets
engine.addSet({ side1Score: 6, side2Score: 4 });
engine.addSet({ side1Score: 3, side2Score: 6 });

// Switch to point-by-point for the deciding set
engine.addPoint({ winner: 0 });
engine.addPoint({ winner: 1 });

engine.getInputMode(); // 'mixed'

The undo/redo system handles mixed-mode seamlessly — undoing through set boundaries works correctly regardless of how the score was entered.

Rotating-Partner Rally Totals​

Americano and Mexicano matches use one segment whose two scores add up to a fixed rally total:

CodeCompletion rule
SET1-S:P32Finish after 32 rallies; 16–16 is a completed tie.
SET1-S:P32DPFinish after 32 rallies, or one deciding rally if tied.
SET1-S:P32WB2Finish after 32 rallies; if tied, continue until a two-point margin.

These are combined totals, unlike a tiebreak's first-to target. Each rally increments side1Score or side2Score. Live getScore() displays numeric points and no tennis games; undo/redo replays the same completion rules. Supply server information explicitly. Multipliers and score increments other than one are unsupported for this segment.

generateRotatingPartnerRound assigns the format from the saved round scoring contract. Manual setMatchUpStatus refuses a conflicting format or illegal score even when generic score validation is disabled. A tied result uses COMPLETED without winningSide. Live completion fires onMatchTie for a tie and onMatchComplete for a winner. Individual standings and separate deciding-phase records are subsequent work.