Skip to content

Config Structure

This guide explains how KyuubiSoft mod config files are organized, where to put your custom content, and how the update system works.

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 settings

This is the most important concept to understand:

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.

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 .example files (remove the .example extension).

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:

  1. A backup is created (e.g. config.json.backup-v4).
  2. New fields are added with their default values.
  3. The _config_version is bumped to the new version.
  4. Your existing settings are preserved.

This ensures you always have the latest config structure without losing your customizations.

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.

Before any auto-migration, the mod creates backup files:

config.json.backup-v4
quests.json.backup-v2

These backups let you recover your previous config if something goes wrong. They are never deleted automatically.

After editing any config file, reload them ingame:

/ksadmin reload

This 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 respawnall

or /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 .example files 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.