Achievement Points

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

Every time an achievement is unlocked, the player receives points based on the achievement’s difficulty level:

Difficulty	Points Earned
Normal	10 points
Hard	25 points
Epic	50 points

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

Your current point balance is visible in two places:

1. In any shop that uses achievement points as currency — your balance appears at the top of the shop UI
2. Statistics Export — if the server has stats export enabled, your total points are included in your player data

---

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

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

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_Berry",
      "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

When a player purchases an item from a shop that uses achievement_points:

1. The system checks if the player has enough points
2. If sufficient, the cost is deducted from their balance
3. The purchased item is added to their inventory
4. If the purchase fails (e.g., inventory full), the points are refunded automatically

---

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

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

The point values per difficulty level (10 / 25 / 50) are currently fixed in the achievement service. To adjust pricing, focus on setting appropriate costs in your shop configurations rather than modifying point values.

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

When an administrator revokes an achievement using /ksachievementadmin revoke, the associated points are not automatically refunded. This is by design to prevent point farming through repeated grant/revoke cycles.

:::info Admin Note If you need to adjust a player’s point balance, consider granting or revoking achievements carefully. There is no direct command to set points manually. :::

---

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 JSON data file (data/players/<uuid>.json)
Persistence	Saved with player data on regular intervals and on logout