Achievement System

Relevant source files

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

• src/util/achievementManager.ts
• src/util/achievementCardGenerator.ts
• src/db/functions/achievementFunctions.ts
• src/commands/fun/achievements.ts
• src/commands/util/manage-achievement.ts
• src/db/schema.ts

The Achievement System is a core engagement feature of the Poixpixel Discord Bot designed to track, award, and display user milestones based on their activity within a server. It monitors various interactions—such as message counts, leveling progress, command usage, and reactions—to automatically progress users toward specific goals. Once a goal is reached, the system handles the distribution of rewards, such as Experience Points (XP) or Discord roles, and generates a visual "Achievement Unlocked" card to announce the feat.

The system is composed of several layers: a database layer for persistent storage of definitions and user progress, a management utility for processing real-time events, a visual generator for custom achievement cards, and interaction commands for both users (to view progress) and administrators (to manage achievement definitions).

Architecture and Data Flow

The system operates through a series of event-driven triggers. When a user interacts with the bot or the server, the achievementManager evaluates if that activity contributes to any defined achievement requirements.

Event Processing Flow

The following diagram illustrates how a user interaction (like sending a message) transitions through the system to potentially trigger an achievement unlock.

Key Components

Component	Description	Primary File(s)
Achievement Manager	Orchestrates progress tracking and announcement logic for various event types.	src/util/achievementManager.ts
Card Generator	Uses Canvas to create a custom PNG image representing the unlocked achievement.	src/util/achievementCardGenerator.ts
Database Functions	Handles CRUD operations for achievement definitions and user-specific progress.	src/db/functions/achievementFunctions.ts
Management Command	Administrative interface to create, delete, award, or remove achievements.	src/commands/util/manage-achievement.ts
User Interface	Paginated display for users to view their earned, in-progress, and available achievements.	src/commands/fun/achievements.ts

Data Models and Schema

The system relies on two primary tables in the PostgreSQL database: achievement_definitions (static goals) and user_achievements (dynamic user progress).

Entity Relationship Diagram

Requirement Types

Achievements are categorized by their requirement_type, which dictates how progress is calculated:

• message_count: Based on total messages sent by the user.
• level: Based on the user's current level in the bot's leveling system.
• command_usage: Tracks how many times a specific command (defined in the requirement JSON) has been executed.
• reactions: Based on the total number of reactions the user has added to messages.

Sources: src/util/achievementManager.ts:55-125, src/commands/util/manage-achievement.ts:41-47

Achievement Unlock Process

When a user's progress reaches 100% (calculated as (current_value / threshold) * 100), the announceAchievement function is triggered. This function handles three critical tasks:

1. Reward Distribution: If a reward_type is set, the system either adds XP to the user's profile or assigns a specific Discord role via the Guild member's role manager.
2. Visual Generation: The generateAchievementCard function creates a 600x180 pixel PNG image using a linear gradient background (Discord Blurple to Pink) and the achievement's icon.
3. Announcement: An embed is sent to the designated advancements channel (configured in the bot's global config) containing the user's username, the achievement name, and the generated card.

Sources: src/util/achievementManager.ts:159-214, src/util/achievementCardGenerator.ts:18-100

Sequence: Unlocking an Achievement

Administrative Management

Administrators with the ManageGuild permission can manipulate achievements through the /manage-achievements command. This includes creating new definitions with specific thresholds and rewards, as well as manually awarding or removing achievements from specific users.

Command Structure

Subcommand	Parameters	Description
create	name, description, requirement_type, threshold, [reward_type], [reward_value]	Creates a new server-wide achievement definition.
delete	id	Permanently removes an achievement and all associated user progress.
award	user, achievement_id	Manually sets a user's progress to 100% and triggers the announcement.
unaward	user, achievement_id	Removes an achievement from a user and attempts to revoke role rewards.

Sources: src/commands/util/manage-achievement.ts:16-121

Conclusion

The Achievement System provides a robust framework for gamifying community participation. By integrating tightly with the database and Discord's interaction model, it ensures that user progress is accurately tracked across different types of activities. The addition of automated visual cards and rewards provides immediate feedback and incentive for users to remain active within the server environment.

Sources: src/util/achievementManager.ts, src/commands/fun/achievements.ts