# 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. 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

Your current point balance is visible in these places:

1. **The achievement book** -- in the header and on the overview tiles
2. **In any shop that uses achievement points as currency** -- your balance appears at the top of the shop window
3. **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:

```json
{
  "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

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

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](./admin-panel#settings). New values apply to future unlocks; points already earned stay.

### 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

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](./admin-panel#players-tool) of the admin window. It works for online and offline players and every change is logged.
:::

---

## 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 |