Scoreboards Documentation
Everything you need to create and manage Discord leaderboards
- Add the bot — Invite Scoreboards to your Discord server using the invite link on the homepage.
- Run the setup wizard — Use
/get startedto walk through the initial configuration. - Assign roles — Open the dashboard to set the
bot permissionrole (users who can manage leaderboards) and thevalidatorrole (users who can approve submissions). - Create your first leaderboard — Use
/scoreboard createto set up a leaderboard. Choose a name, type, and sort order. - Display it — Use
/scoreboard showin a channel to post the interactive leaderboard with submit and pagination buttons.
When creating a leaderboard with /scoreboard create, choose one of six types:
Classic
Adds or subtracts points from a running total. Best for cumulative scoring games.
Highscore
Only stores each player's personal best. Previous lower scores are replaced automatically.
Time (Speedrun)
Submit times in 00:00:00 format. Use ascending sort for fastest-wins or descending for longest-wins.
ELO - Ranked 1v1
Competitive ELO rating system. Submit match results and both players' ratings update automatically.
Rating
Submit images for community star ratings (1–10). Votes are averaged into a score. Perfect for art contests and creative challenges.
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).
Leaderboard Management
| Command | Description | Permission |
|---|---|---|
/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 | Opens the dashboard to manage this scoreboard's settings (sort, visibility, headers, view mode, ELO config, and more) | Admin / Bot Permission |
/scoreboard delete | Permanently delete a leaderboard and all associated data (requires confirmation) | Admin / Bot Permission |
Score & Match Submissions
| Command | Description | Permission |
|---|---|---|
/submit | Submit to any leaderboard. The bot opens the right next step based on type — a score modal (Classic/Highscore/Time), a player + winner picker (ELO), a player + score picker (League), or a name modal (Rating, with an image attached to the slash command). | Everyone |
/set | Manually set a player's exact score or ELO rating | Admin / Bot Permission |
/adjust | Add or subtract a value from a player's score (use negative values to subtract) | Admin / Bot Permission |
/player remove | Remove a player from a leaderboard | Admin / Bot Permission |
Configuration
| Command | Description | Permission |
|---|---|---|
/get started | Launch the setup wizard for first-time configuration | Admin |
/help | View interactive help documentation with all available topics | Everyone |
There are two ways to submit:
- Use the
/submitslash command and pick a leaderboard. The bot opens the right modal/flow based on the leaderboard's type — a score input for Classic/Highscore/Time, a player + winner picker for ELO, a player + score picker for League, or a name input for Rating (with the image attached to the slash command). - Click the Submit button on the posted leaderboard message to open the same submission flow.
Review Process
- The submission is posted to the configured verification channel (if set).
- A validator or admin clicks Approve or Reject.
- If rejected, the submitter receives a DM with the rejection reason.
- If approved, the leaderboard updates immediately.
Auto-Approval
Each leaderboard can be configured to auto-approve submissions after a set delay: Off, Instant, 1 hour, 3 hours, 24 hours, 3 days, or 7 days. The default for ELO leaderboards is 24 hours.
Cancelling a Score
Admins and validators can cancel an already-approved score by right-clicking the submission message and selecting "Cancel Score/Match". This reverts the score change and requires a cancellation reason.
The ELO - Ranked 1v1 leaderboard type uses an ELO rating system to rank players competitively.
How it works
- Each player starts at a configurable starting ELO (default: 1200).
- Match results can be win, loss, or draw.
- Ratings are calculated using a K-factor of 32.
- Both players' ratings update simultaneously after approval.
Matchmaking Queue (Beta)
If the queue button is enabled on the leaderboard, players can click it to join the matchmaking queue. The system pairs players with similar ELO ratings using an expanding window algorithm. When matched, a thread is created for the match with community voting buttons. If no opponent is found within 5 minutes, the queue entry expires.
The League leaderboard type ranks players by points accumulated across head-to-head matches. It's the right format for sports like football/soccer, basketball, futsal, hockey, and any 1v1 competition where the season's table is the source of truth.
How it works
- Submit a match with
/submit— the bot prompts for both players and a score for each (e.g. 3 and 1). - The higher score wins; equal scores are a draw.
- The winner is awarded points_win, the loser points_loss, both players in a draw points_draw.
- The leaderboard ranks players by total points; W/D/L counts are tracked separately.
Default points
New leagues default to 3 / 1 / 0 (FIFA standard since 1994). All three values are configurable per leaderboard from the dashboard. Use 2 / 1 / 0 for hockey, 4 / 2 / 0 for rugby, or any custom schedule that fits your sport.
Submitting a match
From the website, open the leaderboard and click Submit — enter both players and the match score. The bot's /submit command opens the same prompt in Discord. Same-player matches and negative scores are rejected at submission time.
Reviewing & canceling
League matches use the same review queue as ELO matches: a validator approves or rejects each submission, points apply on approval, and approved matches can be cancelled later (which reverts the exact points awarded).
The Rating leaderboard type lets community members submit images and rate each other's submissions with star ratings.
How it works
- Users submit images with
/submit— attach the image to the slash command, then enter a name in the prompt. - 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 — only one vote per person per submission.
- The leaderboard ranks submissions by average rating.
Rating on the website
On the website, submissions appear in the Entries tab. Click any entry to see the full image and rate it with interactive star buttons. Your existing votes are remembered across sessions.
Control who can see your leaderboards on the Scoreboards website:
Visible to everyone on the website.
Only visible to members of your Discord server (requires login).
Only visible to members with a specific Discord role.
Not shown on the website at all.
Automatically assign Discord roles to players based on their leaderboard ranking. For example, you could give the top 3 players a "Champion" role, ranks 4–10 a "Veteran" role, and so on.
- 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.