Skip to main content
These commands allow referees to import match scores from various sources and generate statistical reports.

​
/importscores

Imports scores directly from an osu! multiplayer lobby using the osu! API.
​
osuLobbyId
string
required
The multiplayer lobby ID from osu! (e.g., “118575195”)
​
dbRoomId
string
required
The match ID in the database (e.g., “A1”, “Q1”)

​
Usage Example

/importscores osuLobbyId:118575195 dbRoomId:A1
This command:
  1. Fetches all game data from the osu! API for the specified lobby
  2. Matches beatmap IDs to the round’s map pool
  3. Matches osu! user IDs to internal database users
  4. Calculates grades based on score statistics
  5. Inserts all scores into the database
The osu! multiplayer lobby must be public for the API to access it. For private lobbies, use /importscores-privaterooms instead.
The command automatically:
  • Handles multiple games in a single lobby
  • Maps beatmaps to mod slots (NM1, HD2, etc.)
  • Caches user lookups for performance
  • Reports the total number of scores imported

​
/importscores-privaterooms

Manually imports scores from a CSV or TXT file for private lobbies.
​
matchId
string
required
The match ID in the database
​
file
Attachment
required
CSV or TXT file containing score data (attach using Discord file upload)

​
Usage Example

/importscores-privaterooms matchId:A1 file:[attach .csv or .txt]
The file must be in the format exported by osu! tournament client or match history. The parser expects comma-separated values with specific column positions:
  • Column 5: Beatmap ID
  • Column 7: osu! User ID
  • Column 9: Score
  • Column 10: Accuracy
  • Column 13: Max Combo
  • Column 18: Grade
Each line must start with the tournament name (configured in the server). Other lines are ignored.
The import process:
  1. Downloads the file from Discord
  2. Parses CSV format with quoted field support
  3. Validates match exists and retrieves round information
  4. Maps beatmap IDs to mod slots
  5. Maps osu! user IDs to internal users
  6. Saves all valid scores to the database
If beatmap IDs don’t match the round’s map pool, or if players aren’t registered in the database, those scores will be skipped.

​
/addmplinkid

Adds the osu! multiplayer lobby ID to a match record.
​
matchId
string
required
The match ID in the database
​
mpLinkId
string
required
The numeric MP link ID from osu!

​
Usage Example

/addmplinkid matchId:A1 mpLinkId:118575195
This associates the osu! lobby with the database match record. Required before using /importscores.
Find the MP link ID in the osu! multiplayer lobby URL: https://osu.ppy.sh/community/matches/[ID]

​
/matchups

Displays a paginated list of all matches.

​
Usage Example

/matchups
Shows:
  • Match ID
  • Team names (Red vs Blue)
  • Scheduled date and time
  • 5 matches per page with navigation buttons
See Referee Commands for full details.

​
/stats

Generates comprehensive statistics for a qualifier round using Z-sum normalization.
​
roundId
integer
required
The round ID to generate statistics for

​
Usage Example

/stats roundId:1
This command calculates:
  • Z-Sum: Normalized score across all maps (accounts for map difficulty variance)
  • Average Score: Raw score average across all plays
  • Map Rankings: Rank on each individual map
  • Per-map Statistics: Mean and standard deviation for each map
The output includes:
  • Embed showing top 10 players
  • Complete CSV file with all player statistics
  • Rankings sorted by Z-Sum (primary) and average score (secondary)

​
Z-Sum Calculation

For each player on each map: 
Z-Score = (Player Score - Map Average) / Map StdDev
Z-Sum = Sum of all Z-Scores across maps
This normalization ensures:
  • Harder maps don’t dominate the scoring
  • Consistent performance is rewarded
  • Outlier protection via standard deviation
The CSV includes detailed breakdowns showing rank and score for each map slot (NM1, HD1, HR2, DT3, etc.).

​
/preparescores

Admin only. Generates a seeding CSV file compatible with bracket generators.
​
roundId
integer
required
The round ID to prepare scores for

​
Usage Example

/preparescores roundId:1
Generates a CSV file with:
  • Team names and flags
  • Scores for each map in the pool
  • Seeds calculated from Z-sum rankings
  • Mod-specific seeds (NM, HD, HR, DT)
  • Map rankings for each player
  • Player roster with osu! IDs
Output format: 
team name,flag ISO,NM1,HD1,HR1,DT1,...,Seed,NM Seed,HD Seed,HR Seed,DT Seed,...
Player1,Player1,950000,920000,880000,...,1,1,1,1,1,...
This file can be imported into bracket generation tools like DIO’s bracket.json generator.
Maps are automatically ordered by mod type (NM → HD → HR → DT → TB) and then by number.

Build docs developers (and LLMs) love

Get started for freeTalk to us