Achievement Points
Achievement Points are a currency automatically earned when you complete achievements. They integrate with the shop system, allowing server owners to create shops where players spend their hard-earned points on exclusive items.
How Points Are Earned
Section titled “How Points Are Earned”Every time an achievement is unlocked, the player receives points based on the achievement’s difficulty level. The values can be changed in config.json (points.*) or in the admin window (Points & book):
| Difficulty | Default points |
|---|---|
| Easy | 10 |
| Normal | 10 |
| Hard | 25 |
| Epic | 50 |
| Legendary | 10 |
The defaults are the values from before 3.0.0, so nothing changes until you set your own.
Points are awarded automatically — there is no action required from the player beyond completing the achievement.
:::info Accumulative Points are cumulative and never expire. They persist across sessions and server restarts. :::
Viewing Your Points
Section titled “Viewing Your Points”Your current point balance is visible in these places:
- The achievement book — in the header and on the overview tiles
- In any shop that uses achievement points as currency — your balance appears at the top of the shop window
- Statistics Export — if the server has stats export enabled, your total points are included in your player data
Shop Integration
Section titled “Shop Integration”Achievement Points work as a full currency in the KyuubiSoft Shop System. Server owners can create shops that accept achievement points instead of (or alongside) regular item currencies.
How It Works
Section titled “How It Works”The Achievement mod registers a CurrencyProvider with the currency ID achievement_points. Any shop can reference this currency to use achievement points for purchases.
Setting Up a Points Shop
Section titled “Setting Up a Points Shop”To create a shop that uses achievement points, set the currencyId field in your shop configuration:
{ "id": "achievement_shop", "title": "shop.achievement_store.title", "currencyId": "achievement_points", "settings": { "itemsPerPage": 9, "showSoldOut": true, "allowBuyMultiple": false }, "items": [ { "itemId": "Armor_Iron_Head", "name": "Iron Helmet", "quantity": 1, "cost": 50, "description": "A sturdy iron helmet", "category": "armor", "maxPurchases": 1 }, { "itemId": "Food_Pie_Apple", "name": "Berry Pie", "quantity": 10, "cost": 15, "description": "10x Berry Pie", "category": "food", "maxPurchases": 0 }, { "itemId": "Tool_Pickaxe_Iron", "name": "Iron Pickaxe", "quantity": 1, "cost": 30, "description": "1x Iron Pickaxe", "category": "tools", "maxPurchases": 3 } ]}Place this file in the Core mod’s shops/ folder (e.g., shops/achievement_shop.json).
:::tip Currency Display
In the shop UI, the player’s current achievement point balance is shown at the top. The currency icon displays as an Emerald Bar (Ingredient_Bar_Emerald) and the display name reads “Achievement Points” (localizable).
:::
Spending Points
Section titled “Spending Points”When a player purchases an item from a shop that uses achievement_points:
- The system checks if the player has enough points
- If sufficient, the cost is deducted from their balance
- The purchased item is added to their inventory
- If the purchase fails (e.g., inventory full), the points are refunded automatically
Pricing Guidelines
Section titled “Pricing Guidelines”Here are some suggested pricing tiers based on how many points players earn over time:
| Item Tier | Suggested Cost | Rough Equivalent |
|---|---|---|
| Common consumables | 10-20 points | 1-2 Normal achievements |
| Standard equipment | 30-50 points | 2-3 Hard achievements |
| Rare items | 75-100 points | 2 Epic achievements |
| Exclusive / cosmetic | 150-250 points | Significant progression |
:::warning Balance Carefully A player who completes all default achievements will earn hundreds of points. Price your items so that earlier achievements give meaningful purchasing power, while top-tier items require dedicated effort. :::
Configuration
Section titled “Configuration”Achievement points are built into the achievement system and require no additional configuration to enable. They are automatically awarded when achievements are unlocked.
Customizing Point Values
Section titled “Customizing Point Values”Set points.easy, points.normal, points.hard, points.epic and points.legendary in config.json, or use the Points & book page of the admin window. New values apply to future unlocks; points already earned stay.
Disabling Points
Section titled “Disabling Points”If you do not want to use achievement points, simply do not create any shops with "currencyId": "achievement_points". Points will still accumulate silently but have no effect.
Refunds on Revoke
Section titled “Refunds on Revoke”Since 3.0.0, revoking an achievement (with /acadmin revoke or the players tool) takes back the points it granted. The balance never goes below 0.
:::info Admin Note To change a balance directly, use Points ± in the players tool of the admin window. It works for online and offline players and every change is logged. :::
Technical Details
Section titled “Technical Details”| Property | Value |
|---|---|
| Currency ID | achievement_points |
| Display Name | Achievement Points (localizable via achievements.currency.points) |
| Icon Item | Ingredient_Bar_Emerald |
| Storage | Per-player data (players/<uuid>.json, or MySQL when KyuubiSoft Core uses MySQL) |
| Persistence | Saved with player data on regular intervals and on logout |