Achievement Management (Admin Panel)
The admin panel provides a complete workflow for creating and managing achievements. No code changes are needed — everything is configured through the UI.
Resources
Achievement Rules
Navigate to Achievement Rules in the sidebar to manage rule definitions.
Creating a Rule:
- Click Create
- Fill in the fields:
| Field | Description | Example |
|---|---|---|
| Name | Human-readable rule name | ”Win 5 matches” |
| Field (metric) | What to measure — dropdown with 13 options | wins |
| Comparator | How to evaluate — dropdown | gte (greater or equal) |
| Target | Threshold value | 5 |
| Weight | Contribution to achievement progress (0-100) | 100 |
Available Metrics:
| Metric | Description |
|---|---|
matches | Total matches played |
wins | Total matches won |
losses | Total matches lost |
positions | Total positions opened |
wins_in_row | Current win streak |
total_volume | Cumulative trading volume |
total_profit | Cumulative realized PnL |
invite | Accepted friends count |
level | User level |
deposits | Number of deposits |
withdrawals | Number of withdrawals |
profile_completed | Whether profile has nickname + avatar (use bool comparator) |
trades_closed | Number of closed positions |
Available Comparators:
| Comparator | When to use | Example |
|---|---|---|
>= (gte) | Progressive goals | ”Win at least 5 matches” |
> (gt) | Must exceed | ”Score above 1000” |
<= (lte) | Stay below threshold | ”Keep losses under 5” |
< (lt) | Must be below | ”Fewer than 3 liquidations” |
= (eq) | Exact match | ”Reach exactly level 10” |
bool | True/false check | ”Complete your profile” |
Achievements
Navigate to Achievements in the sidebar.
Creating an Achievement:
- Click Create
- Fill in:
| Field | Description |
|---|---|
| Name | Display name (shown to users) |
| Key | Unique slug (first_win, trading_veteran) |
| Description | Rich text description |
| Avatar | Badge image (upload) |
| Is Active | Toggle — inactive achievements are not evaluated |
| Is Hidden | Toggle — hidden achievements not shown until completed |
| Expires At | Optional — time-limited achievements |
| Rules | Select one or more achievement rules |
| Rewards | Select consumable items to grant on completion |
Roles & Permissions
Achievement management requires the create:achievementDefinitions and update:achievementDefinitions permissions. Assign these via Roles in the admin panel.
Example: Creating “First Win” Achievement
Step 1: Create the Rule
- Go to Achievement Rules → Create
- Name:
First Win Rule - Field:
wins - Comparator:
gte - Target:
1 - Weight:
100 - Save
Step 2: Create the Reward (Optional)
- Go to Consumables → Create
- Name:
50 XP Boost - Type:
exp - Value:
50 - Save
Step 3: Create the Achievement
- Go to Achievements → Create
- Name:
First Win - Key:
first_win - Description:
Win your first match! - Upload a badge image
- Is Active:
true - Link the rule from Step 1
- Link the reward from Step 2
- Save
Step 4: Test
- Log in as a test player (use dev code
12345) - Play and win a match
- Check the player’s achievement progress in the admin panel
- The achievement should show 100% progress and “completed”
Multi-Rule Achievements
For complex achievements, create multiple rules with weights that sum to 100:
Example: “Trading Master”
- Rule 1:
wins>= 10, weight 50 - Rule 2:
total_profit>= 500, weight 30 - Rule 3:
trades_closed>= 100, weight 20
A player with 8 wins (80% of target), $400 profit (80% of target), and 60 closed trades (60% of target):
- Rule 1: 80% × 50 = 40
- Rule 2: 80% × 30 = 24
- Rule 3: 60% × 20 = 12
- Total: 76% (not yet completed)
How It Works Behind the Scenes
- When a user performs any action (trade, login, deposit, etc.), an event is published to NATS
- The achievement worker picks up the event and recalculates ALL metrics for that user
- Each active achievement’s rules are evaluated using the current metrics
- Progress is stored as a percentage (0-100) in
UserAchievement - When progress reaches 100%, rewards are granted and a notification is sent
- Completed achievements are never re-evaluated or re-granted
See the Achievement System documentation for technical details.