Configuration

The plugin uses config.json for all settings. This page documents every available option.

Folder Structure

Version 1.6.0+

Starting with version 1.6.0, the Achievement Plugin uses a new organized folder structure that separates standard configurations from custom configurations.

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

KyuubiAchievements/
├── 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
    ├── en-US.json                           # English (default)
    ├── de-DE.json                           # German
    ├── fr-FR.json                           # French
    ├── custom_en-US.json                    # Custom English translations
    ├── custom_de-DE.json                    # Custom German translations
    ├── custom_en-US.json.example            # Custom translation template
    └── custom_de-DE.json.example            # Custom translation template

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`	Lootbag definitions 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

Version 1.8.5+

Starting with version 1.8.5, all language files are stored in the 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
`en-US.json`	English translations (default)
`de-DE.json`	German translations
`fr-FR.json`	French translations
`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:

Copy custom_en-US.json.example to custom_en-US.json
Add only the keys you want to override
Custom translations are merged on top of standard translations

Example: Custom Lootbag Translations

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

Copy the .example template to remove the .example extension
Add your achievements to the achievements array
Reload the plugin with /achievements reload

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

Example: Custom MMO Achievement

{
  "configVersion": 3,
  "achievements": [
    {
      "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 }
      ]
    }
  ]
}

Load Order

Achievements are loaded in this order:

configs/achievements.json (if loadDefaultAchievements is true)
custom/custom_achievements.json (merges/overrides)
configs/mmo_achievements.json (if loadMmoAchievements is true)
custom/custom_mmo_achievements.json (merges/overrides)
configs/rpg_leveling_achievements.json (if loadRpgLevelingAchievements is true)
custom/custom_rpg_leveling_achievements.json (merges/overrides)

Lootbags are loaded in this order:

configs/lootbags.json (standard lootbags)
custom/custom_lootbags.json (merges/overrides)

Localization is loaded in this order:

localization/{language}.json (e.g., en-US.json)
localization/custom_{language}.json (merges/overrides)

Migration from v1.5.x

If upgrading from v1.5.x:

The plugin will automatically create the new folder structure
Existing achievements.json in the root folder will be migrated to configs/
Existing custom achievements will need to be manually moved to custom/

Disabling Standard Configs

Each standard config can be individually disabled in config.json. When disabled, only the corresponding custom config will be loaded.

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

{
  "loadDefaultAchievements": false,
  "loadMmoAchievements": false,
  "loadRpgLevelingAchievements": false
}

Use standard achievements but custom MMO/RPG:

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

The plugin detects the outdated version
Creates a backup (e.g., achievements.json.backup-v1)
Extracts the new version from the plugin
Reloads the updated config

This ensures you always have the latest achievements and fixes without manual intervention.

Complete Configuration Example

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

  "notifications": {
    "enabled": true,
    "displayMode": "chat",
    "displayDurationMs": 5000,
    "showRewardsInBanner": true,
    "broadcastToChat": false,
    "broadcastFormat": "{player} unlocked: {achievement}"
  },

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

  "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"`	Default server language for UI and messages. Options: `"en-US"`, `"de-DE"`, `"fr-FR"`, `"es-ES"`, `"pt-BR"`, `"it-IT"`, `"pl-PL"`, `"ru-RU"`, `"ja-JP"`
`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)

Per-Player Language (v2.5.0+)

Since version 2.5.0, players can override the server language with their own preference using /kslang <language>. The language setting in config.json serves as the default for players who have not set a preference. All 9 languages listed above are supported per-player.

Display Settings

Controls how titles appear on player nametags and in chat.

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.

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

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`

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.

"notifications": {
  "enabled": true,
  "displayMode": "chat",
  "displayDurationMs": 5000,
  "showRewardsInBanner": true,
  "broadcastToChat": false,
  "broadcastFormat": "{player} unlocked: {achievement}"
}

Option	Type	Default	Description
`enabled`	boolean	`true`	Enable/disable notifications
`displayMode`	string	`"both"`	Notification type: `"chat"`, `"banner"`, or `"both"`
`displayDurationMs`	number	`5000`	Toast banner duration in milliseconds
`showRewardsInBanner`	boolean	`true`	Show rewards in toast notification
`broadcastToChat`	boolean	`false`	Announce unlocks to all players
`broadcastFormat`	string	`"\{player\} unlocked: \{achievement\}"`	Broadcast message format

Tracking Settings

Controls which achievement categories are tracked.

"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

Admin Settings

Controls administrative behavior.

"admin": {
  "cascadeRevoke": false,
  "cascadeRevokeWarning": true,
  "bypassPrerequisites": false
}

Option	Type	Default	Description
`cascadeRevoke`	boolean	`false`	Revoke dependent achievements when parent is revoked
`cascadeRevokeWarning`	boolean	`true`	Warn admin before cascade revoke
`bypassPrerequisites`	boolean	`false`	Admin grant bypasses prerequisites

Export Settings

Controls statistics export for external tools.

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

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

LuckPerms Integration

If LuckPerms is installed, the plugin automatically retrieves prefixes from LuckPerms groups. The groupPrefixes config serves as a fallback or override.

Folder Structure​

Root Folder​

configs/ Folder​

custom/ Folder​

localization/ Folder​

Custom Translation Files​

How Custom Achievements Work​

Load Order​

Migration from v1.5.x​

Disabling Standard Configs​

Config Versioning​

Complete Configuration Example​

Configuration Sections​

General Settings​

Display Settings​

Title Position​

RPG Level Positions​

Notification Settings​

Tracking Settings​

Admin Settings​

Export Settings​

Group Prefixes (LuckPerms Integration)​