Clans

Clan system, clan pages, clan leaderboards, and member management

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:

PPv2

Shows average PP across all clan members:

Average: {total PP / member count}pp

PPv1

Shows average PPv1 across all members:

Average: {total PPv1 / member count}pp

RankedScore

Shows total ranked score:

RankedScore: {total ranked score}

TotalScore

Shows total score:

TotalScore: {total score}

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:

State	Description	Actions Available
Free	Not in any clan	Join
Member	Active clan member	Leave
JoinPendingVerification	Join request pending	Leave (cancel request)
QuitPendingVerification	Leave request pending	-
Left	Previously left clan	Join again
JoinedOtherClan	Member 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 Page

Clan pages are implemented in src/pages/clan/[id].vue with dynamic data loading based on mode/ruleset selection.

Clan Search

The clan directory is in src/pages/clans.vue with server-side search functionality.

Data Queries

// 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
}

Relationship Management

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

Related Features

User Pages

View individual player profiles with clan badges

Leaderboards

Compare players globally across all clans