# Config Structure

# 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

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
```

## Base vs Custom

This is the most important concept to understand:

### 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
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).

:::tip
Always put your content in `custom/` files. This is the only way to ensure your work survives mod updates. The in-game editors of the KS mods (for example the shop editor, NPC management and the Quests and Achievements admin windows) save to the right files for you.
:::

## Config Version and Auto-Migration

Shipped config files carry a version field (`_config_version` or `configVersion`, depending on the file):

```json
{
  "_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:

```json
{
  "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 (it needs `ks.admin`). For NPC changes that need a fresh spawn, also run:

```
/kscitizen respawnall
```

or `/kscitizen respawn <id>` for a single NPC.

:::note[Broken files are kept]
If a Core NPC file or lootbag file cannot be read, Core no longer overwrites it: the file is kept, a `.corrupt-<time>` copy is made, and the last working state is used until you fix the file and reload.
:::

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