# Chapters

# 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. The **Chapters** tab of the [admin window](./admin-panel#chapters) edits everything on this page in game.

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

```json
{
  "_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) |
| `icon` | string | No | Icon for the UI |
| `category` | string | No | `"main"` (default), `"side"`, or `"event"` |
| `unlockCondition` | string | No | Fact condition that must be true to unlock this chapter |
| `requiredChapters` | string[] | No | Chapters that must be completed first |
| `rewards` | object[] | No | Bonus rewards granted when the chapter is completed |
| `setsFact` | string | No | Fact key set when the chapter is completed |
| `setsFactValue` | any | No | Value of that fact (default: `true`) |
| `hidden` | boolean | No | If `true`, chapter is hidden until unlocked (default: `false`) |
| `autoChain` | boolean | No | If `true`, completing a quest of the chapter starts the next one right away (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:

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

The `unlockCondition` uses the same [fact condition syntax](./story-quests#fact-conditions) 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.
:::

In the admin window, unlock rules have three modes with a plain-text summary: **open from the start**, **after another chapter** and **by a fact**. Other conditions show as "custom condition". The quick fixes **Match chain** and **Match order** line up the chain and the order of the affected chapters only.

## Auto-Start (autoChain)

With `autoChain: true` ("Auto-start" in the admin window), the next quest of the chapter starts right after the previous one is completed. The quest givers' offer texts are skipped then. Off (the default) means the quest giver offers the next quest.

## 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. Chapter rewards use the same reward types and the same reward builder as quests (see [Rewards](./rewards)), but no tier factor. Common examples:

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

Command rewards that run as the console follow the [console rule](./permissions#the-console-rule) here too.

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

```
mods/kyuubisoft_questbook/
  configs/
    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.