Skip to main content
Guccho includes a comprehensive clan system that allows players to form groups, compete together, and track collective achievements.

​
Overview

Clans are player-organized groups with dedicated pages showing members, statistics, and best scores.

Clan Pages

Dedicated pages with member lists and clan statistics

Clan Search

Browse and search all clans on the server

Member Management

Join, leave, and manage clan memberships

Clan Leaderboards

Best scores from clan members across all modes

​
Clan Directory

The main clans page (/clans) displays all clans on the server.

​
Search Functionality

Search for clans by:
  • Clan name: Full or partial name matching
  • Badge: Clan tag/badge text
1

Enter Search Term

Type a clan name or badge in the search box.
2

Submit Search

Press Enter or click the Search button.
3

View Results

Matching clans are displayed in a grid layout.

​
Grid Display

Clans are shown in a responsive grid:
  • Clan Avatar: Large clan image with badge overlay
  • Clan Name: Displayed prominently
  • Member Avatars: Up to several member avatars in an overlapping stack
  • Member Count: Total members if more than displayed
  • Clan Statistics: Average PP or total score depending on ranking system
The clan directory respects the selected mode, ruleset, and ranking system for statistics.

​
URL Parameters

Clan search supports filtering via URL: 
/clans?mode=:mode&ruleset=:ruleset&ranking=:system&keyword=:search
Example: 
/clans?mode=osu&ruleset=std&ranking=PPv2&keyword=dragon

​
Clan Pages

Each clan has a dedicated page (/clan/:id) showing detailed information.

​
Clan Header

The clan page header displays:
  • Clan Avatar: Large square image with rounded corners
  • Clan Badge: Displayed as an overlay on the avatar
  • Clan Name: Large heading text
  • Owner Information: Avatar and username of clan owner
  • Creation Date: When the clan was founded
  • Member Count: Total number of members

​
Clan Statistics

Statistics vary by selected ranking system:
Shows average PP across all clan members:
Average: {total PP / member count}pp

​
Member Management

​
Joining a Clan

Players can join clans if they meet the requirements:
1

Navigate to Clan Page

Find the clan you want to join via search or direct link.
2

Click Join Button

Click the green plus icon button.
3

Wait for Verification

Your join request may need approval depending on clan settings.
Players can only be in one clan at a time. You must leave your current clan before joining another.

​
Leaving a Clan

Members can leave their clan at any time:
1

Go to Your Clan Page

Navigate to your current clan’s page.
2

Click Leave Button

Click the red minus icon button.
3

Confirm

Your clan membership will be removed.

​
Membership States

Clan membership can be in several states:
StateDescriptionActions Available
FreeNot in any clanJoin
MemberActive clan memberLeave
JoinPendingVerificationJoin request pendingLeave (cancel request)
QuitPendingVerificationLeave request pending-
LeftPreviously left clanJoin again
JoinedOtherClanMember of different clan-
Membership state is checked server-side to ensure data integrity.

​
Member List

The clan page displays all members in a table:

​
Table Columns

  • User: Avatar, username, and country
  • Interactive rows link to user profiles

​
Pagination

For clans with many members:
  • 20 members per page
  • Navigation buttons to jump between pages
  • Current page highlighted
  • Smart page range display (shows nearby pages)

​
Clan Best Scores

The clan page shows the best scores from all clan members.

​
Score Display

Each score entry shows:
  • Player: Member who set the score
  • Beatmap: Map name and difficulty
  • Score Details: Points, accuracy, combo, mods
  • Performance: PP or score value
  • Date: When the score was set

​
Filtering

Scores can be filtered by:
  • Mode: osu!, taiko, catch, mania
  • Ruleset: Server-specific rulesets
  • Ranking System: PPv2, PPv1, RankedScore, TotalScore
Use the mode switcher at the top to change filters.

​
Score Pagination

  • 10 scores per page (configurable)
  • Navigation similar to member pagination
  • Updates dynamically without page reload
Clan best scores are a great way to see what your clan members are working on and celebrate top performances together.

​
Clan Avatars and Badges

​
Clan Avatar

Clans can set custom avatars:
  • Square images (1:1 aspect ratio recommended)
  • Displayed with rounded corners (squircle mask)
  • Shown on clan page, search results, and member profiles

​
Clan Badge

The badge is a short text identifier:
  • Typically 2-5 characters
  • Displayed on clan avatar as overlay
  • Shown on member profiles
  • Used for quick clan identification
Avatar and badge management may be restricted to clan owners or administrators depending on server configuration.

​
Profile Integration

Clan membership is displayed on user profiles:
  • Badge appears as overlay on user avatar
  • Tooltip shows full clan name
  • Clicking badge navigates to clan page

​
Clan Statistics Calculation

​
Average Performance

For PP-based ranking systems: 
averagePP = totalClanPP / memberCount

​
Total Score

For score-based ranking systems: 
totalScore = sum(memberScores)
Statistics are recalculated when members join or leave, and when member statistics change.

​
Implementation Details

Clan pages are implemented in src/pages/clan/[id].vue with dynamic data loading based on mode/ruleset selection.
// Clan detail query
{
  id: string,
  mode: ActiveMode,
  ruleset: ActiveRuleset,
  rankingSystem: LeaderboardRankingSystem
}

// Clan members query
{
  id: string,
  page: number,
  perPage: number  // Default: 20
}

// Clan best scores query
{
  id: string,
  mode: ActiveMode,
  ruleset: ActiveRuleset,
  rankingSystem: LeaderboardRankingSystem,
  page: number,
  perPage: number  // Default: 10
}
Clan relationships are managed server-side with proper validation:
  • Players can only be in one clan
  • Join/leave requests are atomic
  • State transitions are validated
  • Pending states prevent duplicate actions

​
Mobile Responsiveness

Clan pages adapt to mobile devices:
  • Grid layout stacks on small screens
  • Tables scroll horizontally
  • Touch-optimized buttons
  • Condensed statistics display
  • Responsive member avatars

​
SEO Optimization

Clan pages include metadata:
  • Title: {clan name} - Clans
  • Description: Clan information and statistics
  • Server-side rendering for fast initial load

User Pages

View individual player profiles with clan badges

Leaderboards

Compare players globally across all clans

Build docs developers (and LLMs) love

Get started for freeTalk to us