Custom Achievements

Create unique achievements for your server by editing the custom_achievements.json file.

Getting Started

Step 1: Create the File

Create custom_achievements.json in your plugin folder:

plugins/achievements/
├── config.json
├── achievements.json        ← Default achievements (don't edit)
└── custom_achievements.json ← Your custom achievements

Step 2: Basic Structure

{
  "achievements": [
    {
      "id": "my_first_achievement",
      "category": "progression",
      "trigger": {
        "type": "blocks_mined",
        "target": "any",
        "count": 100
      }
    }
  ]
}

Step 3: Restart Server

Restart your server or use a reload command. Custom achievements are merged with defaults.

Complete Example

Here's a fully-featured custom achievement:

{
  "achievements": [
    {
      "id": "summer_event_champion",
      "category": "secret",
      "iconItem": "Trophy_Gold",
      "hidden": true,
      "difficulty": "epic",
      "custom": true,
      "title": {
        "id": "summer_champion",
        "color": "#FFD700"
      },
      "trigger": {
        "type": "manual"
      },
      "rewards": [
        {
          "type": "item",
          "itemId": "Cosmetic_Summer_Crown",
          "amount": 1
        },
        {
          "type": "command",
          "command": "broadcast {player} is the Summer Event Champion!",
          "executor": "console"
        }
      ],
      "additionalInfo": {
        "text": "Awarded to Summer Event winners!",
        "color": "#FF9900"
      }
    }
  ]
}

Overriding Default Achievements

To modify a built-in achievement, use the same id:

{
  "achievements": [
    {
      "id": "first_blood",
      "category": "combat",
      "trigger": {
        "type": "kills",
        "target": "any_mob",
        "count": 10
      },
      "rewards": [
        {
          "type": "item",
          "itemId": "Material_Diamond",
          "amount": 5
        }
      ]
    }
  ]
}

This replaces the default first_blood achievement entirely.

Creating Achievement Chains

Simple Chain

{
  "achievements": [
    {
      "id": "server_veteran_1",
      "category": "social",
      "difficulty": "easy",
      "trigger": {
        "type": "playtime_minutes",
        "count": 1440
      },
      "title": {
        "id": "newcomer",
        "color": "#AAAAAA"
      }
    },
    {
      "id": "server_veteran_2",
      "category": "social",
      "difficulty": "normal",
      "requires": "server_veteran_1",
      "trigger": {
        "type": "playtime_minutes",
        "count": 10080
      },
      "title": {
        "id": "regular",
        "color": "#55FF55"
      }
    },
    {
      "id": "server_veteran_3",
      "category": "social",
      "difficulty": "hard",
      "requires": "server_veteran_2",
      "trigger": {
        "type": "playtime_minutes",
        "count": 43200
      },
      "title": {
        "id": "veteran",
        "color": "#FFD700"
      }
    }
  ]
}

Multi-Prerequisite Achievement

{
  "id": "master_of_all",
  "category": "secret",
  "difficulty": "epic",
  "requires": [
    "combat_master",
    "mining_master",
    "exploration_master"
  ],
  "trigger": {
    "type": "auto_on_prerequisites"
  },
  "title": {
    "id": "grandmaster",
    "color": "#FF55FF"
  }
}

Localization

Add translations for your custom achievements in language files.

English (en-US/achievements.lang)

achievements.name.summer_event_champion=Summer Event Champion
achievements.desc.summer_event_champion=Win the Summer Event competition
achievements.title.summer_champion=Summer Champion

German (de-DE/achievements.lang)

achievements.name.summer_event_champion=Sommer-Event Champion
achievements.desc.summer_event_champion=Gewinne den Sommer-Event Wettbewerb
achievements.title.summer_champion=Sommer-Champion

Fallback Behavior

If no translation is found, the plugin uses the achievement id formatted as a display name.

Event Achievements

Time-Limited Event

{
  "id": "halloween_2024",
  "category": "secret",
  "hidden": true,
  "trigger": {
    "type": "manual"
  },
  "additionalInfo": {
    "text": "Halloween 2024 - Limited Time!",
    "color": "#FF6600"
  },
  "rewards": [
    {
      "type": "item",
      "itemId": "Cosmetic_Pumpkin_Head",
      "amount": 1
    }
  ]
}

Grant manually during the event:

/achievementadmin grant PlayerName halloween_2024

Competitive Achievement

{
  "id": "pvp_tournament_winner",
  "category": "combat",
  "difficulty": "epic",
  "trigger": {
    "type": "manual"
  },
  "title": {
    "id": "champion",
    "color": "#FF5555"
  },
  "rewards": [
    {
      "type": "command",
      "command": "lp user {player} parent add pvp_champion",
      "executor": "console"
    }
  ]
}

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

Validation

The plugin validates achievements on load:

• Duplicate IDs: Warning logged, last definition wins
• Circular prerequisites: Error logged, achievement disabled
• Missing prerequisites: Warning logged, requirement ignored
• Invalid triggers: Error logged, achievement disabled

Check server logs after adding custom achievements:

[KyuubiSoft Achievements] Loaded 5 custom achievements
[KyuubiSoft Achievements] Warning: Achievement 'my_chain_2' requires unknown 'my_chain_1'

Disabling Default Achievements

To use only custom achievements:

1. Set in config.json:

{
  "loadDefaultAchievements": false
}

2. Create all achievements in custom_achievements.json

warning

This removes all 487 built-in achievements. Make sure you have replacements!