Skip to content

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.

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
  • config.json - Main plugin configuration (language, display settings, notifications, etc.)
  • README.md - Quick reference documentation

Contains standard achievement definitions that ship with the plugin. These files should NOT be modified as they may be overwritten during plugin updates.

FileDescription
achievements.jsonCore achievements (combat, progression, exploration, social)
mmo_achievements.jsonAchievements for MMO Skill Tree integration (skill levels)
rpg_leveling_achievements.jsonAchievements for RPG Leveling integration (character level, XP, mob kills)
lootbags.json20 lootbag rewards with item pools and weighted chances

Contains custom achievement definitions created by server administrators. These files are NEVER overwritten by plugin updates.

FileDescription
custom_achievements.jsonGeneral custom achievements
custom_mmo_achievements.jsonCustom MMO skill achievements
custom_rpg_leveling_achievements.jsonCustom RPG leveling achievements
custom_lootbags.jsonCustom lootbag definitions
*.exampleTemplate files showing the correct format

Contains language files for the plugin UI and messages. Standard files may be updated during plugin updates, but custom files are NEVER overwritten.

FileDescription
<lang>.jsonShipped translations for the 9 languages (replaced when a new version ships newer texts)
custom_*.jsonCustom translation overrides (never overwritten)
custom_*.json.exampleTemplates for custom translations

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

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

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.

Localization is loaded in this order:

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

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
}

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.


{
"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
}
}
}
OptionTypeDefaultDescription
languagestring"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
loadDefaultAchievementsbooleantrueLoad configs/achievements.json. Set to false for fully custom setups
loadMmoAchievementsbooleantrueLoad configs/mmo_achievements.json (MMO Skill Tree achievements)
loadRpgLevelingAchievementsbooleantrueLoad 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+). :::

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"
}
OptionTypeDefaultDescription
displayModestring"both"Where to show titles: "nametag", "chat", or "both"
titlePositionstring"prefix"Title position (see table below)
nametagFormatstring"\{title\} \{name\}"Format for nametag display
chatFormatstring"\{title\} \{name\}: \{message\}"Format for chat messages
titleColorstring"#FFD700"Color for titles in chat (hex). Chat only
showRpgLevelbooleanfalseShow player level from RPGLeveling plugin
rpgLevelFormatstring"Lv.\{level\}"Format for level display. \{level\} is replaced with the actual level
rpgLevelColorstring"#55FFFF"Color for level in chat (hex). Chat only
rpgLevelPositionstring"after_name"Level position: "before_name", "after_name", or "after_title"
showRaritybooleantrueShow the share of players who have an achievement in the book
showServerFirstbooleantrueShow 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. :::

Config ValueNametag ResultChat 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)
PositionNametag ExampleChat 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. :::

Controls achievement unlock notifications.

"notifications": {
"enabled": true,
"displayMode": "banner",
"displayDurationMs": 5000,
"showRewardsInBanner": true,
"broadcastToChat": false,
"broadcastFormat": "{player} unlocked: {achievement}",
"pendingRewardHint": true
}
OptionTypeDefaultDescription
enabledbooleantrueEnable/disable notifications
displayModestring"banner""banner" = one HUD toast, "chat" = one chat line, "both". New installs use banner; existing configs keep their value
displayDurationMsnumber5000Toast duration in milliseconds
showRewardsInBannerbooleantrueShow the reward hint in the toast or chat line
broadcastToChatbooleanfalseAnnounce unlocks to all players (each in their own language; colour codes in the format are stripped)
broadcastFormatstring"\{player\} unlocked: \{achievement\}"Broadcast message format
pendingRewardHintbooleantrueOnce per session after join: tell players that rewards are waiting

Achievement points per difficulty. The defaults are the values before 3.0.0. Points are a shop currency, see Achievement Points.

OptionDefault
points.easy10
points.normal10
points.hard25
points.epic50
points.legendary10

Controls which achievement categories are tracked.

"tracking": {
"saveIntervalSeconds": 300,
"ignoreCreativeMode": true,
"enableExploration": true,
"enableCombat": true,
"enableProgression": true,
"enableSocial": true
}
OptionTypeDefaultDescription
saveIntervalSecondsnumber300Auto-save interval (5 minutes default)
ignoreCreativeModebooleantrueIgnore achievement progress when player is in creative mode
enableExplorationbooleantrueTrack exploration achievements
enableCombatbooleantrueTrack combat achievements
enableProgressionbooleantrueTrack progression achievements
enableSocialbooleantrueTrack social achievements

Creative mode is ignored for single triggers, “total” achievements and statistics.

Controls administrative behavior.

"admin": {
"cascadeRevoke": false,
"cascadeRevokeWarning": true,
"bypassPrerequisites": false
}
OptionTypeDefaultDescription
cascadeRevokebooleanfalseRevoke dependent achievements when parent is revoked
cascadeRevokeWarningbooleantrue/acadmin revoke names the dependent achievements first (online players)
bypassPrerequisitesbooleanfalseNo effect: admin grants always skip prerequisites. Kept in the file, not shown in the admin window

Controls statistics export for external tools.

"export": {
"enabled": true,
"intervalSeconds": 300,
"exportGlobalStats": true,
"exportLeaderboards": true,
"exportRecentUnlocks": true,
"leaderboardSize": 100,
"recentUnlocksSize": 50,
"includePlayerTotals": true
}
OptionTypeDefaultDescription
enabledbooleantrueEnable statistics export
intervalSecondsnumber300Export frequency
exportGlobalStatsbooleantrueInclude global statistics
exportLeaderboardsbooleantrueInclude player leaderboards
exportRecentUnlocksbooleantrueInclude recent unlock history
leaderboardSizenumber100Number of top players
recentUnlocksSizenumber50Number of recent unlocks
includePlayerTotalsbooleantrueInclude per-player totals

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
}
}
OptionTypeDescription
prefixstringPrefix text with MiniMessage formatting
colorstringHex color code for the prefix (e.g., "#FF5555")
prioritynumberHigher 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. :::

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
}
OptionTypeDefaultDescription
enabledbooleantrueEnable/disable the Achievement Book item
itemIdstring"AchievementBook"Item ID for the achievement book
giveOnFirstJoinbooleantrueGive the book to players on their first join
giveOnEveryJoinbooleanfalseGive the book to players on every join
hotbarSlotnumber7Hotbar slot where the book is placed (0-8)
giveDelaySecondsnumber3Delay 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.

Controls the on-screen achievement tracker HUD. See Tracker HUD for detailed documentation.

"trackerHud": {
"enabled": true
}
OptionTypeDefaultDescription
enabledbooleantrueEnable/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.

OptionTypeDefaultDescription
categoryOrderarray[]Order of the categories in the book; empty = built-in order
categoryIconsobject{}Item icon per category id
disabledAchievementsarray[]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.