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 — Use
/settingsto set thebot_permissionrole (users who can manage leaderboards) and thescore_validatorrole (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 five 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.
Ranked 1v1 (ELO)
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.
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 | 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 (requires confirmation) | Admin / Bot Permission |
Score & Match Submissions
| Command | Description | Permission |
|---|---|---|
/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 (use negative values to subtract) | Admin / Bot Permission |
/player remove | Remove a player from a leaderboard | Admin / Bot Permission |
Configuration
| Command | Description | Permission |
|---|---|---|
/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 |
There are two ways to submit a score:
- Use the
/submit scoreslash command with a leaderboard name, score value, and one or more players. - Click the Submit button on the posted leaderboard message to open a submission modal.
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 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: 1000).
- 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 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 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 — 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.