Achievements
This page explains the achievement structure and documents all built-in achievements.
Achievement Structure
Section titled “Achievement Structure”Each achievement is defined as a JSON object with the following fields:
{ "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
Section titled “Field Reference”Required Fields
Section titled “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
Section titled “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
Section titled “Triggers”Triggers define how achievements are unlocked. These are the trigger types the server really counts (the editor of the admin window 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) |
| 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
Section titled “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
Section titled “blocks_placed”Tracks blocks placed by the player.
{ "type": "blocks_placed", "target": "any", "count": 1000}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
Section titled “items_crafted”Tracks crafted items.
{ "type": "items_crafted", "target": "Weapon_Sword_Iron", "count": 1}zones_discovered
Section titled “zones_discovered”Tracks zone/area discoveries.
{ "type": "zones_discovered", "target": "any", "count": 10}chat_messages
Section titled “chat_messages”Tracks chat messages sent.
{ "type": "chat_messages", "count": 100}playtime_minutes
Section titled “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 book. :::
distance_walked
Section titled “distance_walked”Tracks walking distance in blocks.
{ "type": "distance_walked", "count": 10000}full_armor_set
Section titled “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
Section titled “equip_item”Tracks when a specific item is equipped.
{ "type": "equip_item", "target": "Weapon_Sword_Legendary"}manual
Section titled “manual”Admin-only manual grant. Cannot be unlocked through gameplay.
{ "type": "manual"}auto_on_prerequisites
Section titled “auto_on_prerequisites”Automatically unlocks when all prerequisites are met.
{ "type": "auto_on_prerequisites"}Rewards
Section titled “Rewards”Item Rewards
Section titled “Item Rewards”Grants items to the player’s inventory.
{ "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.
Command Rewards
Section titled “Command Rewards”Executes a server command.
{ "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.
:::
Lootbag Rewards
Section titled “Lootbag Rewards”Grants a lootbag that is opened in the Rewards tab of the book (/ksrewards).
{ "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 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 for detailed lootbag template configuration.
Titles
Section titled “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 in chat and on the nameplate when the player chooses them in the Titles tab of the book (/kstitles).
Prerequisites
Section titled “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
Section titled “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_4The book shows a chain as one line with the current stage (“Stage 2 / 5”); the detail panel shows the whole stage path.
Hidden Achievements
Section titled “Hidden Achievements”Set "hidden": true to hide an achievement until unlocked:
{ "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
Section titled “Additional Info”Add custom notes to achievements:
"additionalInfo": { "text": "Only available during the Summer Event!", "color": "#FF9900"}This text appears in the book’s detail panel.
Built-in Categories
Section titled “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.
Example Achievement Chains
Section titled “Example Achievement Chains”Monster Hunter (Combat)
Section titled “Monster Hunter (Combat)”- Kill 50 → 250 → 1,000 → 5,000 → 10,000 mobs
Miner (Progression)
Section titled “Miner (Progression)”- Mine 100 → 1,000 → 10,000 → 100,000 blocks
Playtime (Social)
Section titled “Playtime (Social)”- Play 1h → 5h → 10h → 25h → 50h → 100h → 250h → 500h → 1,000h
Distance Walker (Exploration)
Section titled “Distance Walker (Exploration)”- Walk 100 → 1,000 → 5,000 → 10,000 → 42,195 (marathon!) → 100,000 → 500,000 → 1,000,000 blocks