# Scoreboards

> Scoreboards is a Discord bot and web dashboard that lets you create and manage leaderboards in your Discord server. Track cumulative points, personal bests, speedrun times, ELO ratings, and community-voted image contests — with a public web view your members can share.

## Links

- Website: https://scoreboards.dev
- Documentation: https://scoreboards.dev/docs
- Blog: https://scoreboards.dev/blog
- Add to Discord: https://discord.com/oauth2/authorize?client_id=1337888416221888615
- Support Discord: https://discord.gg/8nzPbPy64P
- Full documentation for LLMs: https://scoreboards.dev/llms-full.txt

## Leaderboard Types

- **Classic**: Cumulative point tracking. Every score submission adds to a running total. Best for seasonal competitions and activity tracking.
- **High Score**: Personal best only. Only the highest score is kept per player. Ideal for arcade-style competitions.
- **Fastest Times**: Time-based records in MM:SS.ms format. Tracks fastest completion times for speedruns and races.
- **ELO (Ranked 1v1)**: Skill-based competitive ratings. Uses ELO algorithm with configurable K-factor, starting rating, and optional decay.
- **Image Rating**: Community star ratings (1-10) on submitted images. Perfect for art contests and creative challenges.

## Bot Commands

### Leaderboard Management
- `/scoreboard create` — Create a new leaderboard with name, type, sort order, and optional settings (Admin / Bot Permission)
- `/scoreboard show` — Display the leaderboard in the current channel with interactive buttons (Admin / Bot Permission)
- `/scoreboard settings` — Change sort order, game link, auto-approval, submission channel, or visibility (Admin / Bot Permission)
- `/scoreboard display_settings` — Customize view mode, headers, visible ranks, medals, and button visibility (Admin / Bot Permission)
- `/scoreboard delete` — Permanently delete a leaderboard and all associated data (Admin / Bot Permission)

### Score & Match Submissions
- `/submit score` — Submit a score for one or more players. Supports @mentions, @roles, and custom names. (Everyone)
- `/submit match_result` — Record an ELO match result between two players (win, loss, or draw) (Everyone)
- `/submit image` — Submit an image for a Rating scoreboard. Name your submission and attach an image. (Everyone)
- `/set score` — Manually set a player's exact score or ELO rating (Admin / Bot Permission)
- `/adjust score` — Add or subtract a value from a player's score (Admin / Bot Permission)
- `/player remove` — Remove a player from a leaderboard (Admin / Bot Permission)

### Configuration
- `/settings` — Set the bot_permission and score_validator roles for your server (Admin)
- `/get started` — Launch the setup wizard for first-time configuration (Admin)
- `/help` — View interactive help documentation with all available topics (Everyone)

## Key Features

- **Score Validation**: Configurable approval workflow with validator roles, auto-approval delays (instant to 7 days), and cancellation support
- **Tier Roles**: Automatically assign Discord roles based on leaderboard rank ranges
- **Visibility Settings**: Public, Hidden (server members only), Private (role-based), or Disabled
- **Web Dashboard**: Manage leaderboards, configure settings, review submissions, and manage scores through a web interface at scoreboards.dev/dashboard
- **Live Leaderboards**: Real-time updating leaderboard embeds in Discord channels
- **Player Analytics**: Rank history, performance insights, submission logs, and percentile rankings
- **Matchmaking Queue (Beta)**: For ELO leaderboards, players can join a queue and get matched with similarly-rated opponents

## How Score Submission Works

1. Players submit scores via `/submit score` or by clicking the Submit button on the leaderboard embed
2. If a validation channel is configured, submissions go there for review
3. Validators approve or reject submissions (rejected submitters get a DM with the reason)
4. Auto-approval can be set per leaderboard: Off, Instant, 1 hour, 3 hours, 24 hours, 3 days, or 7 days
5. Admins can cancel already-approved scores by right-clicking the submission message

## ELO Rating System

- Each player starts at a configurable starting ELO (default: 1000)
- Match results can be win, loss, or draw
- Ratings are calculated using a configurable K-factor (default: 32)
- Optional ELO decay: inactive players gradually lose rating points (daily, weekly, or monthly intervals)
- Matchmaking queue pairs players with similar ELO using an expanding window algorithm

## Image Rating System

- Users submit images with `/submit image`, giving each submission a name
- Submissions appear in the designated channel with a rating dropdown
- Anyone can rate from 1 to 10 stars; ratings are averaged into a score
- Users can change their vote at any time — one vote per person per submission
- The leaderboard ranks submissions by average rating
- Submissions are also viewable and rateable on the website

## Visibility & Privacy

- **Public**: Visible to everyone on the website
- **Hidden**: Only visible to members of your Discord server (requires login)
- **Private**: Only visible to members with a specific Discord role
- **Disabled**: Not shown on the website at all

## Tier Roles

Automatically assign Discord roles to players based on their leaderboard ranking:
- Configure tiers from the web dashboard under each leaderboard's settings
- Set a minimum and maximum rank range for each tier
- Assign any existing Discord role to each tier
- Roles are automatically assigned and removed as rankings change

## Web Dashboard

The web dashboard at scoreboards.dev/dashboard provides:
- Server selection from servers where you have admin permissions
- Leaderboard management with full settings configuration
- Score management: add players, set/adjust scores, remove players
- Submission review: approve or reject pending submissions
- Tier roles configuration with rank range controls
- Leaderboard display customization: custom headers, visible ranks, medals, emoji

## FAQ

Q: How do I add Scoreboards bot to my Discord server?
A: Click the "Add to Discord" button on the website. You need administrator permissions. Once added, create leaderboards immediately.

Q: What types of leaderboards are supported?
A: Five types: Classic (cumulative points), High Score (personal best), Fastest Times (speedruns), ELO (ranked 1v1), and Image Rating (community star voting).

Q: Is it free?
A: Scoreboards is currently completely free to use. Pricing and usage limits may be introduced for certain features in the future.

Q: How does score validation work?
A: Set a validator role to manually approve/reject submissions. Or enable auto-approval with configurable delays (instant to 7 days).

Q: How do tier roles work?
A: Tier roles automatically assign Discord roles based on leaderboard rank. Configure min/max rank ranges per role from the web dashboard.

Q: Can I control who can view my leaderboards?
A: Yes. Each leaderboard has visibility settings: Public, Hidden, Private, or Disabled.

Q: Is there a limit to how many leaderboards I can create?
A: Each server can have up to 100 leaderboards.

Q: Can I customize the view mode of my leaderboards?
A: Yes. Customize headers, sort order, visible ranks, medals, and more through the dashboard.

Q: Can I track player statistics and analytics?
A: Basic leaderboard tracking is fully functional. Comprehensive player statistics, performance trends, and detailed analytics dashboards are currently in development.