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.

configs/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):

{
  "useCustomContent": true
}

Custom File Format

Every custom file follows the same pattern with three fields:

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_entered", "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:

{
  "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 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
custom/*.json (additional)	Never touched
config.json	Only created if missing, never overwritten

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
/ksquestadmin export quest <id>	Export a single quest as JSON
/ksquestadmin debug	Shows your active quests, progress, and facts