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

:::tip Admin window
Since 3.1.0 the easiest way is the [Admin Window](./admin-panel): 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.
:::

## 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 `/ksadmin reload` (KyuubiSoft Core reloads every KS mod)

## 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

```json
{
  "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

```json
{ "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

```json
{ "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:

```json
{ "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

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

### Equipment Triggers

```json
// 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

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

### Social Triggers

```json
{ "type": "chat_messages", "target": null, "count": 1000 }
{ "type": "npc_interact", "target": "blacksmith_gorn", "count": 1 }
{ "type": "dialog_complete", "target": "elder_story", "count": 1 }
```

### Integration Triggers

**MMO Skill Tree (requires MMO SkillTree plugin):**
```json
// 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.
:::

```json
```

**RPG Leveling (requires RPG Leveling plugin):**
```json
// 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):**
```json
// 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):**
```json
// 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

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

---

## Reward Types

### Item Reward

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

### Lootbag Reward

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

```json
{
  "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

```json
{
  "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](./permissions#command-rewards-that-run-as-the-console).

### MMO XP Reward

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

---

## Title Colors

Use hex color codes:

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

**Common colors:**
- `#FFD700` - Gold
- `#FF4444` - Red
- `#44FF44` - Green
- `#4444FF` - Blue
- `#9932CC` - Purple
- `#FF9800` - Orange

---

## Prerequisites (Chains)

### Single Prerequisite

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

### Multiple Prerequisites

```json
{
  "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:

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

---

## Localization

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

```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",
  "achievements.hint.my_custom_achievement": "Optional hint for a hidden achievement"
}
```

---

## 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"

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

---

## Examples

### Event Achievement

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

### Boss Kill Achievement

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

### Skill Mastery Chain

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

### Custom MMO Achievement

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

---

## 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`:

```json
{
  "loadDefaultAchievements": false
}
```

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

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