Achievements
Relevant source files
The following files were used as context for generating this wiki page:The Achievements system is a player engagement feature designed to reward users for completing specific in-game milestones. It provides a visual progression system, categorizes achievements by type, and uses a rarity scale to denote the difficulty and prestige of each accomplishment. The system is accessible from the user's profile and presents a detailed, filterable view of both unlocked and locked achievements.
This feature is implemented primarily through the AchievementsPage component, which is launched from the UserProfile component. It displays a combination of achievements already earned by the player and a predefined list of achievements that are yet to be unlocked.
Component Architecture
The Achievements feature is encapsulated within its own React component, AchievementsPage, which is rendered conditionally by the UserProfile component. This creates a modular, single-page view dedicated to achievements.
Sources: components/user-profile.tsx:13, 68-70, components/achievements-page.tsx
Component Flow
The user journey begins at the UserProfile component. A summary of the player's achievements is displayed, and clicking this section sets the showAchievements state to true, which in turn unmounts the profile view and renders the full AchievementsPage.
This diagram illustrates the flow of control between the UserProfile and AchievementsPage components.
Sources: components/user-profile.tsx:29, 68-70, 240-243
Data Structure
The achievement data is defined as an array of objects within the AchievementsPage component. The system combines achievements passed in via the profile prop with a hardcoded list of locked achievements to create a comprehensive list.
Sources: components/achievements-page.tsx:21-70
Achievement Object
Each achievement has a consistent structure, detailed in the table below.
| Field | Type | Description | Source |
|---|---|---|---|
id | string | A unique identifier for the achievement. | components/achievements-page.tsx:30 |
name | string | The display name of the achievement. | components/achievements-page.tsx:31 |
icon | string (emoji) | An emoji character used as the visual icon. | components/achievements-page.tsx:32 |
description | string | A brief explanation of what is required to unlock the achievement. | components/achievements-page.tsx:33 |
rarity | "common" | "rare" | "epic" | "legendary" | The rarity level, which affects styling. | components/achievements-page.tsx:34 |
unlocked | boolean | A flag indicating if the player has earned the achievement. | components/achievements-page.tsx:23, 35 |
progress | number | The player's current progress towards unlocking the achievement. | components/achievements-page.tsx:23, 36 |
total | number | The total value required to reach 100% progress. | components/achievements-page.tsx:37 |
category | string | The category the achievement belongs to, used for filtering. | components/achievements-page.tsx:38 |
unlockedAt | string (optional) | The date the achievement was unlocked. This is present on unlocked achievements from the profile prop. | components/achievements-page.tsx:290-292 |
Data Relationship
The profile object contains an array of achievements that the user has unlocked. The AchievementsPage component merges this data with a static list of locked achievements.
This ER diagram shows that a Profile can have multiple Achievement objects.
Sources: components/achievements-page.tsx:12, 22-23, components/user-profile.tsx:12
Example Data
The following snippet from achievements-page.tsx shows the structure of a locked achievement.
// components/achievements-page.tsx:40-51
{
id: "locked2",
name: "Marathon",
icon: "🏃",
description: "Play 10,000 hands",
rarity: "epic",
unlocked: false,
progress: 7234,
total: 10000,
category: "hands",
},
The conditions for unlocking achievements, such as "Get a Royal Flush", are based on outcomes determined by the game logic, as seen in the hand evaluation functions within the poker engine.
Sources: lib/poker-engine.ts:162-168
UI and Presentation
The AchievementsPage is a feature-rich interface that provides multiple ways to view and understand player accomplishments.
Categories
Achievements are grouped into categories, allowing players to filter the list. The categories are managed by a useState hook and rendered as tabs.
| ID | Name | Icon |
|---|---|---|
all | All | Trophy |
wins | Wins | Star |
hands | Hands | Target |
special | Special | Zap |
streaks | Streaks | Flame |
vip | VIP | Crown |
Sources: components/achievements-page.tsx:72-79
Rarity System
A rarity system is used to visually distinguish achievements. The rarity affects the border color, background color, and text color of the achievement card.
| Rarity | getRarityColor Class (border, bg) | getRarityTextColor Class (text) |
|---|---|---|
common | border-gray-400 bg-gray-400/10 | text-gray-400 |
rare | border-blue-500 bg-blue-500/10 | text-blue-400 |
epic | border-purple-500 bg-purple-500/10 | text-purple-400 |
legendary | border-yellow-400 bg-yellow-400/10 | text-yellow-400 |
Unlocked legendary achievements also feature a pulsing glow effect.
Sources: components/achievements-page.tsx:81-111, 224-226
Progress and Completion
The UI clearly distinguishes between locked and unlocked achievements:
- Overall Completion: A prominent progress card at the top of the page shows the percentage of all achievements completed.
- Locked Achievements: Display a
Lockicon, are slightly faded (opacity-60), and show a progress bar indicating how close the player is to unlocking it. - Unlocked Achievements: Display their specific icon, are fully opaque, and show the date they were unlocked (if available).
Sources: components/achievements-page.tsx:143-163, 237-239, 276-288
User Interaction Flow
The following diagram shows the sequence of events when a user interacts with the achievements system.
This sequence demonstrates how a user navigates from the profile to the detailed achievements page, filters the content, and returns.
Sources: components/user-profile.tsx:29, 240, components/achievements-page.tsx:14, 131, 189
Integration with User Profile
The UserProfile component serves as the primary entry point to the full achievements page. It presents a compact, summary view of the player's most notable achievements.
- A button/section labeled "Achievements" is present on the profile.
- It displays a grid of the first 8 unlocked achievements, showing their icon and name.
- The rarity of each achievement is used to determine the border color of its icon in the summary view, using the
getRarityColorutility function. - Clicking this section triggers the
setShowAchievements(true)state change, which opens the full-screenAchievementsPagecomponent.