# Quest Types

# Quest Types

The Quest System supports five quest types, each with different progression mechanics, reset behavior and assignment rules.

## Overview

| Type | Reset | Assignment | Turn-in | Pool-based |
|------|-------|-----------|---------|------------|
| **Daily** | Every day at configured time | Random from daily pool | QuestBook | Yes |
| **Weekly** | Every week on configured day | Random from weekly pool | QuestBook | Yes |
| **Story** | Never (permanent) | Auto-started or prerequisite-gated | Quest Book / NPC | No |
| **Side** | Never (permanent) | Available after prerequisites met | Quest Book / NPC | No |
| **Hub** | Never (permanent) | Player chooses from available sub-quests | Quest Book | No |

## Daily Quests

Daily quests are short, repeatable tasks assigned fresh each day. Players receive a set number of daily quests drawn randomly from the daily quest pool.

**Key behavior:**
- Reset at the time configured in `dailyResetTime` (default: 04:00)
- The number of quests assigned is controlled by `dailyQuestCount` (default: 3)
- Quests are turned in in the **Questbook** -- open it with `/ksquest` and press **Claim reward**
- Support the **tier system**: each quest can have Common, Rare, Epic or Legendary variants with increasing difficulty and rewards
- A finished daily counts as done until the next reset. When the same quest is drawn again later, it can be done again
- Can be **rerolled** if the reroll system is enabled

**Example daily quest definition:**

```json
{
  "id": "daily_mine_stone",
  "type": "daily",
  "category": "gathering",
  "difficulty": "easy",
  "icon_item": "Tool_Pickaxe_Iron",
  "name": {
    "en": "Stone Breaker",
    "de": "Steinbrecher"
  },
  "description": {
    "en": "Daily blocks mined challenge.",
    "de": "Taegliche blocks mined Herausforderung."
  },
  "objectives": [
    {
      "id": "obj_1",
      "type": "blocks_mined",
      "target": "Rock_Stone*",
      "count": 50,
      "description": {
        "en": "Mine Rock Stone (0/50)",
        "de": "Baue ab Rock Stone (0/50)"
      }
    }
  ],
  "rewards": [
    { "type": "quest_tokens", "amount": 2 },
    { "type": "item", "item_id": "Ore_Iron", "amount": 5 }
  ],
  "options": {
    "repeatable": true,
    "tier": "common",
    "weight": 50,
    "pool": "mining"
  }
}
```

:::tip Tier Variants
To create difficulty variants, define multiple quests with the same base concept but a different `difficulty` and objective counts. For example: `daily_mine_stone` (easy, 50 blocks), `daily_mine_stone_rare` (medium, 75 blocks), `daily_mine_stone_epic` (hard, 100 blocks). The `difficulty` decides the tier and its reward factor; how often each variant is drawn comes from its weight in the pool file. `tier`, `weight` and `pool` inside `options` (as in the shipped files) are not used for drawing or rewards.
:::

## Weekly Quests

Weekly quests are larger challenges that reset once per week. They typically have multiple objectives and offer better rewards than daily quests.

**Key behavior:**
- Reset on the day configured in `weeklyResetDay` (default: MONDAY) at the `dailyResetTime`
- The number assigned is controlled by `weeklyQuestCount` (default: 5)
- Quests are turned in in the **Questbook** with **Claim reward**
- Also support the tier system with weighted variants
- Players have a full week to complete them

**Example weekly quest definition:**

```json
{
  "id": "weekly_master_miner",
  "type": "weekly",
  "category": "gathering",
  "icon_item": "Tool_Pickaxe_Iron",
  "name": {
    "en": "Mine Master",
    "de": "Bergbaumeister"
  },
  "description": {
    "en": "Complete all objectives in this weekly challenge.",
    "de": "Schliesse alle Ziele dieser woechentlichen Herausforderung ab."
  },
  "objectives": [
    {
      "id": "obj_1",
      "type": "blocks_mined",
      "target": "any",
      "count": 300,
      "description": { "en": "Mine (0/300)", "de": "Baue ab (0/300)" }
    },
    {
      "id": "obj_2",
      "type": "blocks_mined",
      "target": "Ore_*",
      "count": 30,
      "description": { "en": "Mine Ore (0/30)", "de": "Baue ab Ore (0/30)" }
    }
  ],
  "rewards": [
    { "type": "quest_tokens", "amount": 8 },
    { "type": "lootbag", "lootbag_id": "ore_bundle_common" }
  ],
  "options": {
    "repeatable": true,
    "tier": "common",
    "weight": 50,
    "pool": "mastery"
  }
}
```

## Story Quests

Story quests form the main narrative progression. They are permanent (never reset), follow a linear chain through prerequisites and guide players through the game world.

**Key behavior:**
- Defined in `story_quests.json` (separate from other quest types)
- The first story quest can **auto-start** for new players via `"auto_start": true`
- Subsequent quests unlock through **prerequisites** (completing prior quests)
- Objectives can be marked **sequential** (must be completed in order)
- Support **NPC interactions** as objectives (talk to a specific NPC)
- Organized into **chapters** for the quest book UI
- Never expire or reset

**Example story quest definition:**

```json
{
  "id": "tutorial_first_steps",
  "type": "story",
  "category": "main",
  "icon_item": "Tool_Hatchet_Crude",
  "name": {
    "en": "First Steps",
    "de": "Erste Schritte"
  },
  "description": {
    "en": "Craft your first crude tools from gathered materials.",
    "de": "Crafte deine ersten Werkzeuge aus gesammelten Materialien."
  },
  "objectives": [
    {
      "id": "obj_1",
      "type": "items_crafted",
      "target": "Tool_Hatchet_Crude",
      "count": 1,
      "description": { "en": "Craft Tool Hatchet Crude (0/1)", "de": "Crafte Tool Hatchet Crude (0/1)" }
    },
    {
      "id": "obj_2",
      "type": "items_crafted",
      "target": "Tool_Pickaxe_Crude",
      "count": 1,
      "description": { "en": "Craft Tool Pickaxe Crude (0/1)", "de": "Crafte Tool Pickaxe Crude (0/1)" }
    }
  ],
  "rewards": [
    { "type": "quest_tokens", "amount": 2 },
    { "type": "item", "item_id": "Wood_Sticks", "amount": 4 }
  ],
  "prerequisites": {
    "quests": ["tutorial_awakening"]
  }
}
```

:::info Story Quest Options
- `"auto_start": true` -- Quest starts automatically when the player first joins
- `"sequential": true` -- Objectives must be completed in the order listed
:::

## Side Quests

Side quests are optional, permanent quests that provide additional content and rewards. They are typically tied to specific NPCs or regions and unlock after certain story milestones.

**Key behavior:**
- Defined in `quests.json` alongside daily/weekly quests
- Unlocked through **prerequisites** (usually a story quest)
- Completed once per player, unless they are marked repeatable (see [Quest Options](#quest-options))
- Shown in the **Side quests** tab of the Questbook, together with every other quest that is not daily, weekly or story
- Often involve **NPC interactions** (`interact_npc` objective type)
- Can have multiple objective types mixed together (combat, gathering, crafting)

**Example side quest definition:**

```json
{
  "id": "side_riven_hunt",
  "type": "side",
  "category": "combat",
  "icon_item": "Weapon_Sword_Iron",
  "name": {
    "en": "Big Game Hunt",
    "de": "Grosswildjagd"
  },
  "description": {
    "en": "Hunt goblins and Fen Stalkers for Riven.",
    "de": "Jage Goblins und Fen Stalker fuer Riven."
  },
  "objectives": [
    { "id": "obj_1", "type": "kills", "target": "Goblin_*", "count": 10 },
    { "id": "obj_2", "type": "kills", "target": "Fen_Stalker", "count": 3 }
  ],
  "rewards": [
    { "type": "quest_tokens", "amount": 10 },
    { "type": "lootbag", "lootbag_id": "hunter_reward" }
  ],
  "prerequisites": {
    "quests": ["story_trork_camp"]
  }
}
```

## Hub Quests

Hub quests group multiple sub-quests together and track how many the player completes. They are used for "choose your own path" scenarios where players pick from a selection of available quests.

:::caution
Quests 2.1 does not count the `complete_hub_quests` objective, so a hub quest cannot be finished at the moment. The admin window's check marks it as an objective type that never counts. No shipped quest uses the hub type.
:::

**Key behavior:**
- The hub quest itself contains a `complete_hub_quests` objective that auto-increments when sub-quests complete
- Players can choose which sub-quests to tackle from the `available_quests` list
- Only `required_to_progress` sub-quests need to be completed (not all of them)
- Displayed in the **Side quests** tab of the Questbook
- Can have optional `hubUI` config for custom title, subtitle and layout

**Example hub quest definition:**

```json
{
  "id": "mining_hub",
  "type": "hub",
  "category": "gathering",
  "icon_item": "Tool_Pickaxe_Iron",
  "name": {
    "en": "Mining Mastery",
    "de": "Bergbau-Meisterschaft"
  },
  "description": {
    "en": "Complete mining challenges to prove your skill.",
    "de": "Schliesse Bergbau-Herausforderungen ab."
  },
  "objectives": [
    { "id": "complete", "type": "complete_hub_quests", "target": "mining_hub", "count": 3 }
  ],
  "available_quests": ["mine_stone", "mine_ore", "mine_gems", "mine_crystal"],
  "required_to_progress": 3,
  "rewards": [
    { "type": "quest_tokens", "amount": 15 }
  ]
}
```

### Hub Quest Fields

| Field | Required | Description |
|-------|----------|-------------|
| `available_quests` | Yes | Array of sub-quest IDs the player can choose from |
| `required_to_progress` | No | How many sub-quests must be completed (default: 1) |
| `hubUI` | No | Optional UI customization (see below) |

### Hub UI Config

```json
"hubUI": {
  "title": "Mining Challenges",
  "subtitle": "Complete 3 of 4 challenges",
  "layout": "grid"
}
```

| Field | Default | Description |
|-------|---------|-------------|
| `title` | Quest name | Custom title for the hub selection UI |
| `subtitle` | — | Subtitle text |
| `layout` | `"grid"` | Layout mode: `"grid"` or `"list"` |

## Objective Types

All quest types use the same objective system. Here are the available objective types:

| Objective Type | Description | Example Target |
|---------------|-------------|----------------|
| `blocks_mined` | Mine/break blocks | `Rock_Stone*`, `Ore_*`, `any` |
| `blocks_chopped` | Chop trees/wood | `Wood_Oak*`, `any` |
| `blocks_dug` | Dig dirt, sand, or gravel | `Sand_*`, `Dirt_*`, `any` |
| `blocks_harvested` | Harvest crops | `Plant_Crop_Wheat*` |
| `blocks_placed` | Place blocks | `Bench_Campfire`, `Furniture_Crude_Torch` |
| `flowers_picked` | Pick flowers | `Plant_Flower_Common_Red`, `any` |
| `kills` | Kill entities/mobs | `Goblin_*`, `Fen_Stalker`, `Scorpion` |
| `player_kills` | Kill other players | `player` |
| `damage_dealt` | Deal damage to entities | `Scorpion`, `any` |
| `damage_taken` | Receive damage | `any` |
| `items_crafted` | Craft items | `Tool_Pickaxe_Crude`, `Potion_*` |
| `items_collected` | Collect/pick up items | `Ore_*`, `@consumable` |
| `deliver` | Hand items over to an NPC | Item ID, plus `deliverTo` (NPC ID) |
| `distance_traveled` | Walk/run distance | `any` |
| `playtime_minutes` | Play for a duration (minutes) | `any`, `total` |
| `interact_npc` | Interact with an NPC | `guide_finn`, `merchant_aldric` |
| `zone_discovered` | Discover/enter a zone | `Forgotten_Temple` |
| `command_executed` | Execute a server command | Command name (no `/`) |
| `level_reached` | Reach a player level | The level, e.g. `10` |
| `wait` | Wait a number of seconds | none (`count` = seconds) |

`items_consumed` and `complete_hub_quests` are still read from files but are not counted by Quests 2.1. See [Objectives](./objectives).

:::tip Wildcard Targets
Use `*` wildcards to match multiple items: `Ore_*` matches all ore types, `Goblin_*` matches all goblin variants. Use `any` to match everything. Use `@consumable` to match all food items.
:::

## Reward Types

| Reward Type | Fields | Description |
|------------|--------|-------------|
| `quest_tokens` | `amount` | Award quest tokens (internal currency) |
| `item` | `item_id`, `amount` | Give a specific item |
| `lootbag` | `lootbag_id` | Give a loot bag (random rewards) |
| `currency` | `currency`, `amount` | Grant a named currency (gold, silver) |
| `rpg_xp` | `amount` | Grant character XP |
| `mmo_xp` | `skill`, `amount` | Grant skill-specific XP |
| `endless_xp` | `amount` | Grant Endless leveling XP |
| `leveling_xp` | `amount` | Grant main leveling XP |
| `title` | `title_id` | Unlock a player title |
| `achievement` | `achievement_id` | Unlock an achievement |
| `command` | `command`, `executor` | Execute a server command |

## Quest Pools

Daily and weekly quests are assigned from **pools** defined in `daily_pool.json` and `weekly_pool.json`. Each pool entry has a quest ID and an optional weight:

```json
{
  "pool": [
    { "quest_id": "daily_mine_stone", "weight": 10 },
    { "quest_id": "daily_kill_mobs", "weight": 10 },
    { "quest_id": "daily_harvest", "weight": 8 }
  ]
}
```

Higher weight means the quest is more likely to be selected. Add your custom quests to the pool via the `custom/` folder files.

## Additional Quest Fields

These fields can be used on any quest type:

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `difficulty` | string | — | Difficulty level: `"easy"`, `"medium"`, `"hard"`, `"legendary"` |
| `sequential` | bool | `false` | If `true`, objectives must be completed in order |
| `timeLimit` | int | `0` | Time limit in seconds (0 = no limit). Reserved for future use |
| `setsFact` | string | — | Fact key to set when the quest is completed |
| `setsFactValue` | string | `"true"` | Value to assign to the fact |
| `trigger` | object | — | Auto-start trigger (see [Triggers](#triggers)) |
| `nextQuest` | string | — | Quest ID to auto-offer after completion |
| `options` | object | — | Quest options (see below) |

### Quest Options

| Option | Default | Description |
|--------|---------|-------------|
| `auto_start` | `false` | Starts on its own as soon as the prerequisites are met |
| `auto_claim` | `false` | Completes and pays as soon as the last objective is done |
| `sequential` | `false` | Same as the top-level `sequential` |
| `hidden` | `false` | Hidden in the Questbook while locked |
| `trackable` | `true` | Can be tracked on the HUD |
| `rerollable` | `true` | Daily/weekly can be rerolled |
| `maxRerolls` | `1` | Reroll limit for this quest |
| `repeatable` | `false` | A side or story quest can be done again after completion (dailies and weeklies always repeat with the pool) |
| `repeat_cooldown_hours` | `0` | For repeatable quests that are not daily or weekly: hours after the last completion before the quest can start again. `0` = right away, as before 2.1.0 |

```json
"options": {
  "repeatable": true,
  "repeat_cooldown_hours": 24
}
```

The admin window sets these under **Flow → Repeat**. Its check warns when a repeatable quest has no cooldown.

### Difficulty Levels

The `difficulty` field controls the quest's tier color and reward multiplier:

| Difficulty | Color | Multiplier | Aliases |
|-----------|-------|-----------|---------|
| `easy` | Gray | 1.0x | `normal`, `simple`, `basic` |
| `medium` | Blue | 2.0x | `uncommon`, `moderate`, `challenging` |
| `hard` | Purple | 3.0x | `difficult`, `very_hard`, `expert` |
| `legendary` | Gold | 5.0x | `extreme`, `mythic`, `artifact`, `ancient` |

### Triggers

Triggers automatically start quests when certain conditions are met. Add a `trigger` object to the quest definition:

```json
{
  "id": "tutorial_start",
  "trigger": {
    "type": "first_join",
    "startsQuest": "tutorial_start"
  }
}
```

| Trigger Type | Fields | Description |
|-------------|--------|-------------|
| `first_join` | — | Player joins for the first time |
| `zone_enter` | `zoneId` | Player enters a specific zone |
| `npc_interact` | `npcId` | Player interacts with a specific NPC |
| `quest_complete` | `questId` | Another quest is completed |
| `dialog_complete` | `dialogId` | A dialog is completed |
| `dialog_choice` | `dialogId` | A dialog choice is selected |

The types `zone_exit`, `item_obtain`, `item_use` and `block_interact` are still read from files, but nothing fires them in Quests 2.1. The admin window only offers the six types above.

Trigger fields:

| Field | Type | Description |
|-------|------|-------------|
| `type` | string | Trigger type (see above) |
| `startsQuest` | string | Quest ID to start (auto-filled with parent quest ID) |
| `completesObjective` | string | Format: `"quest_id:objective_id"` |
| `condition` | string | Fact condition that must be true |
| `setsFact` | string | Fact key to set when triggered |
| `setsFactValue` | any | Value for the fact (default: `true`) |

`setsFact` and `completesObjective` work since 2.1.0.