Chapters

Chapters group story quests into narrative arcs. They provide structure to the storyline, track player progress across multiple quests, and grant bonus rewards when all quests in a chapter are completed.

How Chapters Work

1. Each chapter defines an ordered list of quest IDs
2. Players progress through the quests in sequence (each quest has prerequisites pointing to the previous one)
3. When all quests in a chapter are completed, the chapter itself is marked complete
4. Chapter completion grants bonus rewards and sets a fact that can unlock the next chapter

chapters.json Structure

Chapters are defined in chapters.json in the quest config folder. Here is the structure:

{
  "_config_version": "2",
  "chapters": [
    {
      "id": "chapter_0_tutorial",
      "name": {
        "en-US": "Prologue: Awakening",
        "de-DE": "Prolog: Erwachen"
      },
      "description": {
        "en-US": "Learn the basics of survival in Orbis.",
        "de-DE": "Lerne die Grundlagen des Ueberlebens in Orbis."
      },
      "quests": [
        "tutorial_awakening",
        "tutorial_first_steps",
        "tutorial_workbench",
        "tutorial_safe_base"
      ],
      "order": 0,
      "category": "main",
      "rewards": [
        { "type": "currency", "currency": "quest_tokens", "amount": 50 },
        { "type": "title", "title_id": "newcomer" }
      ],
      "setsFact": "tutorial_completed"
    }
  ]
}

Field Reference

Field	Type	Required	Description
id	string	Yes	Unique chapter identifier
name	object	Yes	Localized chapter name (keyed by locale, e.g. en-US, de-DE)
description	object	No	Localized chapter description
quests	string[]	Yes	Ordered list of quest IDs belonging to this chapter
order	integer	Yes	Sort position (lower numbers appear first)
category	string	No	"main" (default), "side", or "event"
unlockCondition	string	No	Fact condition that must be true to unlock this chapter
rewards	object[]	No	Bonus rewards granted when the chapter is completed
setsFact	string	No	Fact key set to true when the chapter is completed
hidden	boolean	No	If true, chapter is hidden until unlocked (default: false)

Unlock Conditions

Chapters can require a fact condition to be met before they become available to the player. This creates a chain where completing one chapter unlocks the next:

{
  "id": "chapter_1_emerald",
  "unlockCondition": "tutorial_completed == true",
  "setsFact": "chapter_1_completed"
}

The unlockCondition uses the same fact condition syntax as quest prerequisites. If omitted, the chapter is always available (used for the first chapter).

tip

Each chapter's setsFact creates the key that the next chapter's unlockCondition checks. This forms an automatic chain.

Chapter Rewards

When a player completes all quests within a chapter, they receive the chapter's bonus rewards on top of the individual quest rewards. Supported reward types:

Type	Example	Description
currency	{ "type": "currency", "currency": "quest_tokens", "amount": 100 }	Quest Tokens
title	{ "type": "title", "title_id": "forest_protector" }	Unlocks a player title
lootbag	{ "type": "lootbag", "lootbag_id": "chapter_1_reward" }	Grants a loot bag
achievement	{ "type": "achievement", "achievement_id": "story_complete" }	Unlocks an achievement

note

Chapter completion rewards are granted in addition to rewards from individual quests. Players receive a notification when a chapter is completed.

Default Chapters

The server ships with six chapters covering the full storyline:

Order	Chapter	Quests	Region	Key Reward
0	Prologue: Awakening	10	Tutorial Area	"Newcomer" title + 50 tokens
1	The Emerald Wilds	5	Forest / Kweebec Village	"Forest Protector" title + 100 tokens
2	The Forgotten Temple	4	Temple Depths	"Temple Scholar" title + 100 tokens
3	The Howling Sands	4	Desert / Ruins	"Sand Survivor" title + 100 tokens
4	The Whisperfrost Frontiers	4	Frozen North / Mountains	"Frost Conqueror" title + 100 tokens
5	The Devastated Lands	4	Volcanic Wastelands	"Legend of Orbis" title + 200 tokens

The progression flows: Prologue -> Emerald Wilds -> Forgotten Temple -> Howling Sands -> Whisperfrost Frontiers -> Devastated Lands.

Chapter Progress Tracking

The system tracks chapter progress per player:

• Current chapter -- The first unlocked, non-completed main-story chapter
• Progress counter -- Number of completed quests vs. total quests in the chapter (e.g. 3/5)
• Completion flag -- A fact is stored when the chapter is finished, both as an internal flag (chapter_<id>_completed) and the custom setsFact value

Categories

Chapters support three categories:

Category	Description
main	Primary storyline chapters (shown in main progression)
side	Optional side-story chapters
event	Time-limited event chapters

The Quest Book's Story tab shows quests from main chapters by default.

Custom Chapters

Server owners can add custom chapters alongside the defaults. Place a JSON file in the custom/ subfolder of the quest config directory:

configs/kyuubisoft_questbook/
  chapters.json              # Default chapters
  custom/
    custom_chapters.json     # Your additional chapters

Custom chapters follow the same format as the default chapters.json. They are merged with the defaults and sorted by order. Use order values higher than the defaults (e.g. 100+) to place custom chapters after the built-in story.