Custom Achievements

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.

Quick Start

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 /achievements reload

Available Custom Files

File	Purpose
custom_achievements.json	General custom achievements
custom_mmo_achievements.json	Custom MMO Skill Tree achievements
custom_rpg_leveling_achievements.json	Custom RPG Leveling achievements

---

Achievement Structure

{
  "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"
      }
    }
  ]
}

---

Field Reference

Required Fields

Field	Type	Description
id	String	Unique identifier (lowercase, underscores)
category	String	Category for UI grouping
trigger	Object	What triggers this achievement

Optional Fields

Field	Type	Default	Description
iconItem	String	"Material_Stone"	Hytale item ID for icon
hidden	Boolean	false	Hide until unlocked
difficulty	String	"normal"	easy, normal, hard, epic
requires	String/Array	null	Prerequisite achievement ID(s)
showRequires	Boolean	true	Show prerequisite in UI
title	Object	null	Title reward
rewards	Array	[]	Item/lootbag rewards
additionalInfo	Object	null	Extra info text

---

Categories

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

---

Trigger Types

Block Triggers

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

Combat Triggers

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

Crafting Triggers

{ "type": "items_crafted", "target": "any", "count": 100 }
{ "type": "items_crafted", "target": "Tool_Pickaxe_Iron", "count": 1 }

Equipment Triggers

// 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 }

Progression Triggers

{ "type": "playtime_minutes", "target": null, "count": 6000 }
{ "type": "distance_walked", "target": null, "count": 10000 }
{ "type": "zones_discovered", "target": null, "count": 10 }

Social Triggers

{ "type": "chat_messages", "target": null, "count": 1000 }
{ "type": "emotes_used", "target": null, "count": 100 }

Integration Triggers

MMO Skill Tree (requires MMO SkillTree plugin):

// Reach Mining skill level 75
{ "type": "skill_level", "target": "mining", "count": 75 }

// Reach combined total skill level 500
{ "type": "total_skill_level", "target": null, "count": 500 }

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 }

Special Triggers

{ "type": "weekend_login", "target": null, "count": 1 }
{ "type": "manual", "target": null, "count": 1 }
{ "type": "auto_on_prerequisites", "target": null, "count": 0 }

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

---

Reward Types

Item Reward

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

Lootbag Reward

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

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

Field	Type	Description
type	String	"lootbag"
lootbagId	String	ID from lootbags.json or custom/custom_lootbags.json

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

Command Reward

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

MMO XP Reward

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

---

Title Colors

Use hex color codes:

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

Common colors:

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

---

Prerequisites (Chains)

Single Prerequisite

{
  "id": "miner_2",
  "requires": "miner_1"
}

Multiple Prerequisites

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

---

Overriding Existing Achievements

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.

---

Localization

Add translations in localization/en-US.json:

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

---

Validation

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”

---

Examples

Event Achievement

{
  "id": "summer_festival_2024",
  "category": "events",
  "iconItem": "Decoration_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"
  }
}

Boss Kill Achievement

{
  "id": "dragon_slayer",
  "category": "combat",
  "iconItem": "Material_Scale_Dragon",
  "difficulty": "epic",
  "trigger": { "type": "kills", "target": "Dragon", "count": 1 },
  "title": { "id": "dragonslayer", "color": "#FF0000" },
  "rewards": [
    { "type": "lootbag", "lootbagId": "legendary_loot" }
  ]
}

Skill Mastery Chain

{
  "id": "fishing_master",
  "category": "mmo_skills",
  "iconItem": "Tool_FishingRod",
  "difficulty": "epic",
  "requires": "fishing_75",
  "trigger": { "type": "skill_level", "target": "fishing", "count": 99 },
  "title": { "id": "master_angler", "color": "#00CED1" }
}

Custom MMO Achievement

{
  "id": "custom_mining_150",
  "category": "mmo_skills",
  "iconItem": "Tool_Pickaxe_Adamantite",
  "difficulty": "epic",
  "requires": "mining_100",
  "title": { "id": "legendary_miner", "color": "#FFD700" },
  "trigger": { "type": "skill_level", "target": "mining", "count": 150 },
  "rewards": [
    { "type": "item", "itemId": "Currency_Coin_Gold", "amount": 50 }
  ]
}

---

Best Practices

Naming Conventions

• Use snake_case for IDs: my_achievement_name
• Use descriptive names: diamond_miner_5 not dm5
• Use numbered suffixes for chains: _1, _2, _3

Difficulty Guidelines

Difficulty	When to Use
easy	First-tier, quick to complete
normal	Standard progression
hard	Requires significant effort
epic	End-game, rare achievements

Reward Balance

• 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

Hidden Achievements

Use hidden: true for:

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

---

Disabling Default Achievements

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 487 built-in achievements. Make sure you have replacements!