Leveling & XP System

Relevant source files

The following files were used as context for generating this wiki page:

• src/util/levelingSystem.ts
• src/db/functions/levelFunctions.ts
• src/commands/util/xp.ts
• config.example.json
• src/util/achievementManager.ts
• src/commands/fun/rank.ts
• src/commands/fun/leaderboard.ts

The Leveling & XP System is a core engagement mechanic within the Poixpixel Discord Bot designed to track user activity and reward participation. It functions by awarding Experience Points (XP) to users for sending messages, which eventually leads to level progression. This system is integrated with other bot features, such as the Achievement System and automated role assignment, to provide a gamified experience for server members.

The system handles XP calculation logic, database persistence via Drizzle ORM, and visual feedback through dynamic rank cards. It also includes administrative tools for manual XP adjustments and server-wide level recalculations.

Sources: src/util/levelingSystem.ts, src/db/functions/levelFunctions.ts, config.example.json

Architecture and Core Logic

The system is built upon a mathematical foundation that defines the relationship between XP and levels. XP is primarily gained through message interactions, subject to a configurable cooldown to prevent spam.

XP Calculation Formula

The bot uses a cubic function to determine the XP required for any given level:
XP = (5 / 6) * level * (2 * level^2 + 27 * level + 91)

Sources: src/util/levelingSystem.ts:49-52

Process Flow: Message to XP

When a message is sent, the bot evaluates several conditions before awarding XP:

1. Bot Check: Bots are excluded from earning XP.
2. Cooldown Validation: Users must wait for a specified period (defaulting to 45-60 seconds) between XP awards.
3. Randomized Award: XP awarded per message is a random value within the configured minXpAwarded and maxXpAwarded range.

Sources: src/util/levelingSystem.ts:114-135, config.example.json:101-110

The following diagram illustrates the lifecycle of a message within the leveling system:

Database Implementation

Leveling data is persisted in a PostgreSQL database and optimized using a Redis caching layer. The system tracks XP, level, message counts, and reaction counts for every user.

Key Database Functions

Function	Description	File Path
getUserLevel	Retrieves user data or initializes a new record if the user is not found.	src/db/functions/levelFunctions.ts
addXpToUser	Atomically increments XP and message counts; triggers level-up checks.	src/db/functions/levelFunctions.ts
setXpForUser	Overwrites a user's XP to a specific value (used for administrative resets).	src/db/functions/levelFunctions.ts
getUserRank	Calculates the user's standing on the leaderboard by XP descending.	src/db/functions/levelFunctions.ts

Sources: src/db/functions/levelFunctions.ts:18, src/db/functions/levelFunctions.ts:88, src/db/functions/levelFunctions.ts:182, src/db/functions/levelFunctions.ts:251

Cache Management

To ensure performance, the system utilizes a withCache wrapper. Leaderboard data and individual user levels are cached for 300 seconds. The cache is invalidated whenever XP is modified or a user's reaction count changes.
Sources: src/db/functions/levelFunctions.ts:51, src/db/functions/levelFunctions.ts:168, src/db/functions/levelFunctions.ts:311

Visuals and Interaction

The system provides several ways for users and administrators to interact with their leveling data.

Rank Cards

The bot generates a dynamic image (Rank Card) using @napi-rs/canvas. This card displays the user's avatar, username, current level, leaderboard rank, and a progress bar showing XP toward the next level.
Sources: src/util/levelingSystem.ts:172-273

Commands

Command	Subcommand	Purpose	Permission
/rank	N/A	Displays the user's current rank card and XP progress.	Everyone
/leaderboard	N/A	Displays a paginated list of the top users in the server.	Everyone
/xp	add	Manually adds a specific amount of XP to a user.	Manage Guild
/xp	remove	Subtracts XP from a user (cannot go below 0).	Manage Guild
/xp	set	Sets a user's XP to a specific value.	Manage Guild
/xp	reset	Sets a user's XP to 0.	Manage Guild

Sources: src/commands/fun/rank.ts, src/commands/fun/leaderboard.ts, src/commands/util/xp.ts

Automated Role Assignment

The system supports levelRoles, where users are automatically granted roles upon reaching specific levels. The configuration for these roles is managed in the bot's configuration file.

Logic Flow

1. User earns XP and reaches a newLevel.
2. checkAndAssignLevelRoles fetches the guild member.
3. The system filters config.roles.levelRoles to find all roles where the required level is less than or equal to newLevel.
4. Missing roles are added to the member.

Sources: src/util/levelingSystem.ts:285-316, config.example.json:76-80

Configuration Options

Leveling behavior is highly customizable through the leveling section of config.json.

Option	Type	Default	Description
xpCooldown	Number	60	Time in seconds between XP awards per user.
minXpAwarded	Number	5	Minimum XP granted per eligible message.
maxXpAwarded	Number	15	Maximum XP granted per eligible message.

Sources: config.example.json:101-110, src/util/levelingSystem.ts:15-41

Summary

The Leveling & XP system provides a robust framework for tracking and rewarding community engagement. By combining mathematical progression formulas with automated database triggers and visual rank cards, it ensures a seamless experience for users while providing administrators with granular control over server progression via the /xp and /config commands.