# Story Quests

# Story Quests

Story quests form the main narrative progression of the server. Unlike daily and weekly quests, story quests are played in a fixed order, unlock sequentially through prerequisites, and are completed only once per player.

## How Story Quests Differ from Other Types

| Feature | Story Quests | Daily / Weekly | Side Quests |
|---------|-------------|----------------|-------------|
| Repeatable | No | Yes (rotating pool) | No |
| Prerequisites | Yes (quest chain + facts) | No | Optional |
| Auto-start | Optional | Assigned by system | No |
| NPC turn-in | Common | Rare | Optional |
| Sequential objectives | Optional | No | No |
| Sets facts on completion | Common | No | Optional |

## Auto-Start

A quest with `"auto_start": true` in its `options` block starts on its own as soon as its prerequisites are met: at login, after another quest was completed, or when a dialog sets a fact that unlocks it. Without prerequisites it starts at the first login. This is typically used for the very first tutorial quest:

```json
{
  "id": "tutorial_awakening",
  "type": "story",
  "options": { "auto_start": true }
}
```

:::note
`auto_start` only starts the quest. The player still completes the objectives and turns the quest in, unless the quest also has `auto_claim` (see below).
:::

## Prerequisites

Story quests use the `prerequisites` field to define what must be completed before the quest becomes available:

```json
"prerequisites": {
  "quests": ["tutorial_awakening"],
  "facts": ["chapter_1_completed == true"],
  "minLevel": 5
}
```

### Prerequisite Types

| Type | Field | Description |
|------|-------|-------------|
| **Quest completion** | `quests` | List of quest IDs that must be completed |
| **Achievements** | `achievements` | List of achievement IDs that must be unlocked (needs KyuubiSoft Achievements) |
| **Facts** | `facts` | List of fact conditions (see Facts System below) |
| **Level** | `minLevel` | Minimum player level (needs a leveling plugin) |
| **Skill level** | `mmoSkillRequired` + `minMmoSkillLevel` | Minimum level of a skill (needs the MMO skill plugin) |
| **Permission** | `conditions: [{ "type": "permission", "value": "<node>" }]` | The player must have this permission node (`"negated": true` = must not have it). Checked since 2.0.0 |

All conditions must be met for the quest to become available. The admin window's quest editor sets them under **Flow → Requirements**.

## The Facts System

Facts are key-value pairs stored per player that represent story state. They work like flags or variables that track what the player has done or experienced. The system is inspired by The Witcher 3's quest facts.

### How Facts Work

1. A quest or chapter defines `setsFact` -- a fact key that gets set when it is completed
2. Other quests or chapters use that fact in their `unlockCondition` or `prerequisites.facts`
3. The system checks the player's fact database to determine availability

### Fact Conditions

Facts support comparison operators:

| Operator | Example | Meaning |
|----------|---------|---------|
| `==` | `tutorial_completed == true` | Fact equals value |
| `!=` | `has_betrayed != true` | Fact does not equal value |
| `>=` | `dragons_slain >= 3` | Fact is greater than or equal to |
| `<=` | `reputation <= 50` | Fact is less than or equal to |
| `>` | `level > 10` | Fact is greater than |
| `<` | `corruption < 100` | Fact is less than |

### Where facts come from

- A quest with `setsFact` (and optional `setsFactValue`) sets the fact when it is completed.
- A chapter with `setsFact` sets it when the chapter is completed. Every completed chapter also stores `chapter_<id>_completed`.
- A quest trigger with `setsFact` sets it when the trigger fires.
- An NPC profile dialog can set one with the action `set_fact:name=value`.
- Core NPC dialogs can set one with the dialog action **Set fact**, and check one with the condition **fact**. While Quests is loaded, both use the Quests facts.
- Admins can set, change or delete facts in the Players tool of the [admin window](./admin-panel#players).

For example, a quest with `"setsFact": "gateway_discovered"` sets that fact to `true` upon completion. Other quests can then require `"facts": ["gateway_discovered == true"]` in their prerequisites. Auto-start quests that a new fact unlocks start right away.

## Sequential Objectives

Story quests can require objectives to be completed in order using `"options": { "sequential": true }`. When enabled:

- Only the current objective is active; subsequent objectives are locked
- Locked objectives display as `[Locked]` in the Quest Book and HUD
- Each objective unlocks only after all previous objectives are complete

```json
{
  "id": "tutorial_workbench",
  "type": "story",
  "options": { "sequential": true },
  "objectives": [
    { "id": "obj_1", "type": "blocks_chopped", "target": "any", "count": 8 },
    { "id": "obj_2", "type": "items_crafted", "target": "Bench_WorkBench", "count": 1 },
    { "id": "obj_3", "type": "blocks_placed", "target": "Bench_WorkBench", "count": 1 }
  ]
}
```

In this example, the player must chop 8 blocks before they can craft the workbench, and must craft it before they can place it.

## NPC Turn-in

Many story quests require the player to visit a specific NPC to complete the quest, rather than claiming rewards through the Quest Book. When a quest has an NPC turn-in:

- The Questbook shows **Claim at** *NPC* instead of **Claim reward**, and the detail panel says where to go
- The HUD tracker card shows "Turn in: NPC · distance" when all objectives are complete
- Talking to the NPC opens the completion dialog or the "ready to claim" strip of the quest giver window

## Auto-Claim

A quest with `"auto_claim": true` in its `options` completes and pays its rewards as soon as the last objective is done. No claim and no NPC visit is needed:

```json
"options": {
  "auto_claim": true
}
```

This is useful for exploration quests like discovering a zone, where an extra claim step would break immersion. Chapters with `autoChain` start the next quest of the chain right after (see [Chapters](./chapters)).

## Story Quest Visibility

Story quests appear in the **Story** tab of the Questbook. It shows a chapter map with finished, current and locked chapters; locked chapters cannot be selected. For the selected chapter, the tab lists its quests in chapter order with their state (new, active, ready, completed or locked with the reason).

Quests with the `hidden` option set to `true` are only listed once the player has started or completed them. This allows for secret or surprise quests.

## Default Story Quest Chain

The server ships with a complete story spanning from the tutorial through five biomes. See [Chapters](./chapters) for how these quests are organized into chapters.