Beatmap Management

Relevant source files

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

• src/osu_server/domain/beatmaps/models.py
• src/osu_server/repositories/sqlalchemy/models/beatmap.py
• src/osu_server/repositories/sqlalchemy/commands/beatmaps.py
• src/osu_server/services/queries/beatmaps/mirror.py
• src/osu_server/repositories/interfaces/commands/beatmaps.py
• src/osu_server/config.py

Beatmap Management in Athena encompasses the lifecycle of beatmap metadata and file synchronization, status enforcement, and eligibility logic for scoring. The system is designed to handle metadata from multiple sources (official osu! APIs and community mirrors) while allowing local administrative overrides to determine how beatmaps behave on the private server.

The architecture separates the core domain language (statuses, freshness, and eligibility) from the persistence and transport layers. It utilizes a background worker pattern for fetching and refreshing data, ensuring that the main application remains responsive even when synchronization is required.
Sources: src/osu_server/domain/beatmaps/models.py, AGENTS.md:145-155

Core Data Models

The system distinguishes between a BeatmapSet (the collection) and a Beatmap (individual difficulty). These models track technical metadata, official status, and local state.

Beatmap Hierarchy and Relationships

The following diagram illustrates the relationship between beatmap sets, individual beatmaps, and their physical file attachments stored as blobs.

A visual representation of the beatmap data hierarchy and its connection to storage.
Sources: src/osu_server/repositories/sqlalchemy/models/beatmap.py:16-118

Model Fields and Descriptions

Entity	Field	Type	Description
Beatmap	id	Integer	Unique identifier (osu! beatmap ID).
	checksum_md5	String(32)	MD5 hash of the beatmap file.
	official_status	Enum	Status reported by official sources.
	local_status_override	Enum	Athena-specific status override.
	difficulty_rating	Decimal	Calculated difficulty (star rating).
BeatmapSet	id	Integer	Unique identifier (osu! set ID).
	artist / title	String	Music and map identification.
	official_status	Enum	Set-wide status.

Sources: src/osu_server/domain/beatmaps/models.py:75-108, src/osu_server/repositories/sqlalchemy/models/beatmap.py:53-83

Status and Eligibility Logic

Athena utilizes a dual-status system: official_status (derived from providers) and local_status_override (set by server operators). The effective_status is determined by prioritizing the local override if present.

Status Transitions and Mapping

Statuses are mapped from external providers into canonical internal enums.

How external statuses are ingested and resolved against local server overrides.
Sources: src/osu_server/domain/beatmaps/models.py:112-117, src/osu_server/domain/beatmaps/models.py:133-145

Eligibility Requirements

Beatmap eligibility determines if a map can accept scores or award Performance Points (PP). The BeatmapEligibility object is projected based on the effective_status and verification source.

• PP Awarding: Only RANKED or APPROVED maps typically award ranked PP. LOVED maps award loved PP.
• Mirror Trust: If the source is a mirror and beatmap_mirror_trust_policy is set to "untrusted", eligibility may be restricted.
• Verification: official_status_verified tracks whether the metadata is confirmed from an official source.

Sources: src/osu_server/domain/beatmaps/models.py:270-284, src/osu_server/config.py:100-110

Metadata Freshness and Synchronization

Beatmaps are synchronized using a background fetch system. The BeatmapFreshnessPolicy determines when a cached record is "stale" and requires a refresh.

Freshness Intervals

The system uses configurable intervals (in seconds) to check for updates based on the map's status.

Status Category	Config Key	Default
Ranked/Approved	beatmap_ranked_refresh_interval_seconds	2,592,000 (30 days)
Pending/WIP	beatmap_pending_refresh_interval_seconds	86,400 (1 day)
Graveyard	beatmap_graveyard_refresh_interval_seconds	604,800 (7 days)
Mirror Sources	beatmap_mirror_refresh_interval_seconds	86,400 (1 day)

Sources: src/osu_server/config.py:116-121, src/osu_server/domain/beatmaps/models.py:218-265

Synchronization Flow

The synchronization process involves claiming a "fetch lock" via try_mark_fetch_pending to prevent redundant worker tasks.

The sequence of events for detecting stale metadata and fetching updates via background workers.
Sources: src/osu_server/repositories/sqlalchemy/commands/beatmaps.py:155-185, src/osu_server/services/queries/beatmaps/mirror.py

Repository Implementation

The SQLAlchemyBeatmapCommandRepository handles all persistence operations. It uses atomic PostgreSQL operations for critical state changes.

• Atomic Fetch Locking: try_mark_fetch_pending uses ON CONFLICT DO UPDATE ... WHERE status != 'pending_fetch' to ensure only one worker processes a target at a time.
• Submission Counts: increment_submission_counts atomically updates play_count and pass_count using an SQL UPDATE ... RETURNING statement.
• Checksum Integrity: save_beatmapset_snapshot performs explicit conflict checks to ensure a MD5 checksum is not assigned to multiple distinct beatmap IDs.

Sources: src/osu_server/repositories/sqlalchemy/commands/beatmaps.py:236-258, src/osu_server/repositories/sqlalchemy/commands/beatmaps.py:317-331

Code Snippet: Atomic Fetch Lock

# src/osu_server/repositories/sqlalchemy/commands/beatmaps.py:317-336
def _mark_fetch_pending_statement(target: BeatmapFetchTarget, now: datetime):
    insert_statement = insert(BeatmapFetchStateModel).values(
        target_type=target.target_type,
        target_key=target.target_key,
        status=BeatmapFetchState.PENDING_FETCH.value,
        # ... other fields
    )
    return insert_statement.on_conflict_do_update(
        index_elements=["target_type", "target_key"],
        set_={"status": "pending_fetch", "pending_since": now},
        where=BeatmapFetchStateModel.status != "pending_fetch"
    ).returning(BeatmapFetchStateModel.id)

Sources: src/osu_server/repositories/sqlalchemy/commands/beatmaps.py:317-336

Summary

Beatmap Management in Athena provides a robust framework for maintaining a localized beatmap database. By combining strict background synchronization policies with atomic database operations and a flexible status override system, it ensures data consistency while allowing server administrators full control over map availability and scoring eligibility.