Configuration
The plugin uses config.json in mods/kyuubisoft_achievements/ for all settings. Most options can also be changed in the Admin Window, which writes the same file.
Folder Structure
Section titled “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 actionsRoot Folder
Section titled “Root Folder”- config.json - Main plugin configuration (language, display settings, notifications, etc.)
- README.md - Quick reference documentation
configs/ Folder
Section titled “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
Section titled “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
Section titled “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
Section titled “Custom Translation Files”Custom translation files allow you to override or add translations without losing them during updates:
- Copy
custom_en-US.json.exampletocustom_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
Section titled “How Custom Achievements Work”Adding New Achievements:
- Copy the
.exampletemplate to remove the.exampleextension - Add your achievements to the
achievementsarray - Reload with
/ksadmin reload(KyuubiSoft Core reloads every KS mod), or create the achievement in the Admin Window 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
{ "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
Section titled “Load Order”Achievements are loaded in this order:
configs/achievements.json(ifloadDefaultAchievementsis true)custom/custom_achievements.json(merges/overrides)configs/mmo_achievements.json(ifloadMmoAchievementsis true)custom/custom_mmo_achievements.json(merges/overrides)configs/rpg_leveling_achievements.json(ifloadRpgLevelingAchievementsis 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)
The result is registered in KyuubiSoft Core’s lootbag registry (Core’s own bags with the same id win). See Lootbags.
Localization is loaded in this order:
localization/{language}.json(e.g.,en-US.json)localization/custom_{language}.json(merges/overrides)
Disabling Standard Configs
Section titled “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}Config Versioning
Section titled “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. 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
Section titled “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", "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
Section titled “Configuration Sections”General Settings
Section titled “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
Section titled “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" |
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
Section titled “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 |
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
Section titled “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
Section titled “Notification Settings”Controls achievement unlock notifications.
"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
Section titled “Points”Achievement points per difficulty. The defaults are the values before 3.0.0. Points are a shop currency, see Achievement Points.
| Option | Default |
|---|---|
points.easy | 10 |
points.normal | 10 |
points.hard | 25 |
points.epic | 50 |
points.legendary | 10 |
Tracking Settings
Section titled “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 |
Creative mode is ignored for single triggers, “total” achievements and statistics.
Admin Settings
Section titled “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 | /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
Section titled “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)
Section titled “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
Section titled “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.
"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
Section titled “Tracker HUD Settings”Controls the on-screen achievement tracker HUD. See Tracker HUD for detailed documentation.
"trackerHud": { "enabled": true}| Option | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Enable/disable the tracker HUD globally |
The tracker has a fixed place on the screen. The older key trackerHud.position is ignored.
Categories and disabled achievements (3.1.0)
Section titled “Categories and disabled achievements (3.1.0)”These fields are written by the Admin Window. 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.