Configuration

Configuration

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

Folder Structure

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

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

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

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

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)

Localization is loaded in this order:

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

Migration from v1.5.x

If upgrading from v1.5.x:

1. The plugin will automatically create the new folder structure
2. Existing achievements.json in the root folder will be migrated to configs/
3. 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:

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.

---

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

  "item": {
    "enabled": true,
    "itemId": "AchievementBook",
    "giveOnFirstJoin": true,
    "giveOnEveryJoin": false,
    "hotbarSlot": 7,
    "giveDelaySeconds": 3
  },

  "trackerHud": {
    "enabled": true,
    "position": "right"
  },

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

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

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

"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

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

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

:::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 gallery when used.

"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

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 for detailed documentation.

"trackerHud": {
  "enabled": true,
  "position": "right"
}

Option	Type	Default	Description
enabled	boolean	true	Enable/disable the tracker HUD globally
position	string	"right"	Default side of the screen: "left" or "right"

Individual players can customize their HUD position through the in-game settings page. The position setting here is the server-wide default.