# Configuration

# Configuration

The plugin uses `config.json` in `mods/kyuubisoft_achievements/` for all settings. Most options can also be changed in the [Admin Window](./admin-panel#settings), which writes the same file.

## Folder Structure

**Key Features:**
- **Versioned Standard Configs** - All standard configs have version numbers for automatic updates
- **Individual Toggle** - Each standard config can be disabled individually
- **Custom Overrides** - Custom configs are always loaded and never overwritten

```
mods/kyuubisoft_achievements/
├── config.json                              # Main plugin configuration
├── README.md                                # Documentation
│
├── configs/                                 # Standard configs (DO NOT MODIFY!)
│   ├── achievements.json                    # Default achievements
│   ├── mmo_achievements.json                # MMO Skill Tree achievements
│   ├── rpg_leveling_achievements.json       # RPG Leveling achievements
│   └── lootbags.json                        # Lootbag definitions
│
├── custom/                                  # Custom configs for server admins
│   ├── custom_achievements.json             # Your custom achievements
│   ├── custom_achievements.json.example     # Template
│   ├── custom_mmo_achievements.json         # Your custom MMO skill achievements
│   ├── custom_mmo_achievements.json.example # Template
│   ├── custom_rpg_leveling_achievements.json         # Your custom RPG leveling achievements
│   ├── custom_rpg_leveling_achievements.json.example # Template
│   ├── custom_lootbags.json                 # Your custom lootbags
│   └── custom_lootbags.json.example         # Template
│
├── localization/                            # Language files (9 languages)
│   ├── en-US.json, de-DE.json, es-ES.json, fr-FR.json, it-IT.json,
│   │   pl-PL.json, pt-BR.json, ru-RU.json, tr-TR.json
│   ├── custom_<lang>.json                   # Your own translations (never overwritten)
│   └── custom_en-US.json.example, custom_de-DE.json.example
│
├── players/                                 # Player data (file storage)
├── stats/                                   # Statistics export, server records
├── backups/                                 # Backup sets of the admin window (last 20)
└── admin/                                   # Players tool: action log, queued offline actions
```

### Root Folder

- **config.json** - Main plugin configuration (language, display settings, notifications, etc.)
- **README.md** - Quick reference documentation

### configs/ Folder

Contains standard achievement definitions that ship with the plugin. **These files should NOT be modified** as they may be overwritten during plugin updates.

| File | Description |
|------|-------------|
| `achievements.json` | Core achievements (combat, progression, exploration, social) |
| `mmo_achievements.json` | Achievements for MMO Skill Tree integration (skill levels) |
| `rpg_leveling_achievements.json` | Achievements for RPG Leveling integration (character level, XP, mob kills) |
| `lootbags.json` | 20 lootbag rewards with item pools and weighted chances |

### custom/ Folder

Contains custom achievement definitions created by server administrators. **These files are NEVER overwritten** by plugin updates.

| File | Description |
|------|-------------|
| `custom_achievements.json` | General custom achievements |
| `custom_mmo_achievements.json` | Custom MMO skill achievements |
| `custom_rpg_leveling_achievements.json` | Custom RPG leveling achievements |
| `custom_lootbags.json` | Custom lootbag definitions |
| `*.example` | Template files showing the correct format |

### localization/ Folder

Contains language files for the plugin UI and messages. **Standard files may be updated** during plugin updates, but **custom files are NEVER overwritten**.

| File | Description |
|------|-------------|
| `<lang>.json` | Shipped translations for the 9 languages (replaced when a new version ships newer texts) |
| `custom_*.json` | Custom translation overrides (never overwritten) |
| `custom_*.json.example` | Templates for custom translations |

#### Custom Translation Files

Custom translation files allow you to override or add translations without losing them during updates:

1. Copy `custom_en-US.json.example` to `custom_en-US.json`
2. Add only the keys you want to override
3. Custom translations are merged on top of standard translations

**Example: Custom Lootbag Translations**
```json
{
  "lootbag.name.my_custom_bag": "Epic Treasure Chest",
  "lootbag.desc.my_custom_bag": "Contains rare treasures from the depths!"
}
```

### How Custom Achievements Work

**Adding New Achievements:**
1. Copy the `.example` template to remove the `.example` extension
2. Add your achievements to the `achievements` array
3. Reload with `/ksadmin reload` (KyuubiSoft Core reloads every KS mod), or create the achievement in the [Admin Window](./admin-panel) instead

**Overriding Existing Achievements:**
Custom achievements with the **same ID** as a standard achievement will **override** it. This allows you to:
- Change rewards for existing achievements
- Modify difficulty or requirements
- Add custom titles to standard achievements

The admin window does exactly this when you edit a standard achievement, so players keep their progress and titles. **Reset to default** removes the override again.

**Example: Custom MMO Achievement**
```json
{
  "configVersion": 3,
  "achievements": [
    {
      "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 }
      ]
    }
  ]
}
```

### Load Order

**Achievements** are loaded in this order:
1. `configs/achievements.json` (if `loadDefaultAchievements` is true)
2. `custom/custom_achievements.json` (merges/overrides)
3. `configs/mmo_achievements.json` (if `loadMmoAchievements` is true)
4. `custom/custom_mmo_achievements.json` (merges/overrides)
5. `configs/rpg_leveling_achievements.json` (if `loadRpgLevelingAchievements` is true)
6. `custom/custom_rpg_leveling_achievements.json` (merges/overrides)

**Lootbags** are loaded in this order:
1. `configs/lootbags.json` (standard lootbags)
2. `custom/custom_lootbags.json` (merges/overrides)

The result is registered in KyuubiSoft Core's lootbag registry (Core's own bags with the same id win). See [Lootbags](./lootbags).

**Localization** is loaded in this order:
1. `localization/{language}.json` (e.g., `en-US.json`)
2. `localization/custom_{language}.json` (merges/overrides)

### Disabling Standard Configs

Each standard config can be individually disabled in `config.json`. When disabled, only the corresponding custom config will be loaded.

```json
{
  "loadDefaultAchievements": true,     // configs/achievements.json
  "loadMmoAchievements": true,         // configs/mmo_achievements.json
  "loadRpgLevelingAchievements": true  // configs/rpg_leveling_achievements.json
}
```

**Examples:**

Use only custom achievements (disable all standard):
```json
{
  "loadDefaultAchievements": false,
  "loadMmoAchievements": false,
  "loadRpgLevelingAchievements": false
}
```

Use standard achievements but custom MMO/RPG:
```json
{
  "loadDefaultAchievements": true,
  "loadMmoAchievements": false,
  "loadRpgLevelingAchievements": false
}
```

:::note
Custom configs (`custom/*.json`) are ALWAYS loaded regardless of these settings.
:::

### Config Versioning

All standard configs include a version number (`configVersion`). When the plugin updates a config structure:

1. The plugin detects the outdated version
2. Creates a backup (e.g., `achievements.json.backup-v1`)
3. Extracts the new version from the plugin
4. Reloads the updated config

This ensures you always have the latest achievements and fixes without manual intervention. The current standard files are `achievements.json` and `lootbags.json` version 4. Custom entries that were added to `configs/achievements.json` by hand are moved to `custom/` before the file is replaced.

---

## Complete Configuration Example

```json
{
  "language": "en-US",
  "loadDefaultAchievements": true,
  "loadMmoAchievements": true,
  "loadRpgLevelingAchievements": true,

  "display": {
    "displayMode": "both",
    "titlePosition": "prefix",
    "nametagFormat": "{title}\\n{name}",
    "chatFormat": "[{title}] {name}: {message}",
    "titleColor": "#FFD700",
    "showRpgLevel": false,
    "rpgLevelFormat": "Lv.{level}",
    "rpgLevelColor": "#55FFFF",
    "rpgLevelPosition": "after_name",
    "showRarity": true,
    "showServerFirst": true
  },

  "notifications": {
    "enabled": true,
    "displayMode": "banner",
    "displayDurationMs": 5000,
    "showRewardsInBanner": true,
    "broadcastToChat": false,
    "broadcastFormat": "{player} unlocked: {achievement}",
    "pendingRewardHint": true
  },

  "points": {
    "easy": 10,
    "normal": 10,
    "hard": 25,
    "epic": 50,
    "legendary": 10
  },

  "tracking": {
    "saveIntervalSeconds": 300,
    "ignoreCreativeMode": true,
    "enableExploration": true,
    "enableCombat": true,
    "enableProgression": true,
    "enableSocial": true
  },

  "admin": {
    "cascadeRevoke": false,
    "cascadeRevokeWarning": true,
    "bypassPrerequisites": false
  },

  "export": {
    "enabled": true,
    "intervalSeconds": 300,
    "exportGlobalStats": true,
    "exportLeaderboards": true,
    "exportRecentUnlocks": true,
    "leaderboardSize": 100,
    "recentUnlocksSize": 50,
    "includePlayerTotals": true
  },

  "item": {
    "enabled": true,
    "itemId": "AchievementBook",
    "giveOnFirstJoin": true,
    "giveOnEveryJoin": false,
    "hotbarSlot": 7,
    "giveDelaySeconds": 3
  },

  "trackerHud": {
    "enabled": true
  },

  "categoryOrder": [],
  "categoryIcons": {},
  "disabledAchievements": [],

  "groupPrefixes": {
    "admin": {
      "prefix": "<red>[Admin]</red> ",
      "priority": 100
    },
    "vip": {
      "prefix": "<gold>[VIP]</gold> ",
      "priority": 50
    }
  }
}
```

## Configuration Sections

### General Settings

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `language` | string | `"en-US"` | Old server language field. Since 3.0.1 the server language and the default player language are set for all KyuubiSoft mods in KyuubiSoft Core's settings window (`/kssettings`); the admin window no longer shows this field |
| `loadDefaultAchievements` | boolean | `true` | Load `configs/achievements.json`. Set to `false` for fully custom setups |
| `loadMmoAchievements` | boolean | `true` | Load `configs/mmo_achievements.json` (MMO Skill Tree achievements) |
| `loadRpgLevelingAchievements` | boolean | `true` | Load `configs/rpg_leveling_achievements.json` (RPG Leveling achievements) |

:::info Per-Player Language
Players choose their language for every KyuubiSoft mod in `/kssettings` or with `/kslang <code>` (en-US, de-DE, es-ES, fr-FR, it-IT, pl-PL, pt-BR, ru-RU, tr-TR). The book's language line opens the same page. Whether players may choose and the default for new players are set by the server in `/kssettings` (KyuubiSoft Core 2.8.0+).
:::

### Display Settings

Controls how titles appear on player nametags and in chat.

:::warning Hytale Nameplate Limitations
Due to Hytale engine restrictions, nameplates have the following limitations:
- **No colors** - Nameplates only support plain text. Color codes (legacy `&a`, hex `#FF0000`, MiniMessage `<red>`) are ignored
- **No multiline** - Newline characters (`\n`) are ignored. Text cannot be displayed on multiple lines above a player

Color formatting only works in **chat messages** (via `chatFormat`). The `titleColor` and `rpgLevelColor` settings only affect chat display.
:::

```json
"display": {
  "displayMode": "both",
  "titlePosition": "prefix",
  "nametagFormat": "{title} {name}",
  "chatFormat": "{title} {name}: {message}",
  "titleColor": "#FFD700",
  "showRpgLevel": false,
  "rpgLevelFormat": "Lv.{level}",
  "rpgLevelColor": "#55FFFF",
  "rpgLevelPosition": "after_name"
}
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `displayMode` | string | `"both"` | Where to show titles: `"nametag"`, `"chat"`, or `"both"` |
| `titlePosition` | string | `"prefix"` | Title position (see table below) |
| `nametagFormat` | string | `"\{title\} \{name\}"` | Format for nametag display |
| `chatFormat` | string | `"\{title\} \{name\}: \{message\}"` | Format for chat messages |
| `titleColor` | string | `"#FFD700"` | Color for titles in chat (hex). **Chat only** |
| `showRpgLevel` | boolean | `false` | Show player level from RPGLeveling plugin |
| `rpgLevelFormat` | string | `"Lv.\{level\}"` | Format for level display. `\{level\}` is replaced with the actual level |
| `rpgLevelColor` | string | `"#55FFFF"` | Color for level in chat (hex). **Chat only** |
| `rpgLevelPosition` | string | `"after_name"` | Level position: `"before_name"`, `"after_name"`, or `"after_title"` |
| `showRarity` | boolean | `true` | Show the share of players who have an achievement in the book |
| `showServerFirst` | boolean | `true` | Show the first player on the server who unlocked it |

:::info KyuubiSoft Nameplates
With KyuubiSoft Nameplates installed, the active title is handed over as a nameplate tag instead of overwriting the nameplate text. The RPG level that the title nametag used to add is then not shown.
:::

#### Title Position

| Config Value | Nametag Result | Chat Result |
|--------------|----------------|-------------|
| `"prefix"` | `[Title] Username` | `[Title] Username: message` |
| `"suffix"` | `Username [Title]` | `Username [Title]: message` |
| `"above"` | `[Title] Username` *(same as prefix)* | `[Title] Username: message` |
| `"below"` | `Username [Title]` *(same as suffix)* | `Username [Title]: message` |

:::note
Due to Hytale nameplate limitations, `"above"` and `"below"` behave identically to `"prefix"` and `"suffix"` respectively. True vertical positioning above/below the player name is not currently possible.
:::

**Placeholders:**
- `\{title\}` - Player's active title
- `\{name\}` - Player's username
- `\{message\}` - Chat message content (chat format only)
- `\{level\}` - Player's RPG level (in rpgLevelFormat only)

#### RPG Level Positions

| Position | Nametag Example | Chat Example |
|----------|-----------------|--------------|
| `before_name` | `[Title] [Lv.15] Username` | `[Title] [Lv.15] Username: message` |
| `after_name` | `[Title] Username [Lv.15]` | `[Title] Username [Lv.15]: message` |
| `after_title` | `[Title] [Lv.15] Username` | `[Title] [Lv.15] Username: message` |

:::note RPGLeveling Required
The `showRpgLevel` feature requires the RPGLeveling plugin to be installed. If not present, the level will not be displayed regardless of this setting.
:::

### Notification Settings

Controls achievement unlock notifications.

```json
"notifications": {
  "enabled": true,
  "displayMode": "banner",
  "displayDurationMs": 5000,
  "showRewardsInBanner": true,
  "broadcastToChat": false,
  "broadcastFormat": "{player} unlocked: {achievement}",
  "pendingRewardHint": true
}
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | boolean | `true` | Enable/disable notifications |
| `displayMode` | string | `"banner"` | `"banner"` = one HUD toast, `"chat"` = one chat line, `"both"`. New installs use `banner`; existing configs keep their value |
| `displayDurationMs` | number | `5000` | Toast duration in milliseconds |
| `showRewardsInBanner` | boolean | `true` | Show the reward hint in the toast or chat line |
| `broadcastToChat` | boolean | `false` | Announce unlocks to all players (each in their own language; colour codes in the format are stripped) |
| `broadcastFormat` | string | `"\{player\} unlocked: \{achievement\}"` | Broadcast message format |
| `pendingRewardHint` | boolean | `true` | Once per session after join: tell players that rewards are waiting |

### Points

Achievement points per difficulty. The defaults are the values before 3.0.0. Points are a shop currency, see [Achievement Points](./achievement-points).

| Option | Default |
|--------|---------|
| `points.easy` | `10` |
| `points.normal` | `10` |
| `points.hard` | `25` |
| `points.epic` | `50` |
| `points.legendary` | `10` |

### Tracking Settings

Controls which achievement categories are tracked.

```json
"tracking": {
  "saveIntervalSeconds": 300,
  "ignoreCreativeMode": true,
  "enableExploration": true,
  "enableCombat": true,
  "enableProgression": true,
  "enableSocial": true
}
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `saveIntervalSeconds` | number | `300` | Auto-save interval (5 minutes default) |
| `ignoreCreativeMode` | boolean | `true` | Ignore achievement progress when player is in creative mode |
| `enableExploration` | boolean | `true` | Track exploration achievements |
| `enableCombat` | boolean | `true` | Track combat achievements |
| `enableProgression` | boolean | `true` | Track progression achievements |
| `enableSocial` | boolean | `true` | Track social achievements |

Creative mode is ignored for single triggers, "total" achievements and statistics.

### Admin Settings

Controls administrative behavior.

```json
"admin": {
  "cascadeRevoke": false,
  "cascadeRevokeWarning": true,
  "bypassPrerequisites": false
}
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `cascadeRevoke` | boolean | `false` | Revoke dependent achievements when parent is revoked |
| `cascadeRevokeWarning` | boolean | `true` | `/acadmin revoke` names the dependent achievements first (online players) |
| `bypassPrerequisites` | boolean | `false` | No effect: admin grants always skip prerequisites. Kept in the file, not shown in the admin window |

### Export Settings

Controls statistics export for external tools.

```json
"export": {
  "enabled": true,
  "intervalSeconds": 300,
  "exportGlobalStats": true,
  "exportLeaderboards": true,
  "exportRecentUnlocks": true,
  "leaderboardSize": 100,
  "recentUnlocksSize": 50,
  "includePlayerTotals": true
}
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | boolean | `true` | Enable statistics export |
| `intervalSeconds` | number | `300` | Export frequency |
| `exportGlobalStats` | boolean | `true` | Include global statistics |
| `exportLeaderboards` | boolean | `true` | Include player leaderboards |
| `exportRecentUnlocks` | boolean | `true` | Include recent unlock history |
| `leaderboardSize` | number | `100` | Number of top players |
| `recentUnlocksSize` | number | `50` | Number of recent unlocks |
| `includePlayerTotals` | boolean | `true` | Include per-player totals |

### Group Prefixes (LuckPerms Integration)

Configure custom prefixes per LuckPerms group.

```json
"groupPrefixes": {
  "admin": {
    "prefix": "<red>[Admin]</red> ",
    "priority": 100
  },
  "moderator": {
    "prefix": "<blue>[Mod]</blue> ",
    "priority": 75
  },
  "vip": {
    "prefix": "<gold>[VIP]</gold> ",
    "priority": 50
  },
  "default": {
    "prefix": "",
    "priority": 0
  }
}
```

| Option | Type | Description |
|--------|------|-------------|
| `prefix` | string | Prefix text with MiniMessage formatting |
| `color` | string | Hex color code for the prefix (e.g., `"#FF5555"`) |
| `priority` | number | Higher priority takes precedence |

**Supported Color Formats:**
- MiniMessage tags: `<red>`, `<gold>`, `<#FF5555>`
- Gradients: `<gradient:#FF0000:#00FF00>Text</gradient>`
- Rainbow: `<rainbow>Text</rainbow>`
- Legacy codes: `&a`, `&b`, `&c`, etc.

:::tip LuckPerms Integration
If LuckPerms is installed, the plugin automatically retrieves prefixes from LuckPerms groups. The `groupPrefixes` config serves as a fallback or override.
:::

### Item Settings

Controls the Achievement Book item that opens the achievement book when used. Since 3.1.3 the item is green (Uncommon), so it is easy to tell apart from the Quest Book and the Info Hub book.

```json
"item": {
  "enabled": true,
  "itemId": "AchievementBook",
  "giveOnFirstJoin": true,
  "giveOnEveryJoin": false,
  "hotbarSlot": 7,
  "giveDelaySeconds": 3
}
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | boolean | `true` | Enable/disable the Achievement Book item |
| `itemId` | string | `"AchievementBook"` | Item ID for the achievement book |
| `giveOnFirstJoin` | boolean | `true` | Give the book to players on their first join |
| `giveOnEveryJoin` | boolean | `false` | Give the book to players on every join |
| `hotbarSlot` | number | `7` | Hotbar slot where the book is placed (0-8) |
| `giveDelaySeconds` | number | `3` | Delay in seconds before giving the book after join |

:::info
If `giveOnEveryJoin` is `true`, players will receive the book each time they log in. If `giveOnFirstJoin` is `true` (and `giveOnEveryJoin` is `false`), players only receive it on their very first login.
:::

### Tracker HUD Settings

Controls the on-screen achievement tracker HUD. See [Tracker HUD](./tracker-hud) for detailed documentation.

```json
"trackerHud": {
  "enabled": true
}
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | boolean | `true` | Enable/disable the tracker HUD globally |

:::info
The tracker has a fixed place on the screen. The older key `trackerHud.position` is ignored.
:::

### Categories and disabled achievements (3.1.0)

These fields are written by the [Admin Window](./admin-panel). Empty means the behaviour before 3.1.0.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `categoryOrder` | array | `[]` | Order of the categories in the book; empty = built-in order |
| `categoryIcons` | object | `{}` | Item icon per category id |
| `disabledAchievements` | array | `[]` | Ids that are not shown, counted or tracked (player data stays; a prerequisite on a disabled achievement counts as met) |

New options are added to an existing `config.json` with their defaults on start; values already in the file are kept. A `config.json` that cannot be read is never overwritten.