Skip to main content
Guccho’s leaderboard system provides comprehensive player rankings across multiple game modes, rulesets, and scoring systems.

​
Overview

The leaderboard displays the top players on your server with detailed statistics and filtering options.

Multiple Ranking Systems

PPv1, PPv2, RankedScore, and TotalScore rankings

Country Filtering

Filter leaderboards by player country

Mode Support

Separate leaderboards for each game mode

Pagination

Navigate through pages of rankings

​
Ranking Systems

Guccho supports multiple ranking systems that measure player skill differently:

​
PPv2 (Performance Points v2)

The modern performance-based ranking system:
  • Calculates skill based on score quality and difficulty
  • Weighs recent top plays more heavily
  • Most commonly used ranking system
  • Provides the most accurate skill measurement
PPv2 is the default ranking system used by most servers.

​
PPv1 (Performance Points v1)

Legacy performance point system:
  • Original PP calculation algorithm
  • May be used for older servers or specific modes
  • Generally less accurate than PPv2

​
RankedScore

Ranking based on total score from ranked beatmaps:
  • Only counts scores on ranked/approved beatmaps
  • Ignores loved and unranked maps
  • Traditional ranking method
  • Favors players with more ranked map plays

​
TotalScore

Ranking based on all scores:
  • Counts scores from all beatmap types
  • Includes loved, unranked, and ranked maps
  • Pure score accumulation
  • No difficulty weighting

​
Leaderboard Features

​
Mode and Ruleset Selection

The leaderboard supports all osu! game modes: 
// Available modes
{
  mode: 'osu' | 'taiko' | 'catch' | 'mania',
  ruleset: string // Server-specific rulesets
}
Each mode has its own independent rankings and statistics.

​
Country Filtering

Filter the leaderboard by country:
1

Open Country Dropdown

Click the country filter button in the leaderboard header.
2

Search Countries

Use the search bar to quickly find a specific country.
3

Select Country

Click a country to filter the leaderboard.
4

Clear Filter

Click the clear button (X) to show all countries again.
The country list only shows countries with active players in the selected mode.

​
Leaderboard Columns

The leaderboard table displays:
ColumnDescription
RankPlayer’s position in the current ranking system
FlagPlayer’s country flag (clickable to filter)
PlayerUsername with link to profile page
Performance/ScorePP or score value depending on ranking system
AccuracyOverall accuracy percentage
Play CountTotal number of plays

​
Pagination

Navigate through pages of rankings:
  • Each page shows 20 players
  • Up to 5 pages available (top 100 players)
  • Click page numbers to jump to specific pages
  • URL updates with current page for sharing
The leaderboard is limited to the top 100 players (5 pages) for performance reasons.

​
URL Parameters

Leaderboards support URL parameters for direct linking: 
/leaderboard/:mode?ruleset=:ruleset&ranking=:system&page=:page&country=:country
Parameters:
  • mode: Game mode (osu, taiko, catch, mania)
  • ruleset: Ruleset identifier
  • ranking: Ranking system (PPv2, PPv1, RankedScore, TotalScore)
  • page: Page number (1-5)
  • country: Two-letter country code
Example: 
/leaderboard/osu?ruleset=std&ranking=PPv2&page=1&country=US

​
Real-time Updates

The leaderboard updates dynamically:
  • Loading states shown during data fetching
  • Smooth transitions between pages and filters
  • No full page reloads required
  • History state managed for browser back/forward navigation

​
Implementation Details

The leaderboard is implemented in src/pages/leaderboard/[[mode]].vue with optional mode parameter for cleaner URLs.
// Leaderboard data query
{
  mode: ActiveMode,
  ruleset: ActiveRuleset,
  rankingSystem: LeaderboardRankingSystem,
  page: number,        // 0-based index
  pageSize: number,    // 20 per page
  country?: CountryCode // Optional filter
}
The country list is lazy-loaded when first opened to improve initial page load performance. Countries without players in the selected mode are automatically filtered out.

​
Empty State

When no players have scores in a mode: 
No one played this mode yet.
Wanna be the first one? Go for it.
This encourages new players to be the first to set scores.

​
Table Interactions

​
Clicking Player Names

Click any player’s name to navigate to their profile page.

​
Clicking Flags

Click a flag to filter the leaderboard by that country. The flag column header changes to show “Clear” when a filter is active.

​
Hover Effects

Table rows highlight on hover for better readability and to indicate clickability.

​
Mobile Responsiveness

The leaderboard is fully responsive:
  • Table scrolls horizontally on small screens
  • Condensed table size on mobile devices
  • Touch-friendly navigation buttons
  • Optimized column widths

​
Accessibility

  • Semantic table markup with proper headers
  • ARIA labels for navigation elements
  • Keyboard navigation support
  • Screen reader friendly

​
Performance Optimizations

Server-Side Rendering

Initial leaderboard data is rendered on the server for fast first paint.

Lazy Loading

Country list loaded on-demand to reduce initial payload.

Optimistic Updates

UI updates immediately with loading states during data fetching.

URL State

All filter states persisted in URL for sharing and bookmarking.

User Pages

View detailed player profiles and statistics

Clans

View clan leaderboards and rankings

Build docs developers (and LLMs) love

Get started for freeTalk to us