Scoring System

PadelKit implements a robust Event Sourcing architecture for scoring, ensuring state consistency and enabling historical point tracking. This guide explores the core concepts of the scoring system.

Event Sourcing Architecture

Unlike simple counters that just keep track of the current points, PadelKit uses an Event Sourcing approach. This means the single source of truth for a match is the sequential list of points won by each team.

The MatchScoreHistory class stores these events and recalculates the complete score state instantly. This architecture provides several key advantages:

  1. No inconsistent states: You can never reach an invalid state (like a set score of 8-1) because the score is always deterministically calculated from the raw point history.
  2. Historical corrections: If a referee or player inputs a point for the wrong team, they can fix it at any time. By modifying a past event, the entire match score is automatically recalculated without breaking.
  3. Analytics ready: Having the exact sequence of points allows for advanced statistical analysis later on.

The Match Wrapper

While MatchScoreHistory deals with the mathematical sequence of padel scoring (games, sets, deuces, advantages), it does not care about the meta-rules of a specific tournament (e.g., "Is this match best of 3 or best of 5?").

For a complete application, you should use the Match class. The Match class acts as a wrapper that:

  • Contains the MatchScoreHistory instance.
  • Tracks Player and Team metadata (names, sides).
  • Defines the best_of_sets completion criteria.
  • Provides properties like is_completed and winner.

Match flow

concept
progression
from padelkit import Match, TeamId

# Initialize a standard best-of-3 sets match
match = Match()

# Add points through the history property
match.history.add_point(TeamId.A)
match.history.add_point(TeamId.B)

# Check if the match has been won
if match.is_completed:
    print(f"Match won by {match.winner.name}")
else:
    # Print the current score state
    print(match.history.get_current_score())

Modifying Past Points

One of the most powerful features of PadelKit is the ability to correct mistakes. If you realize that the point at index 15 was actually won by Team B instead of Team A, you can simply modify it:

Correction example

concept
correction
# A mistake was made early in the game
score = match.history.modify_point(15, TeamId.B)

# The new state is automatically recalculated
print(score)

Official & Alternative Scoring Formats

PadelKit supports multiple official and alternative scoring methods defined by the FIP (International Padel Federation) regulations. You can easily configure these when instantiating a Match or a MatchScoreHistory.

1. Advantage Method vs. Punto de Oro (Golden Point)

  • Advantage Method ("advantage"): The traditional tennis-style scoring. When the score reaches 40-40 (Deuce), a team must win two consecutive points (Advantage followed by Game Point) to win the game.
  • Punto de Oro ("gold_point"): A modern, high-stakes alternative. When the score reaches 40-40, a single decisive point decides the game. The receiving team chooses which side (deuce or ad) the server must serve to. In MatchScore, the property is_gold_point becomes True when this decisive point is active.
# Initialize a match with Punto de Oro (Golden Point)
match = Match(advantage_method="gold_point")

2. Set Formats: Standard vs. Mini Sets

  • Standard Sets ("standard"): A set is won by the first team to win 6 games with a margin of at least 2 games. If the score reaches 6-6, a 7-point tie-break is played.
  • Mini Sets ("mini"): A shorter format designed for faster matches. A set is won by the first team to win 4 games with a margin of at least 2 games. If the score reaches 4-4, a 7-point tie-break is played.
# Initialize a match using Mini Sets
match = Match(set_format="mini")

3. Deciding Set Formats

When sets are tied (e.g., 1-1 in a best-of-3 match), FIP regulations allow different methods to decide the final set:

  • Regular Set ("regular"): A full regular set is played (standard set to 6 games or mini set to 4 games, depending on set_format).
  • Match Tie-Break ("tiebreak"): A standard 7-point tie-break is played in place of the final set. In MatchScore, the property in_tiebreak becomes True during this tie-break.
  • Match Super Tie-Break ("super_tiebreak"): A 10-point super tie-break (requiring a 2-point margin) is played in place of the final set. In MatchScore, the property in_super_tiebreak becomes True during this super tie-break.
# Configure a match to be decided by a 10-point Super Tie-Break
match = Match(deciding_set_format="super_tiebreak")

Tie-Break Server Rotation Rules

During any tie-break (regular or match-deciding), PadelKit automatically manages the official server rotation rules:

  1. First Point: The first server of the tie-break serves 1 point from the right (deuce) court.
  2. Subsequent Points: The service alternates every 2 points. The next server serves from the left (ad) court for the first point and the right (deuce) court for the second point.
  3. Active Server Tracking: The active server and player can always be dynamically tracked using the server property on MatchScore (which returns a ServingState object containing both team and player).
# Check which team and player serve the 3rd point of a tie-break
score = match.history.get_current_score()
if score.server:
    print(f"Active server team: {score.server.team}")
    print(f"Active server player: {score.server.player.name}")

Was this page helpful?