♟️ Chess Matchmaker - Tournament Scheduler

Chess Matchmaker generates tournament schedules using different formats:

• Round Robin (Everyone plays against everyone)
• Rating-Based Groups (Players are grouped based on their rating and play Round Robin)
• Knockout (Single-elimination matches until a winner is determined)

This package automatically handles an odd number of players by adding a BYE when necessary.

Installation

You can use it in two ways:

1️⃣ Import functions in your project

2️⃣ Use the CLI directly from the terminal

Using as a Library in Your Project

npm install chess-matchmaker

Or with yarn:

yarn add chess-matchmaker

After installing, you can import the functions like this:

import { roundRobin, ratingBasedGroups, knockout } from 'chess-matchmaker';

1️⃣ Round Robin

Every player plays against every other player exactly once.

Example Input:

const players = ['Alice', 'Bob', 'Charlie'];
const schedule = roundRobin(players);

Example Output:

[
  {
    round: 1,
    matches: [
      { gameNumber: 1, player1: 'Alice', player2: 'Bob' },
      { gameNumber: 2, player1: 'Charlie', player2: 'BYE' },
    ],
  },
  {
    round: 2,
    matches: [
      { gameNumber: 3, player1: 'Alice', player2: 'Charlie' },
      { gameNumber: 4, player1: 'Bob', player2: 'BYE' },
    ],
  },
  {
    round: 3,
    matches: [
      { gameNumber: 5, player1: 'Bob', player2: 'Charlie' },
      { gameNumber: 6, player1: 'Alice', player2: 'BYE' },
    ],
  },
];

2️⃣ Rating-Based Groups

Players are grouped by their rating and play Round Robin within their group. Groups are balanced so that they have a similar number of players.

Example Input:

const players = [
  { name: 'Alice', rating: 1800 },
  { name: 'Bob', rating: 1700 },
  { name: 'Charlie', rating: 1600 },
  { name: 'David', rating: 1500 },
];
const schedule = ratingBasedGroups(players, 2);

Example Output:

{
  groups: [
    [ { name: "Alice", rating: 1800 }, { name: "Bob", rating: 1700 } ],
    [ { name: "Charlie", rating: 1600 }, { name: "David", rating: 1500 } ]
  ],
  rounds: [
    {
      round: 1,
      matches: [
        { gameNumber: 1, player1: "Alice", player2: "Bob" },
        { gameNumber: 2, player1: "Charlie", player2: "David" }
      ]
    },
    {
      round: 2,
      matches: [
        { gameNumber: 3, player1: "Alice", player2: "BYE" },
        { gameNumber: 4, player1: "Charlie", player2: "BYE" }
      ]
    }
  ]
}

3️⃣ Knockout Tournament Players compete in 1v1 matches. Winners advance to the next round.

Example Input:

const players = ['Alice', 'Bob', 'Charlie', 'David'];
const schedule = knockout(players);

Example Output:

[
  {
    round: 1,
    matches: [
      { gameNumber: 1, player1: 'Alice', player2: 'Bob' },
      { gameNumber: 2, player1: 'Charlie', player2: 'David' },
    ],
  },
  {
    round: 2,
    matches: [{ gameNumber: 3, player1: 'Winner Game 1', player2: 'Winner Game 2' }],
  },
];

Using the CLI

You can run the Chess Matchmaker CLI to generate a tournament schedule without writing code.

npm install -g chess-matchmaker

Or with yarn:

yarn global add chess-matchmaker