Skip to content

Custom Achievements

Server administrators can add their own achievements without modifying the default configuration files. Custom achievements support all features of standard achievements including titles, rewards, prerequisites, and custom triggers.

:::tip Admin window Since 3.1.0 the easiest way is the Admin Window: create achievements from templates, edit standard ones (stored as an override with the same id, so players keep their progress), and let the check view find mistakes before you save. This page describes the files the window writes. :::

  1. Navigate to your plugin’s custom/ folder
  2. Copy the .example template file and remove .example from the filename
  3. Edit the JSON to add your achievements
  4. Reload with /ksadmin reload (KyuubiSoft Core reloads every KS mod)
FilePurpose
custom_achievements.jsonGeneral custom achievements
custom_mmo_achievements.jsonCustom MMO Skill Tree achievements
custom_rpg_leveling_achievements.jsonCustom RPG Leveling achievements

{
"configVersion": 3,
"achievements": [
{
"id": "unique_achievement_id",
"category": "progression",
"iconItem": "Tool_Pickaxe_Iron",
"hidden": false,
"difficulty": "normal",
"requires": "prerequisite_achievement_id",
"showRequires": true,
"trigger": {
"type": "blocks_mined",
"target": "any",
"count": 500
},
"title": {
"id": "my_custom_title",
"color": "#FF5500"
},
"rewards": [
{
"type": "item",
"itemId": "Ore_Gold",
"amount": 5
}
],
"additionalInfo": {
"text": "Special event achievement!",
"color": "#FF9900"
}
}
]
}

FieldTypeDescription
idStringUnique identifier (lowercase, underscores)
categoryStringCategory for UI grouping
triggerObjectWhat triggers this achievement
FieldTypeDefaultDescription
iconItemString"Material_Stone"Hytale item ID for icon
hiddenBooleanfalseHide until unlocked
difficultyString"normal"easy, normal, hard, epic
requiresString/ArraynullPrerequisite achievement ID(s)
showRequiresBooleantrueShow prerequisite in UI
titleObjectnullTitle reward
rewardsArray[]Item/lootbag rewards
additionalInfoObjectnullExtra info text

Standard categories:

  • combat - Combat-related achievements
  • progression - General progression
  • exploration - Exploration and discovery
  • social - Social interactions
  • husbandry - Animal taming, farming, fishing
  • secret - Hidden/special achievements
  • mmo_skills - MMO Skill Tree related (auto-hidden if plugin not installed)
  • rpg_leveling - RPG Leveling related (auto-hidden if plugin not installed)

You can create custom categories using any string - they will automatically appear in the UI filter with a default icon.

:::tip Smart Filter Visibility The mmo_skills and rpg_leveling category filters automatically hide in the UI when their respective plugins are not installed. :::


{ "type": "blocks_mined", "target": "any", "count": 1000 }
{ "type": "blocks_mined", "target": "Ore_Iron", "count": 50 }
{ "type": "blocks_placed", "target": "any", "count": 500 }
{ "type": "blocks_chopped", "target": "any", "count": 500 }
{ "type": "blocks_dug", "target": "any", "count": 500 }
{ "type": "blocks_broken", "target": "any", "count": 2000 }
{ "type": "blocks_harvested", "target": "Crop_Wheat", "count": 100 }
{ "type": "flowers_picked", "target": "any", "count": 50 }

:::info Block Categories Blocks are automatically categorized by their group:

  • blocks_chopped — Wood group (trees, logs)
  • blocks_dug — Dirt, Sand, Gravel, Mud, Soil, Snow, Grass, Moss, Cover groups
  • blocks_mined — Stone and Ore groups
  • blocks_broken — Combined total of chopped + dug + mined
  • blocks_harvested — Crops and harvestable blocks
  • flowers_picked — Flower blocks

All block triggers also support specific block IDs and group prefixes (e.g., "group:Wood"). :::

{ "type": "kills", "target": "any_mob", "count": 100 }
{ "type": "kills", "target": "Trork", "count": 50 }
{ "type": "player_kills", "target": "any", "count": 10 }
{ "type": "deaths", "target": null, "count": 10 }
{ "type": "damage_dealt", "target": "any", "count": 50000 }
{ "type": "damage_dealt", "target": "any_mob", "count": 25000 }
{ "type": "damage_dealt", "target": "any_player", "count": 5000 }
{ "type": "damage_taken", "target": "any", "count": 10000 }
{ "type": "pvp_damage_dealt", "target": null, "count": 5000 }
{ "type": "pve_damage_dealt", "target": null, "count": 25000 }

:::tip Multi-Target Support Since v1.8.2, you can use comma-separated targets to match multiple entities or items:

{ "type": "kills", "target": "Spider,Spider_Cave,Spider_Frost", "count": 100 }
{ "type": "blocks_mined", "target": "Ore_Iron,Ore_Gold,Ore_Copper", "count": 500 }

All specified targets count towards the same achievement progress. :::

{ "type": "items_crafted", "target": "any", "count": 100 }
{ "type": "items_crafted", "target": "Tool_Pickaxe_Iron", "count": 1 }
// Trigger when wearing a full armor set
{ "type": "full_armor_set", "target": "iron", "count": 1 }
{ "type": "full_armor_set", "target": "adamantite", "count": 1 }
// Trigger when equipping a specific item
{ "type": "equip_item", "target": "Weapon_Sword_Adamantite", "count": 1 }
{ "type": "playtime_minutes", "target": null, "count": 6000 }
{ "type": "distance_walked", "target": null, "count": 10000 }
{ "type": "zones_discovered", "target": null, "count": 10 }
{ "type": "chat_messages", "target": null, "count": 1000 }
{ "type": "npc_interact", "target": "blacksmith_gorn", "count": 1 }
{ "type": "dialog_complete", "target": "elder_story", "count": 1 }

MMO Skill Tree (requires MMO SkillTree plugin):

// Reach Mining skill level 75 (target SKILL:LEVEL, count 1)
{ "type": "skill_level", "target": "MINING:75", "count": 1 }
// Reach combined total skill level 500
{ "type": "skill_level", "target": "total:500", "count": 1 }

:::caution Only milestones are sent MMO Skill Tree levels are only reported at the milestones 10, 25, 50, 75 and 100 per skill, and total: 100, 500, 1000, 1500, 2000 and 2300. Any other level never unlocks; the admin window’s check view warns about it. :::

RPG Leveling (requires RPG Leveling plugin):

// Reach character level 50
{ "type": "rpg_level", "target": "50", "count": 1 }
// Collect 100,000 total XP
{ "type": "rpg_xp", "target": "any", "count": 100000 }

Endless Leveling (requires Endless Leveling plugin):

// Reach character level 30
{ "type": "endless_level", "target": "30", "count": 1 }
// Collect 50,000 total XP
{ "type": "endless_xp", "target": "any", "count": 50000 }
// Reach Strength skill level 10
{ "type": "endless_skill_level", "target": "STRENGTH:10", "count": 1 }
// Select a specific race
{ "type": "endless_race", "target": "elf", "count": 1 }
// Select a specific class
{ "type": "endless_class", "target": "warrior", "count": 1 }

LevelingCore (requires LevelingCore plugin):

// Reach character level 25
{ "type": "leveling_level", "target": "25", "count": 1 }
// Collect 75,000 total XP
{ "type": "leveling_xp", "target": "any", "count": 75000 }
{ "type": "weekend_login", "target": null, "count": 1 }
{ "type": "manual", "target": null, "count": 1 }
{ "type": "auto_on_prerequisites", "target": null, "count": 0 }

Dungeons (requires KyuubiSoft Dungeons):

{ "type": "dungeon_complete_any", "target": null, "count": 5 }
{ "type": "dungeon_no_death", "target": null, "count": 1 }

Items collected counts the most of an item held at once, so dropping and picking up the same stack does not raise it:

{ "type": "items_collected", "target": "Ore_Onyxium", "count": 64 }

Targets accept wildcards such as Snake_* or Golem_Crystal_*.

:::info Weekend Login Trigger The weekend_login trigger fires automatically when a player logs in on Saturday or Sunday. Useful for “Weekend Warrior” type achievements. :::


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

Gives the player a lootbag that can be opened for randomized rewards.

{
"type": "lootbag",
"lootbagId": "rare_combat_loot"
}
FieldTypeDescription
typeString"lootbag"
lootbagIdStringID from lootbags.json or custom/custom_lootbags.json

Lootbags are defined in configs/lootbags.json (standard) or custom/custom_lootbags.json (custom).

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

executor is "console" (default when missing) or "player". Adding, changing or removing a console command reward needs ks.core.admin.dialog.console in the admin window and in web editor imports; see Permissions.

{
"type": "mmo_xp",
"skill": "Mining",
"amount": 5000
}

Use hex color codes:

{
"title": {
"id": "my_title",
"color": "#FF5500"
}
}

Common colors:

  • #FFD700 - Gold
  • #FF4444 - Red
  • #44FF44 - Green
  • #4444FF - Blue
  • #9932CC - Purple
  • #FF9800 - Orange

{
"id": "miner_2",
"requires": "miner_1"
}
{
"id": "jack_of_all_trades",
"requires": ["miner_1", "hunter_1", "explorer_1"],
"trigger": { "type": "auto_on_prerequisites", "target": null, "count": 0 }
}

To override a default achievement, use the same ID:

{
"id": "miner_1",
"category": "progression",
"difficulty": "easy",
"trigger": { "type": "blocks_mined", "target": "any", "count": 50 },
"title": { "id": "starter_miner", "color": "#8B4513" },
"rewards": [
{ "type": "item", "itemId": "Tool_Pickaxe_Copper", "amount": 1 }
]
}

This will completely replace the default miner_1 achievement. Because the id stays the same, players keep their progress and titles.


Add translations in localization/custom_en-US.json (custom files are never overwritten by updates):

{
"achievements.name.my_custom_achievement": "Custom Achievement Name",
"achievements.desc.my_custom_achievement": "Description of what to do",
"achievements.title.my_custom_title": "Custom Title",
"achievements.hint.my_custom_achievement": "Optional hint for a hidden achievement"
}

The plugin validates achievements on load:

  • Duplicate IDs are rejected
  • Missing prerequisite IDs are logged as warnings
  • Circular dependencies are detected and rejected
  • Invalid triggers default to “manual”

The admin window’s check view goes further (unknown items, lootbags and skills, an id equal to a trigger type, skill_level targets that never fire, abuse-prone triggers with rewards).

:::warning Do not use a trigger type as id An achievement whose id equals a trigger type (for example a Dungeons trigger) would take over that trigger’s counter. The check view reports it as an error. :::


{
"id": "summer_festival_2024",
"category": "events",
"iconItem": "Deco_Lantern",
"difficulty": "normal",
"hidden": true,
"trigger": { "type": "manual", "target": null, "count": 1 },
"title": { "id": "festival_goer", "color": "#FFD700" },
"additionalInfo": {
"text": "Summer Festival 2024 Exclusive!",
"color": "#FF9900"
}
}
{
"id": "dragon_slayer",
"category": "combat",
"iconItem": "Ingredient_Leather_Scaled",
"difficulty": "epic",
"trigger": { "type": "kills", "target": "Dragon", "count": 1 },
"title": { "id": "dragonslayer", "color": "#FF0000" },
"rewards": [
{ "type": "lootbag", "lootbagId": "legendary_loot" }
]
}
{
"id": "fishing_master",
"category": "mmo_skills",
"iconItem": "Tool_Fishing_Trap",
"difficulty": "epic",
"requires": "fishing_75",
"trigger": { "type": "skill_level", "target": "FISHING:100", "count": 1 },
"title": { "id": "master_angler", "color": "#00CED1" }
}
{
"id": "custom_total_2000",
"category": "mmo_skills",
"iconItem": "Tool_Pickaxe_Adamantite",
"difficulty": "epic",
"requires": "total_level_1500",
"title": { "id": "legendary_miner", "color": "#FFD700" },
"trigger": { "type": "skill_level", "target": "total:2000", "count": 1 },
"rewards": [
{ "type": "item", "itemId": "Ingredient_Bar_Gold", "amount": 50 }
]
}

  • Use snake_case for IDs: my_achievement_name
  • Use descriptive names: diamond_miner_5 not dm5
  • Use numbered suffixes for chains: _1, _2, _3
DifficultyWhen to Use
easyFirst-tier, quick to complete
normalStandard progression
hardRequires significant effort
epicEnd-game, rare achievements
  • Easy achievements: Small rewards (10-50 gold)
  • Normal achievements: Medium rewards (50-200 gold)
  • Hard achievements: Good rewards + titles
  • Epic achievements: Best rewards + unique titles

Use hidden: true for:

  • Easter eggs
  • Secret discoveries
  • Event achievements
  • Spoiler content

To use ONLY custom achievements, set in config.json:

{
"loadDefaultAchievements": false
}

This will skip loading configs/achievements.json but still load MMO and RPG Leveling achievements if their files exist.

This removes all 277 standard achievements. Make sure you have replacements! To switch off single achievements instead, use Disable in the admin window (disabledAchievements).