How Leaderboards Work
Every time the bot replies to a user’s message, their reply count is automatically incremented in the leaderboard database.Reply Triggered
When the bot sends an auto-reply to a user’s message, the leaderboard update process begins.
User Lookup
The system checks if the user already exists in the current leaderboard using their Discord user ID.
Counter Update
If the user exists, their reply count increases by 1. If they’re new, they’re added with a count of 1.
Viewing the Leaderboard
Use the/leaderboard command to display the top 10 users:
Command Options
The/leaderboard command accepts a required season parameter:
| Season | Description |
|---|---|
| Current | Active leaderboard tracking ongoing replies |
| Season 2 | Archived leaderboard from Season 2 |
| Season 1 | Archived leaderboard from Season 1 |
The season choices are hardcoded in the command definition and match the table names in the leaderboard database.
Leaderboard Display
The leaderboard shows the top 10 users with the most replies:Medal Rankings
The top three positions receive special recognition:- 🥇 1st place - Gold medal
- 🥈 2nd place - Silver medal
- 🥉 3rd place - Bronze medal
- 4th-10th - Numerical ranking (4th, 5th, etc.)
commands/slash/leaderboard.js:40-55:
User Badges
Users can have special badges displayed next to their names based on theirgroups field:
Available Badges
- Active Developer - Owner badge for server owners
- Wrench icon - Programmer badge for bot developers
- Helper icon - Helper badge for support staff
- Season 1 Winner - Badge for Season 1 competition winners
- Season 2 Winner - Badge for Season 2 competition winners
utils/constants.js and assigned through the groups column:
Leaderboard Updates
The leaderboard is updated immediately after each reply using theupdateLeaderboard utility function.
Update Process
Fromutils/updateLeaderboard.js:28-68:
Seasonal Competition System
AutoResponse supports multiple leaderboard seasons, allowing you to:- Archive past competition results
- Start fresh seasonal competitions
- Maintain historical records of previous winners
Database Structure
Leaderboards are stored in a single SQLite database atdata/leaderboards.db with separate tables for each season:
- current - Active leaderboard
- Season2 - Season 2 archive
- Season1 - Season 1 archive
Table Schema
Each season table uses the same schema structure. The
groups field stores comma-separated badge identifiers.Starting a New Season
While there’s no automated command for season transitions, the process involves:- Manually rename the
currenttable to archive it (e.g.,Season3) - Create a new
currenttable with the standard schema - Add the new season to the
/leaderboardcommand choices - Optionally assign season winner badges (
S3W) to top finishers
Leaderboard Initialization
On bot startup, AutoResponse initializes the leaderboard database: Fromutils/getLeaderboards.js:16-28:
Empty Leaderboards
If a season has no data (new server or archived season with no activity):Empty leaderboards return a user-friendly error message rather than displaying a blank leaderboard.
Leaderboard Sorting
Results are sorted by reply count in descending order:Privacy Considerations
Leaderboards are ephemeral
Leaderboards are ephemeral
By default, leaderboard responses are sent as ephemeral messages (only visible to the command user). This prevents channel spam while allowing users to check rankings privately.
Opt-out affects tracking
Opt-out affects tracking
Users who opt out with
/optout stop receiving replies and therefore stop gaining leaderboard points. Their existing points remain but won’t increase.Usernames are public
Usernames are public
Discord usernames are displayed on the leaderboard. Users concerned about privacy should be aware their username and reply count are visible.
Technical Details
Database Location
- Path:
data/leaderboards.db - Type: SQLite3
- Access: Read/write by bot, read-only for leaderboard queries
Performance
The leaderboard system is optimized for performance:- Updates use simple
UPDATEorINSERTqueries - Sorting happens in memory on the top 10 entries only
- Database connections are opened per-operation and closed immediately
- No caching layer (data is always fresh from the database)