Leaderboards and Stats Projections
Relevant source files
The following files were used as context for generating this wiki page:
- src/osu_server/domain/scores/leaderboards.py
- src/osu_server/services/commands/scores/user_stats_projection.py
- src/osu_server/repositories/interfaces/commands/beatmap_leaderboards.py
- src/osu_server/repositories/sqlalchemy/queries/beatmap_leaderboards.py
- src/osu_server/repositories/sqlalchemy/queries/user_stats.py
- src/osu_server/services/commands/scores/submit_score.py
The Leaderboards and Stats Projections system in Athena is responsible for managing, calculating, and persisting user performance data and beatmap-specific rankings. This system ensures that every submitted score is correctly attributed to the user's global profile and reflected in the appropriate beatmap leaderboard scopes. It operates across several layers, including domain policies for ranking logic, command services for updating state, and query repositories for high-performance data retrieval.
The architecture follows a clear separation between Command (write) and Query (read) operations. Commands handle the business logic of score submission and the subsequent updates to "projections"—pre-calculated statistics like total score, accuracy, and rank. Queries focus on efficiently fetching these projections for display to the user, supporting various leaderboard categories such as Global, Friends, and Country.
Sources: src/osu_server/domain/scores/leaderboards.py, src/osu_server/services/commands/scores/submit_score.py, src/osu_server/repositories/sqlalchemy/queries/user_stats.py
Core Data Structures and Policies
Score Ranking Logic
Ranking is determined by the ScoreRankKey, which defines the sorting priority for scores. The primary sorting criterion is the total score (descending), followed by the submission timestamp (ascending), and finally the internal score ID (ascending) to break ties.
Sources: src/osu_server/domain/scores/leaderboards.py:20-39
Leaderboard Scopes and Filters
Leaderboards are segmented by "Scopes" and "Filters". A scope identifies a specific context (Beatmap ID, Ruleset, Playstyle), while a mod filter key allows for filtering scores based on specific mod combinations (e.g., Global vs. Selected Mods).
| Component | Description |
|---|---|
ALL_MODS_FILTER_KEY | Constant representing the global leaderboard regardless of mods (Value: None). |
NO_MOD_FILTER_KEY | Constant for leaderboards specifically filtering for no gameplay-altering mods (Value: 0). |
LeaderboardModFilter | Normalizes a ModCombination into a canonical key for database lookup. |
LeaderboardScope | Defines the dimensions (Beatmap, Ruleset, Playstyle) for a leaderboard. |
Sources: src/osu_server/domain/scores/leaderboards.py:12-18, 42-77
Score Submission and Projection Updates
When a score is submitted, the SubmitScoreUseCase initiates a transaction that persists the score and triggers updates to relevant projections. This process includes calculating PersonalBestDelta and updating the user's overall statistics.
Submission Flow
The system generates "Projections" into multiple leaderboard scopes for a single score submission. For instance, a score with "Double Time" might be projected into both the "All Mods" and "Double Time" filter keys if it represents the user's best performance in those categories.
The flow of score submission involving projection updates to beatmap leaderboards and user statistics.
Sources: src/osu_server/services/commands/scores/submit_score.py:84-142
User Stats Projection Calculation
User statistics are aggregated from a user's best performance rows across different beatmaps. The build_current_user_stats_projection function calculates weighted accuracy and total hit counts based on the UserPerformanceBest data.
Sources: src/osu_server/services/commands/scores/user_stats_projection.py:12-70
Query Architecture
The query side utilizes optimized SQL views and subqueries to provide real-time leaderboard data. The SQLAlchemyBeatmapLeaderboardQueryRepository handles the retrieval of top rows and personal bests for specific scopes.
Leaderboard Category Logic
Leaderboards support several categories, each with specific visibility and availability rules:
- Global: Top scores across the entire server.
- Selected Mods: Scores filtered by specific mod combinations.
- Friends: Filtered to only include the viewer's friends.
- Country: Filtered by the user's country code.
Sources: src/osu_server/repositories/sqlalchemy/queries/beatmap_leaderboards.py:228-243
Performance and Visibility Filtering
The query repository applies strict filtering to ensure data integrity and privacy:
- Status Check: Only beatmaps with specific statuses (Ranked, Approved, Loved, Qualified) display leaderboards.
- Privacy: Users must have the
LEADERBOARD_VISIBLEprivilege to appear on public leaderboards. - Score Validity: Only passed scores that were eligible at the time of submission are included.
Entity Relationship diagram showing how scores link to beatmap leaderboard projections and overall user statistics.
Sources: src/osu_server/repositories/sqlalchemy/queries/beatmap_leaderboards.py:68-154, src/osu_server/repositories/sqlalchemy/queries/user_stats.py:171-209
Implementation Details
User Stats Source Retrieval
The SQLAlchemyUserStatsQueryRepository performs a complex batch read of stats sources. It first identifies known user IDs and then either fetches pre-calculated projections or falls back to raw score aggregation if the projection is missing.
# src/osu_server/repositories/sqlalchemy/queries/user_stats.py:73-95
requested_projection_rows = _mapping_rows(
(
await session.execute(
_requested_projection_statement(
tuple(known_user_ids),
ruleset=ruleset,
playstyle=playstyle,
)
)
)
.mappings()
.all()
)
Sources: src/osu_server/repositories/sqlalchemy/queries/user_stats.py:73-95
Ranked Candidate Subquery
The beatmap leaderboard query uses a ranked_candidates_subquery which performs a row_number() window function to calculate the rank of each score within the requested scope on the fly.
Sources: src/osu_server/repositories/sqlalchemy/queries/beatmap_leaderboards.py:68-154
Summary
The Leaderboards and Stats Projections module provides the backbone for competitive play in Athena. By utilizing a projection-based approach, the system balances the need for complex, multi-dimensional ranking logic with the performance requirements of a real-time game server. The use of domain-driven policies ensures that ranking remains consistent, while the repository patterns provide a scalable way to handle large volumes of score data.