Performance Points Engine

Relevant source files

The following files were used as context for generating this wiki page:

• src/osu_server/domain/scores/performance.py
• src/osu_server/infrastructure/performance/rosu_calculator.py
• src/osu_server/services/commands/scores/performance/execute_calculation.py
• src/osu_server/repositories/sqlalchemy/models/score_performance.py
• src/osu_server/services/commands/scores/process_submission.py
• tests/unit/domain/scores/test_performance.py
• tests/unit/infrastructure/performance/test_rosu_calculator.py

The Performance Points (PP) Engine is a specialized subsystem within Athena responsible for calculating the skill-based value of osu! scores. It handles the lifecycle of performance calculations, starting from initial score submission, through asynchronous worker processing, and finally updating user statistics and leaderboards. The engine is designed to be decoupled from specific client protocols, supporting both legacy osu!stable and modern lazer-style scoring through unified domain policies.

The engine follows a two-process model where score intake occurs in the main application process, while heavy PP calculations and leaderboard projections are offloaded to dedicated worker processes via taskiq. This ensures that the high-computational cost of difficulty calculation (using the rosu-pp-py library) does not block real-time communication with game clients.

Sources: README.md, AGENTS.md, src/osu_server/domain/scores/performance.py:1-20

Architecture and Data Flow

The PP Engine operates as a state-driven workflow. When a score is submitted, the engine evaluates eligibility, creates a pending calculation record, and signals workers to process the job. The calculation result is then used to refresh the user's personal best on specific beatmaps and update their global statistics.

High-Level Workflow

The diagram shows the transition from a submitted score to the final update of user statistics.
Sources: src/osu_server/services/commands/scores/process_submission.py:455-520, src/osu_server/services/commands/scores/performance/execute_calculation.py:50-150

Domain Policies and Eligibility

Not all scores are eligible for Performance Points. The PerformanceEligibilityPolicy defines strict rules based on game playstyle, beatmap status, and score outcome.

Eligibility Criteria

• Passed Scores Only: Failed scores are explicitly excluded from PP calculations.
• Vanilla Playstyle: Currently, only "Vanilla" playstyle is supported. Scores using RELAX or AUTOPILOT mods are marked ineligible.
• Ranked/Approved Status: PP is only granted for beatmaps with RANKED or APPROVED status. LOVED or QUALIFIED maps are currently out of scope.
• Leaderboard Eligibility: The score must be eligible for leaderboards at the time of submission.

Sources: src/osu_server/domain/scores/performance.py:126-155, tests/unit/domain/scores/test_performance.py:145-190

Formula Profiles

The engine uses FormulaProfile to manage different scoring versions. This allows the server to handle legacy vanilla ranking alongside newer formula iterations.

Profile	Description
LEGACY_VANILLA_RANKED	Historical vanilla ranking formula.
VANILLA_RANKED	Current active vanilla ranking version (v1).

Sources: src/osu_server/domain/scores/performance.py:73-80

Data Models and Persistence

Performance calculations are persisted in the score_performance_calculations table. The engine tracks the lifecycle of each calculation using a state machine.

Performance Calculation States

State	Description
QUEUED	Initial state after submission; awaiting worker pickup.
FETCHING_FILE	Worker has claimed the job and is retrieving the .osu file.
CALCULATING	Worker is actively processing the PP value.
COMPLETED	Calculation successful; PP and Star Rating are stored.
UNAVAILABLE	Calculation failed (e.g., corrupt map or invalid input).
SUPERSEDED	Calculation is no longer current (e.g., due to a recalculation batch).

Sources: src/osu_server/domain/scores/performance.py:23-45, src/osu_server/repositories/sqlalchemy/models/score_performance.py:44-65

Recalculation Infrastructure

For server-wide changes (e.g., PP reworks), the engine provides PerformanceRecalculationBatch and PerformanceRecalculationWorkItem models. These allow operators to queue large-scale recalculations across specific filters (e.g., all scores on a specific ruleset).

Sources: src/osu_server/domain/scores/performance.py:92-123, src/osu_server/repositories/sqlalchemy/models/score_performance.py:100-145

Infrastructure: Rosu Calculator

The concrete implementation of PP calculation is handled by the RosuPerformanceCalculator, which acts as an adapter for the rosu-pp-py library.

Calculation Logic

1. Input Validation: Verifies that hit counts (300s, 100s, 50s, misses) and accuracy are non-negative and within valid ranges.
2. Beatmap Parsing: Loads the raw .osu file bytes into a rosu.Beatmap object.
3. Ruleset Conversion: If the score's ruleset differs from the beatmap's native ruleset (e.g., playing a Taiko map on Osu! ruleset), the calculator performs the conversion.
4. Performance Calculation: Applies mods, accuracy, and combo to calculate the resulting PP and Star Rating.

# Simplified flow in RosuPerformanceCalculator
def calculate(self, input_data: PerformanceCalculatorInput) -> PerformanceCalculatorResult:
    # 1. Validate hits and accuracy
    # 2. Parse beatmap content
    beatmap = rosu.Beatmap(content=input_data.osu_file_bytes)
    # 3. Calculate based on score attributes
    attributes = rosu.Performance(
        mods=input_data.score.mods.to_persistence_bitmask(),
        accuracy=input_data.score.accuracy * 100.0,
        combo=input_data.score.max_combo,
        n300=input_data.score.n300,
        # ... other hits
    ).calculate(beatmap)
    return PerformanceCalculatorCompleted(pp=Decimal(str(attributes.pp)), ...)

Sources: src/osu_server/infrastructure/performance/rosu_calculator.py:30-115, tests/unit/infrastructure/performance/test_rosu_calculator.py:65-95

Execution Workflow

The ExecutePerformanceCalculationUseCase manages the worker-side orchestration.

Job Execution Sequence

The sequence demonstrates how the worker transitions through database states while interacting with the file provider and calculator.
Sources: src/osu_server/services/commands/scores/performance/execute_calculation.py:50-250

Error Handling and Unavailability

If a calculation cannot be completed, the engine marks it as UNAVAILABLE with a specific reason:

• BEATMAP_PARSE_FAILED: The .osu file was corrupt or not an osu! file.
• BEATMAP_CONVERT_FAILED: Conversion between rulesets failed.
• CALCULATOR_INPUT_INVALID: Score data (e.g., negative accuracy) was rejected by the calculator.
• CALCULATOR_EXECUTION_FAILED: An unexpected error occurred within the rosu-pp-py library.

Sources: src/osu_server/infrastructure/performance/rosu_calculator.py:70-110, src/osu_server/services/commands/scores/performance/execute_calculation.py:270-300

Summary

The Performance Points Engine provides a robust, asynchronous, and state-managed environment for osu! score evaluation. By combining the high-performance rosu-pp-py calculator with a reliable state machine and task queue, Athena ensures that performance data is calculated accurately and efficiently without impacting game-client responsiveness. The system remains extensible for future scoring updates through its FormulaProfile and recalculation batch infrastructure.