# Scoreboards

> Scoreboards is a leaderboard platform for communities — create ELO ladders, leagues, highscore tables, speedrun boards and image-rating contests on the web, with a full-featured Discord bot integration. 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://www.scoreboards.dev
- Documentation: https://www.scoreboards.dev/docs
- Blog: https://www.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://www.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)**: Skill-based competitive ratings for 1v1, team matches (2v2 up to 8v8) or free-for-alls (3 to 8 players). 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. Event controls include image approval, per-member submission caps, blind voting (hidden scores until reveal), and closing submissions when the contest ends.
- **League**: Match-based points ranking for sports like football, basketball, and FIFA. Configurable points per win/draw/loss (default 3/1/0) and a match score (e.g. 3-1), 1v1, team matches or free-for-alls.

## Bot Commands

### Leaderboard Management
- `/leaderboard create` — Create a new leaderboard with name, type, sort order, and optional settings (Admin / Bot Permission)
- `/leaderboard show` — Display the leaderboard in the current channel with interactive buttons (Admin / Bot Permission)
- `/leaderboard settings` — Open this leaderboard's page on the web dashboard, where every setting lives (Admin / Bot Permission)
- `/leaderboard delete` — Permanently delete a leaderboard and all associated data (Admin / Bot Permission)

### Score & Match Submissions
- **Submit button** (on the leaderboard message, not a slash command) — Opens the right next step for the board's type automatically: **Submit score** for Classic/Highscore/Time (score modal), **Submit result** for ELO (player + winner picker) and League (player + scoreline), or **Submit image** for Rating (name + image). Free-for-all boards use a **Report result** button instead. (Everyone)
- `/score` — Set or adjust a player's score, ELO or time. Pick the leaderboard; a form then asks whether to Set (replace) or Adjust (add, or subtract with a minus sign — Adjust is preselected), plus the players and the value. Image Rating leaderboards are not offered — their ranking comes from members' votes, so there is no score to set. (Admin / Bot Permission)
- **Cancel Review** (message context menu, not a slash command) — Right-click an already-approved submission message and pick Apps → Cancel Review to reverse it. Reverts the score or rating change and asks for a cancellation reason. (Admin / Validator)

### Configuration
- Dashboard (https://www.scoreboards.dev/dashboard) — Set the bot permission and 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)
- `/delete_my_data` — Permanently delete all your personal scoreboards and data (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**: Leaderboards in Discord channels that update themselves. Each one posts in one of two appearances, set per leaderboard in the dashboard: a rendered image, or a Discord embed whose rows link to each player's stats. Free-for-all and team leaderboards can use either — only Image Rating boards are fixed to the embed. The image and the embed take the same colour, the board's own accent
- **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 — 1v1 or balanced teams, each team with its own voice channel
- **Free-for-all**: ELO and League leaderboards can run 3–8 player matches where everybody plays for themselves, set with `match_format` on `/leaderboard create` (`ffa3`…`ffa8`) or under Match format in the dashboard. It replaces team matches — a leaderboard cannot have both. The leaderboard carries a Report result button: it opens a form whose player picker demands exactly the lobby size (a 6-player leaderboard takes 6, no fewer), plus an optional result field — the winner, or on a placement-points leaderboard the whole finishing order, 1st first. ELO accepts the full finishing order or an all-draw; League also accepts one winner with everyone else unplaced
- **Fixed Teams**: Team-size ELO and League leaderboards can rank persistent named teams instead of players. Teams sign up via the leaderboard's Team sign-up button (roster may hold up to 2 reserves). On ELO boards the team has its own rating and when any member clicks Queue the whole team is queued (the first team-size members to click Ready per side are the lineup); on League boards the table ranks teams by points and matches are submitted team vs team with a score

## How Score Submission Works

1. Players submit by clicking the board's own submit button on the leaderboard message — **Submit score** (Classic/Highscore/Time), **Submit result** (ELO/League), **Submit image** (Rating), or **Report result** (free-for-all). It is the only route from Discord. The website and the mobile app can submit too.
2. If a log 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 and validators can cancel already-approved scores by right-clicking the submission message and picking Apps → **Cancel Review**

## ELO Rating System

- Each player starts at a configurable starting ELO (default: 1200)
- Match results can be win, loss, or draw
- Ratings are calculated using a configurable K-factor (default: 32)
- Team matches: ELO and League boards have a fixed team size, 1v1 (default) up to 8v8, chosen at creation or later under Match format in the dashboard. Players are still ranked individually — for ELO the expected result comes from each team's average rating, and the same zero-sum change is applied to every player on that side
- Free-for-all matches: 3–8 players, each for themselves. Every pair in the match is rated against each other (better finish beats worse, equal finish is a draw between them) with the K-factor divided by the number of opponents, so one free-for-all is worth about one match of movement and is exactly zero-sum — six equally rated players at K=32 finish +16, +10, +3, −3, −10, −16. First place, including a tie for it, counts as a win, everyone below as a loss, an all-draw as a draw for the whole field
- League free-for-all: an optional placement points table (`10,8,6,4,2,0`, F1 style) pays a complete finishing order. Leave anyone unplaced — a winner-only report, or an order stopped halfway — and the table does not apply at all: first place takes the win points and everyone else the loss points, which is also what happens with no table configured. An all-draw pays the draw points to everybody
- Optional ELO decay: inactive players gradually lose rating points (daily, weekly, or monthly intervals)
- Matchmaking queue groups players with similar ELO using an expanding window algorithm, and splits team matches into two sides with the closest possible average rating. A free-for-all leaderboard fires at exactly its lobby size, has no sides to balance, and gives the match one shared voice channel; the result is reported by one player and locks in once a majority of the field presses Confirm

## Image Rating System

- Users submit images with the leaderboard's Submit image button — one modal takes the name and the image together
- 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
- Settings grouped into three categories: Leaderboards (the board in view), Discord (how the bot and its boards appear in the server) and Economy
- Tier roles configuration with rank range controls, in its own section under Discord
- Leaderboard display: appearance (a rendered image or a Discord embed), the board's colour, custom headers, visible ranks, emojis and which buttons show

## 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: Six types: Classic (cumulative points), High Score (personal best), Fastest Times (speedruns), ELO (ranked 1v1, team matches or free-for-alls), Image Rating (community star voting), and League (match points table, 1v1, teams or free-for-alls).

Q: Can a match have more than two sides?
A: Yes — ELO and League leaderboards can be set to free-for-all with 3 to 8 players, where everybody plays for themselves and the result is the finishing order. Free-for-all replaces team matches on that leaderboard; the two cannot be combined.

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, from the dashboard. A leaderboard posts either as a rendered image or as a Discord embed with clickable rows, and you can change headers, sort order, visible ranks, the board's colour, emojis and which buttons appear. Image Rating leaderboards always post as an embed — the image has no column for an entry's submitter.

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.