Real-Time Game Leaderboard

Welcome to the Real-Time Leaderboard Series, where you'll build a dynamic ranking system using the Elo rating system. In this project, your task is to implement a real-time leaderboard that not only ranks players based on their performance but also tracks additional metrics like current ranking, best-ever ranking, and match history.

The Elo system dynamically adjusts player rankings based on match outcomes, making it ideal for competitive environments. This project will help you explore the mechanics of the Elo system while implementing features to track player progression and maintain a fair and responsive leaderboard.

---

What is an Elo Rating System?

The Elo rating system is a method for calculating the relative skill levels of players in a two-player game. It adjusts each player’s rating based on the outcome of matches, factoring in the skill difference between the players. Here's how it works:

1. Core Mechanics

• Initial Ratings: Every player starts with a default rating (e.g., 1000).
• Expected Outcome: The system calculates the probability of each player winning based on their current ratings.
• Rating Adjustment: After a match, the winner gains points, and the loser loses points. The amount depends on the match outcome and the expected outcome.

2. Key Formulas

• Expected Score:
  The expected score of Player A is calculated using the formula:

  $E_A = \frac{1}{1 + 10^{\frac{(R_B - R_A)}{400}}}$

  Where:

  • $E_A$: Expected score of Player A.
  • $R_A$: Current rating of Player A.
  • $R_B$: Current rating of Player B.

• Rating Update:
  After a match, the new rating of Player A is calculated using the formula:

  $R_A' = R_A + K \times (S_A - E_A)$

  Where:

  • $R_A'$: New rating of Player A.
  • $K$: Adjustment factor (e.g., 32 for regular players, 16 for high-rated players).
  • $S_A$: Actual score of Player A (1 for win, 0 for loss).

---

Example

• Player A has a rating of 1200, and Player B has a rating of 1000.

• The expected scores are calculated as follows:

  • $E_A = \frac{1}{1 + 10^{\frac{(1000 - 1200)}{400}}} \approx 0.76$
  • $E_B = \frac{1}{1 + 10^{\frac{(1200 - 1000)}{400}}} \approx 0.24$

• If Player A wins:

  • $R_A' = 1200 + 32 \times (1 - 0.76) = 1207.68$
  • $R_B' = 1000 + 32 \times (0 - 0.24) = 992.32$

Key Features:

1. Dynamic Adjustments: Players gain or lose points depending on whether they exceed or fall short of expected performance.
2. Relative Rankings: Higher-rated players lose fewer points to lower-rated opponents and vice versa.
3. Metrics Tracking: Tracks additional data like rank progression, best-ever rank, and total matches played.

---

Metrics for Each Player

In addition to the Elo rating, you’ll track these metrics for each player:

• Current Rating: The player’s latest Elo rating.
• Current Rank: The player’s position on the leaderboard.
• Best Ever Rating: The highest rating the player has achieved.
• Best Ever Rank: The highest rank the player has held.
• Total Matches Played: The total number of matches played by the player.
• Win/Loss Record: Number of wins and losses for the player.

---

API Specification

You need to implement a REST API with the following routes:

1. Add/Update Player

• Endpoint: POST /players
• Request Body:

  {
    "name": "string", // Player's name
    "rating": integer // Initial rating
  }

• Response:

  {
    "message": "Player added/updated successfully.",
    "player": {
          "id": integer,
           ... you can optionally return other fields or not
     }
  }

• Functionality:
  • Adds a new player or updates an existing player.
  • If no rating is provided, defaults to 1000.
  • Initializes metrics like matches played, win/loss record, and best-ever ranking.

2. Report Match

• Endpoint: POST /matches
• Request Body:

  {
    "winnerId": "string", // ID of the winning player
    "loserId": "string",  // ID of the losing player
    "kFactor": integer    // Adjustment factor (optional, defaults to 32)
  }

• Response:

  {
    "message": "Match processed successfully.",
    "winnerRating":integer,
    "loserRating":integer,
  }

• Functionality:
  • Adjusts Elo ratings for both players based on the match outcome.
  • Updates player metrics:
    • Increments matches played for both players.
    • Updates win/loss record.
    • Tracks best-ever rating and best-ever rank.

3. Retrieve Leaderboard

• Endpoint: GET /leaderboard
• Query Parameters:
  • limit: Number of top players to retrieve (optional).
• Response:

  {
    "leaderboard": [
      {
        "id": "string",
        "name": "string",
        "totalGames": integer,
        "wins": integer,
        "losses": integer,
        "rating": integer,
        "bestRating": integer,
        "rank": integer,
        "bestRank": integer,
      }
    ]
  }

• Functionality:
  • Returns the leaderboard sorted by current ratings in descending order.
  • Optionally limits the number of players in the response.

4. Retrieve Player Metrics

• Endpoint: GET /players/:id

• Response:

  {
    "id": "string",
    "name": "string",
    "totalGames": integer,
    "wins": integer,
    "losses": integer,
    "rating": integer,
    "bestRating": integer,
    "rank": integer,
    "bestRank": integer
  }

• Functionality:

  • Retrieves detailed metrics for a specific player.

---

Constraints

• Player Count: The system must support up to 1 million players.
• Matches: The system must handle up to 10,000 match updates per second.
• Metrics Tracking: Each player’s metrics should be updated in real time.
• Leaderboard Updates: Rankings and metrics must dynamically adjust after every match.

Summary

This project builds a real-time Elo-based leaderboard with player-specific metrics, enabling dynamic ranking and progress tracking. By implementing this system, you'll gain hands-on experience with ranking algorithms, real-time updates, and REST API design. This foundational project sets the stage for adding advanced features such as matchmaking, regional leaderboards, and time-based ranking decay.