# Achievements

# Achievements

This page explains the achievement structure and documents all built-in achievements.

## Achievement Structure

Each achievement is defined as a JSON object with the following fields:

```json
{
  "id": "spider_hunter_1",
  "category": "combat",
  "iconItem": "Deco_Trophy_Harvest",
  "hidden": false,
  "difficulty": "easy",
  "requires": null,
  "showRequires": true,
  "title": {
    "id": "spider_slayer",
    "color": "#FF5555"
  },
  "trigger": {
    "type": "kills",
    "target": "Spider",
    "count": 1
  },
  "rewards": [
    {
      "type": "item",
      "itemId": "Ingredient_Bar_Gold",
      "amount": 10
    }
  ],
  "additionalInfo": {
    "text": "Hunt spiders in dark caves!",
    "color": "#AAAAAA"
  }
}
```

## Field Reference

### Required Fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique identifier (snake_case recommended) |
| `category` | string | Category for filtering: `combat`, `progression`, `exploration`, `social`, `husbandry`, `secret` |
| `trigger` | object | Unlock condition (see [Triggers](#triggers)) |

### Optional Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `iconItem` | string | `"Ore_Gold"` | Item ID for the achievement icon |
| `hidden` | boolean | `false` | Hide as "???" until unlocked |
| `difficulty` | string | `"normal"` | Difficulty tier: `easy`, `normal`, `hard`, `epic`, `legendary` (sets the points and the rarity ring in the book) |
| `requires` | string/array | `null` | Prerequisite achievement ID(s) |
| `showRequires` | boolean | `true` | Show prerequisites in the book's detail panel |
| `title` | object | `null` | Unlockable title reward |
| `rewards` | array | `[]` | Item/command rewards |
| `additionalInfo` | object | `null` | Custom info text |
| `custom` | boolean | `false` | Mark as custom achievement |

## Triggers

Triggers define how achievements are unlocked. These are the trigger types the server really counts (the editor of the [admin window](./admin-panel) offers exactly this list):

| Group | Trigger types |
|-------|---------------|
| Mining and building | `blocks_mined`, `blocks_chopped`, `blocks_dug`, `blocks_broken` (all kinds), `blocks_placed`, `blocks_harvested`, `flowers_picked` |
| Combat | `kills`, `player_kills`, `damage_dealt`, `pvp_damage_dealt`, `pve_damage_dealt`, `damage_taken` |
| Items | `items_collected` (the most of an item held at once), `items_crafted`, `equip_item`, `full_armor_set` |
| World | `zones_discovered`, `distance_walked`, `playtime_minutes`, `weekend_login` |
| Social and NPCs | `chat_messages`, `npc_interact`, `dialog_complete` (see [NPC Integration](./npc-integration)) |
| Levels (with the mod) | `skill_level` (MMO Skill Tree), `rpg_level`, `rpg_xp` (RPG Leveling), `leveling_level`, `leveling_xp` (LevelingCore), `endless_level`, `endless_xp`, `endless_skill_level`, `endless_class`, `endless_race` (Endless Leveling) |
| Dungeons (with KyuubiSoft Dungeons) | `dungeon_complete_any`, `dungeon_complete_<biome>`, `dungeon_rarity_<rarity>`, `dungeon_no_death`. `dungeon_boss_any` / `dungeon_boss_<biome>` exist, but Dungeons does not send boss kills yet |
| Special | `manual` (only by admin grant), `auto_on_prerequisites` (unlocks when the requirements are met) |

**Targets** can be an exact id, a prefix (`Ore_`), a wildcard (`Snake_*`, `Golem_Crystal_*`), a comma list or `any`. Some triggers are easy to abuse; the admin window marks them and warns when such a trigger gives rewards.

Achievements with the `manual` trigger show as **Special** in the book. Husbandry, fishing, farming and death achievements have no tracker yet and use `manual`.

### blocks_mined

Tracks blocks mined by the player.

```json
{
  "type": "blocks_mined",
  "target": "Ore_Iron",
  "count": 100
}
```

**Target Options:**
- Specific block: `"Ore_Iron"`, `"Stone"`, `"Wood_Oak"`
- Any block: `"any"`
- Prefix match: `"Ore_"` matches all ores, `"Wood_"` matches all wood

### blocks_placed

Tracks blocks placed by the player.

```json
{
  "type": "blocks_placed",
  "target": "any",
  "count": 1000
}
```

### kills

Tracks entity kills.

```json
{
  "type": "kills",
  "target": "Spider",
  "count": 50
}
```

**Target Options:**
- Specific entity: `"Spider"`, `"Wolf"`, `"Goblin"`
- Any mob: `"any_mob"`
- Any player: `"any_player"`
- Any entity: `"any"`

### items_crafted

Tracks crafted items.

```json
{
  "type": "items_crafted",
  "target": "Weapon_Sword_Iron",
  "count": 1
}
```

### zones_discovered

Tracks zone/area discoveries.

```json
{
  "type": "zones_discovered",
  "target": "any",
  "count": 10
}
```

### chat_messages

Tracks chat messages sent.

```json
{
  "type": "chat_messages",
  "count": 100
}
```

### playtime_minutes

Tracks playtime in minutes.

```json
{
  "type": "playtime_minutes",
  "count": 60
}
```

:::tip Playtime Display
Playtime is calculated in real-time, including the current session. Progress shows as "X / Y Minutes" in the book.
:::

### distance_walked

Tracks walking distance in blocks.

```json
{
  "type": "distance_walked",
  "count": 10000
}
```

### full_armor_set

Tracks when player equips a complete armor set.

```json
{
  "type": "full_armor_set",
  "target": "iron"
}
```

**Available Materials:**
`iron`, `copper`, `bronze`, `steel`, `cobalt`, `mithril`, `thorium`, `adamantite`, `onyxium`, `prisma`

### equip_item

Tracks when a specific item is equipped.

```json
{
  "type": "equip_item",
  "target": "Weapon_Sword_Legendary"
}
```

### manual

Admin-only manual grant. Cannot be unlocked through gameplay.

```json
{
  "type": "manual"
}
```

### auto_on_prerequisites

Automatically unlocks when all prerequisites are met.

```json
{
  "type": "auto_on_prerequisites"
}
```

## Rewards

### Item Rewards

Grants items to the player's inventory.

```json
{
  "type": "item",
  "itemId": "Ingredient_Bar_Gold",
  "amount": 10
}
```

If the inventory is full, only what fits is handed out; the rest waits in the Rewards tab of the book. See [Rewards](./rewards-ui).

### Command Rewards

Executes a server command.

```json
{
  "type": "command",
  "command": "give {player} diamond 5",
  "executor": "console"
}
```

| Field | Options | Description |
|-------|---------|-------------|
| `executor` | `"console"` | Execute with full permissions (also the default when the field is missing) |
| `executor` | `"player"` | Execute as the player |

**Placeholder:** `\{player\}` is replaced with the player's name.

:::caution Console command rewards
Adding, changing or removing a command reward that runs as the console needs `ks.core.admin.dialog.console` in addition to `ks.achievements.admin` (in the admin window, when saving and in web editor imports). See [Permissions](./permissions#command-rewards-that-run-as-the-console).
:::

### Lootbag Rewards

Grants a lootbag that is opened in the Rewards tab of the book (`/ksrewards`).

```json
{
  "type": "lootbag",
  "lootbagId": "starter_pack"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `type` | string | `"lootbag"` |
| `lootbagId` | string | Template ID from `lootbags.json` |

**Examples:**
```json
"rewards": [
  { "type": "lootbag", "lootbagId": "welcome_gift" },
  { "type": "lootbag", "lootbagId": "miner_reward" },
  { "type": "lootbag", "lootbagId": "legendary_hoard" }
]
```

:::tip Pending Rewards
Lootbags wait in the Rewards tab of the book (`/ksrewards`). They are rolled once and the result is saved, so a relog never re-rolls them.
:::

See [Lootbags Configuration](./lootbags) for detailed lootbag template configuration.

## Titles

Achievements can grant unlockable titles.

```json
"title": {
  "id": "spider_slayer",
  "color": "#FF5555"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Title identifier (for localization) |
| `color` | string | Hex color code (default: `#FFD700` gold) |

Titles are displayed in chat and on the nameplate when the player chooses them in the Titles tab of the book (`/kstitles`).

## Prerequisites

Achievements can require other achievements to be completed first.

**Single prerequisite:**
```json
{
  "id": "spider_hunter_2",
  "requires": "spider_hunter_1",
  ...
}
```

**Multiple prerequisites:**
```json
{
  "id": "master_hunter",
  "requires": ["spider_hunter_5", "wolf_hunter_5", "bear_hunter_5"],
  ...
}
```

## Achievement Chains

Achievements can form progression chains using the `requires` field:

```
spider_hunter_1 (1 kill)
       ↓
spider_hunter_2 (10 kills) - requires: spider_hunter_1
       ↓
spider_hunter_3 (50 kills) - requires: spider_hunter_2
       ↓
spider_hunter_4 (100 kills) - requires: spider_hunter_3
       ↓
spider_hunter_5 (500 kills) - requires: spider_hunter_4
```

The book shows a chain as one line with the current stage ("Stage 2 / 5"); the detail panel shows the whole stage path.

## Hidden Achievements

Set `"hidden": true` to hide an achievement until unlocked:

```json
{
  "id": "secret_easter_egg",
  "hidden": true,
  "category": "secret",
  ...
}
```

Hidden achievements display as "???" without icon, progress, reward or title, and the search never finds them. Add an optional hint with the text key `achievements.hint.<id>` in `localization/custom_<lang>.json`.

## Additional Info

Add custom notes to achievements:

```json
"additionalInfo": {
  "text": "Only available during the Summer Event!",
  "color": "#FF9900"
}
```

This text appears in the book's detail panel.

## Built-in Categories

The standard file includes **277 achievements** across 6 categories (plus 121 MMO Skill Tree and 34 RPG Leveling achievements in their own files):

| Category | Count | Description |
|----------|-------|-------------|
| **Combat** | 51 | Killing mobs, PvP, combat milestones |
| **Progression** | 104 | Mining, crafting, building, general progress |
| **Exploration** | 34 | Zone discovery, distance traveled, dungeons |
| **Social** | 22 | Chat messages, playtime hours |
| **Husbandry** | 29 | Animals, farming, fishing (special, see above) |
| **Secret** | 37 | Easter eggs, hidden challenges |

Categories can be renamed, reordered and given icons in the [admin window](./admin-panel#categories).

## Example Achievement Chains

### Monster Hunter (Combat)
- Kill 50 → 250 → 1,000 → 5,000 → 10,000 mobs

### Miner (Progression)
- Mine 100 → 1,000 → 10,000 → 100,000 blocks

### Playtime (Social)
- Play 1h → 5h → 10h → 25h → 50h → 100h → 250h → 500h → 1,000h

### Distance Walker (Exploration)
- Walk 100 → 1,000 → 5,000 → 10,000 → 42,195 (marathon!) → 100,000 → 500,000 → 1,000,000 blocks