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

All config files live in your server's configs/ directory, organized by mod:

configs/
├── kyuubisoft_core/
│   ├── config.json              — Core settings
│   ├── citizens.json            — Base NPC definitions
│   ├── 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
│   │   ├── de-DE.json
│   │   ├── custom_en-US.json.example
│   │   └── custom_de-DE.json.example
│   ├── npc-roles/               — NPC behavior roles
│   └── shops/                   — Shop configurations
│
├── 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
│   │   ├── de-DE.json
│   │   └── fr-FR.json
│   └── 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
│   │   └── de-DE.json
│   └── quest_npc_profiles/      — NPC-to-quest link configs
│
├── kyuubisoft_infohub/
│   └── ...                      — Info Hub sections and entries
│
├── kyuubisoft_seasonpass/
│   └── ...                      — Season pass tiers and rewards
│
├── kyuubisoft_chatplus/
│   └── ...                      — Chat channels, mail settings
│
└── kyuubisoft_weapon-mastery/
    └── ...                      — Weapon mastery settings

Base vs Custom

This is the most important concept to understand:

Base Configs

Files in the main configs/ folders (e.g. configs/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

Files in the custom/ subfolders (e.g. configs/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).

tip

Always put your content in custom/ files. This is the only way to ensure your work survives mod updates.

Config Version and Auto-Migration

Each config file has a _config_version field:

{
  "_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.

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

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.

Reloading Configs

After editing any config file, reload them ingame:

/ksadmin reload

This reloads all config files from disk without restarting the server. For citizen changes, also run:

/kscitizen respawn

Tips

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