Config Structure
This guide explains how KyuubiSoft mod config files are organized, where to put your custom content, and how the update system works.
Folder Structure
Section titled “Folder Structure”Every KyuubiSoft mod keeps its files in its own data folder inside the server’s mods/ directory (next to the mod JARs). The folder names below are the real ones:
mods/├── kslang/│ └── prefs.json — Language choices shared by all KS mods│├── kyuubisoft_core/│ ├── config.json — Core settings│ ├── citizens.json — Base NPC definitions│ ├── citizen-backups/ — Last 10 timestamped NPC file backups│ ├── skin-cache.json — NPC skin cache│ ├── configs/│ │ └── lootbags.json — Lootbag definitions│ ├── custom/│ │ ├── custom_citizens.json.example│ │ └── custom_lootbags.json.example│ ├── dialogs/ — NPC dialog trees│ ├── localization/│ │ ├── en-US.json … tr-TR.json — 9 languages│ │ └── custom_<lang>.json — Your own texts (create it)│ ├── npc-roles/ — NPC behavior roles│ ├── shops/ — NPC shop configurations│ └── shop_data/ — Per-player shop counters│├── kyuubisoft_achievements/│ ├── config.json — Achievement settings│ ├── configs/│ │ ├── achievements.json — Achievement definitions│ │ ├── lootbags.json — Achievement lootbags│ │ ├── mmo_achievements.json│ │ └── rpg_leveling_achievements.json│ ├── custom/│ │ ├── custom_achievements.json.example│ │ ├── custom_lootbags.json.example│ │ ├── custom_mmo_achievements.json.example│ │ └── custom_rpg_leveling_achievements.json.example│ ├── localization/│ │ └── en-US.json … tr-TR.json — 9 languages│ ├── admin/ — Admin window data (player actions)│ └── stats/│ ├── global_stats.json│ └── leaderboards.json│├── kyuubisoft_questbook/│ ├── config.json — Quest book settings│ ├── configs/│ │ ├── quests.json — Base quest definitions│ │ ├── story_quests.json — Story quest chain│ │ ├── chapters.json — Quest chapters│ │ ├── daily_pool.json — Daily quest rotation│ │ ├── weekly_pool.json — Weekly quest rotation│ │ └── quest_token_shop.json│ ├── custom/│ │ ├── custom_quests.json.example│ │ ├── custom_story_quests.json.example│ │ ├── custom_chapters.json.example│ │ ├── custom_daily_pool.json.example│ │ ├── custom_weekly_pool.json.example│ │ └── custom_quest_token_shop.json.example│ ├── localization/│ │ └── en-US.json … tr-TR.json — 9 languages│ ├── admin/ — Admin window data (player actions)│ └── quest_npc_profiles/ — NPC-to-quest link configs│├── kyuubisoft_infohub/│ └── ... — Info Hub pages, rules, FAQ, team, news│├── kyuubisoft_seasonpass/│ └── ... — Season pass tiers and rewards│├── kyuubisoft_chatplus/│ └── ... — Chat channels, mail settings│└── kyuubisoft_weapon-mastery/ └── ... — Weapon mastery settingsBase vs Custom
Section titled “Base vs Custom”This is the most important concept to understand:
Base Configs
Section titled “Base Configs”Files in the mod’s data folder and its configs/ subfolder (e.g. mods/kyuubisoft_questbook/configs/quests.json). These are the default content shipped with the mod.
- May be overwritten when the mod updates to a new version.
- You can read them for reference, but do not rely on manual edits persisting.
Custom Configs
Section titled “Custom Configs”Files in the custom/ subfolders (e.g. mods/kyuubisoft_questbook/custom/custom_quests.json). These are your additions.
- Never overwritten by mod updates.
- Entries from custom files are merged with base entries at load time.
- Start by renaming the
.examplefiles (remove the.exampleextension).
Config Version and Auto-Migration
Section titled “Config Version and Auto-Migration”Shipped config files carry a version field (_config_version or configVersion, depending on the file):
{ "_config_version": 5, "settings": { ... }}When the mod updates and the built-in version is higher than your file’s version:
- A backup is created (e.g.
config.json.backup-v4). - New fields are added with their default values.
- The
_config_versionis bumped to the new version. - Your existing settings are preserved.
This ensures you always have the latest config structure without losing your customizations.
Disabling Base Entries
Section titled “Disabling Base Entries”If you want to remove a base quest, achievement, or citizen without editing the base file, use the disabled_base_ids pattern:
{ "disabled_base_ids": [ "starter_quest_1", "tutorial_achievement" ]}Add this to your custom config file. Any IDs listed here will be skipped when loading base entries, effectively removing them from the game.
Backup System
Section titled “Backup System”Before any auto-migration, the mod creates backup files:
config.json.backup-v4quests.json.backup-v2These backups let you recover your previous config if something goes wrong. They are never deleted automatically.
Reloading Configs
Section titled “Reloading Configs”After editing any config file, reload them ingame:
/ksadmin reloadThis reloads all config files from disk without restarting the server (it needs ks.admin). For NPC changes that need a fresh spawn, also run:
/kscitizen respawnallor /kscitizen respawn <id> for a single NPC.
- JSON validation — Always validate your JSON before reloading. A single missing comma can prevent the entire file from loading. Use a JSON validator or your editor’s built-in checker.
- Start from examples — Rename the
.examplefiles to get started with the correct structure. - One change at a time — When troubleshooting, make one change, reload, and test before making more changes.
- Check server logs — If a config fails to load, the server console will show the error with the file path and line number.