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:

{
  "id": "spider_hunter_1",
  "category": "combat",
  "iconItem": "Trophy_Spider",
  "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": "Material_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)

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
requires	string/array	null	Prerequisite achievement ID(s)
showRequires	boolean	true	Show prerequisites when locked
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.

blocks_mined

Tracks blocks mined by the player.

{
  "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.

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

kills

Tracks entity kills.

{
  "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.

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

zones_discovered

Tracks zone/area discoveries.

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

chat_messages

Tracks chat messages sent.

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

playtime_minutes

Tracks playtime in minutes.

{
  "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 gallery. :::

distance_walked

Tracks walking distance in blocks.

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

full_armor_set

Tracks when player equips a complete armor set.

{
  "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.

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

manual

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

{
  "type": "manual"
}

auto_on_prerequisites

Automatically unlocks when all prerequisites are met.

{
  "type": "auto_on_prerequisites"
}

Rewards

Item Rewards

Grants items to the player’s inventory.

{
  "type": "item",
  "itemId": "Material_Gold",
  "amount": 10
}

If the inventory is full, items drop on the ground.

Command Rewards

Executes a server command.

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

Field	Options	Description
executor	"console"	Execute with full permissions
executor	"player"	Execute as the player

Placeholder: \{player\} is replaced with the player’s name.

Lootbag Rewards

Grants a lootbag that can be collected via the Rewards UI (/rewards).

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

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

Examples:

"rewards": [
  { "type": "lootbag", "lootbagId": "welcome_gift" },
  { "type": "lootbag", "lootbagId": "miner_reward" },
  { "type": "lootbag", "lootbagId": "legendary_hoard" }
]

:::tip Pending Rewards Lootbags are stored as pending rewards and can be collected via /rewards. The toast notification shows “Lootbag” in the rewards line when an achievement grants a lootbag. :::

See Lootbags Configuration for detailed lootbag template configuration.

Titles

Achievements can grant unlockable titles.

"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 on the player’s nametag when selected via /titles.

Prerequisites

Achievements can require other achievements to be completed first.

Single prerequisite:

{
  "id": "spider_hunter_2",
  "requires": "spider_hunter_1",
  ...
}

Multiple prerequisites:

{
  "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 gallery shows chain progress as [2/5] and only displays the next unlockable achievement in the chain.

Hidden Achievements

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

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

Hidden achievements display as:

• Name: ”???”
• Description: ”???”
• Icon: Lock icon

Additional Info

Add custom notes to achievements:

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

This text appears below the rewards in the gallery.

Built-in Categories

The plugin includes 487 achievements across 6 categories:

Category	Count	Description
Combat	49	Killing mobs, PvP, combat milestones
Progression	102	Mining, crafting, building, general progress
Exploration	32	Zone discovery, distance traveled
Social	20	Chat messages, playtime hours
Husbandry	29	Animals, farming, fishing
Secret	37	Easter eggs, hidden challenges

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