# Custom Content

# Custom Quest Content

The quest system uses a **Base+Custom** architecture that separates default content from your modifications. This means your custom quests, chapters and pool entries survive mod updates without any manual merging.

## How It Works

When the server starts, the quest system loads content in two phases:

1. **Base files** from `configs/` -- these are maintained by the mod and get updated automatically
2. **Custom files** from `custom/` -- these are yours and are **never overwritten**

The merge process combines both sets. If a custom quest has the same ID as a base quest, the custom version wins.

:::tip Admin window
The [admin window](./admin-panel) writes every change you save into these `custom_*.json` files, and only what differs from the shipped content. You can edit quests, chapters and pools there without touching any file, and hand-written custom files keep working next to it.
:::

```
mods/kyuubisoft_questbook/
  configs/              <-- Base content (auto-updated by the mod)
    quests.json
    story_quests.json
    chapters.json
    daily_pool.json
    weekly_pool.json
  custom/               <-- Your content (never touched by updates)
    custom_quests.json
    custom_story_quests.json
    custom_chapters.json
    custom_daily_pool.json
    custom_weekly_pool.json
    my_event_pack.json  <-- Additional files auto-loaded
```

:::tip
Custom content must be enabled in `config.json` (it is by default):
```json
{
  "useCustomContent": true
}
```
:::

## Custom File Format

Every custom file follows the same pattern with three fields:

```json title="custom/custom_quests.json"
{
  "_info": "Admin-created/modified quests. This file is NOT overwritten on mod updates.",
  "disabled_base_ids": ["daily_mine_stone", "daily_harvest"],
  "quests": [
    {
      "id": "my_custom_quest",
      "type": "side",
      "category": "exploration",
      "name": { "en-US": "Lost Temple", "de-DE": "Verlorener Tempel" },
      "objectives": [
        { "id": "find_temple", "type": "zone_discovered", "targets": ["Forgotten_Temple"], "count": 1 }
      ],
      "rewards": [
        { "type": "quest_tokens", "amount": 5 }
      ]
    }
  ]
}
```

### `disabled_base_ids`

This is the key mechanism for hiding default quests you do not want on your server. Instead of deleting them from the base file (which would get restored on the next update), you list their IDs here:

```json
{
  "disabled_base_ids": [
    "daily_mine_stone",
    "daily_kill_mobs",
    "weekly_master_miner"
  ],
  "quests": []
}
```

The listed IDs are removed from the quest list during the merge phase. This works for all content types: quests, story quests, chapters, and pool entries.

## Auto-Folder Loading

Any `.json` file placed in the `custom/` folder that does **not** start with `custom_` is automatically loaded as additional content. This is how [Quest Packs](./quest-packs) work on the server side.

The system:
- Scans `custom/` for `.json` files
- Skips files starting with `custom_` (already handled by the standard merge)
- Skips `.example` files
- Loads quests and chapters from each file
- Processes files alphabetically (last file wins on duplicate IDs)

:::caution
Additional files do **not** support `disabled_base_ids`. Only the standard `custom_*.json` files do. If you need to disable base content, use `custom_quests.json`.
:::

## Example Files

On first start, the mod extracts `.example` template files into `custom/` for quests, story quests, chapters, daily pool, weekly pool and the token shop. To use one, rename it by removing the `.example` extension and edit its contents.

## Practical Workflow

**Adding a quest** -- Rename `custom_quests.json.example` to `custom_quests.json`, add your quest to the `"quests"` array, then run `/ksquestadmin reload`.

**Disabling a default quest** -- Open `custom/custom_quests.json`, add the quest ID to `"disabled_base_ids"`, then reload.

**Adding to the daily pool** -- Create `custom/custom_daily_pool.json` with entries like `{ "quest_id": "my_daily", "weight": 1 }` in the `"pool"` array.

## Update Safety

When the mod updates, this is what happens:

| Location | Behavior |
|----------|----------|
| `configs/*.json` | Backed up and replaced if version is newer |
| `custom/custom_*.json` | **Never touched** by updates (the admin window writes your own changes here) |
| `custom/*.json` (additional) | **Never touched** |
| `config.json` | Only created if missing, never overwritten |
| `configs/quest_token_shop.json` | Replaced only when the shipped file carries a newer version (backup `quest_token_shop.json.backup-v<N>`) |

Backups of replaced base files are saved as `filename.json.backup-v{N}` so you can always compare changes.

:::info
The version-aware extraction uses the `_config_version` field in base files. If the version in your `configs/` folder is lower than the version shipped with the mod, the old file is backed up and replaced.
:::

## Admin Commands

| Command | Description |
|---------|-------------|
| `/ksquestadmin reload` | Reloads all config files (base + custom) |
| `/ksquestadmin export all` | Full backup export of all quest data to `exports/` |
| `/ksquestadmin export quest <id>` | Export a single quest as JSON |
| `/ksquestadmin import <file> [overwrite]` | Import a file from `exports/` |
| `/ksquestadmin debug` | Shows your active quests, progress, and facts |

Exports go to `exports/` only. Old admin panel exports that were left in `custom/` (`export_quests_…`, `export_chapters_…`, `export_stats_…`) are moved once to `exports/legacy-panel/`, because they overrode later changes on every restart. Quests that only existed in those files are named in one warning line in the log.