# NPC Quest Profiles

# NPC Quest Profiles

NPC Quest Profiles connect Citizens (NPCs from KyuubiSoft Core) to quests. Each profile defines which quests an NPC offers, what it says in each phase, and how it behaves when a player is nearby. Profiles are JSON files in the `quest_npc_profiles/` folder, and since 2.1.0 they are edited in game on the **NPC profiles** tab of the [admin window](./admin-panel#npc-profiles).

## Overview

When a player talks to an NPC that has a quest profile, the first step that fits wins:

1. **Delivery open** -- the player has a `deliver` objective for this NPC and carries items for it: the [delivery confirmation](./quest-book-ui#delivery-confirmation) opens.
2. **Turn-in ready** -- the player has finished a quest this NPC takes in: the completion dialog (or the "ready to claim" strip of the quest giver window).
3. **Offer** -- the NPC has a quest the player can start. With two or more at once, the [quest giver window](./quest-book-ui#quest-giver-window) opens with all of them as cards.
4. **Quest running** -- the player has an active quest from this NPC: the reminder dialog.
5. **Not ready** -- quests exist but no requirement is met yet: the "not ready" dialog.
6. **Default** -- the default dialog.
7. **Otherwise** -- without a default dialog, the NPC does what Core's NPC management set up: shop, bank or Core dialogs.

## Profile JSON Structure

Each profile is a single JSON file per NPC:

```json
{
  "citizenId": "smith_gorn",
  "quests": [
    {
      "questId": "story_iron_forge",
      "priority": 10,
      "requires": ["tutorial_sustainability"],
      "offer": { "speaker": "Gorn", "nodes": [/* ... */] },
      "active": { "speaker": "Gorn", "lines": ["npc.smith_gorn.active.1"] },
      "complete": { "speaker": "Gorn", "lines": ["..."], "action": "complete_quest" }
    }
  ],
  "proximityMessages": {
    "offer": "npc.smith_gorn.proximity.offer",
    "active": "npc.smith_gorn.proximity.active",
    "complete": "npc.smith_gorn.proximity.complete",
    "defaultMsg": "npc.smith_gorn.proximity.default"
  },
  "proximityRange": 20,
  "proximityCooldown": 300,
  "defaultDialog": { "speaker": "Gorn", "lines": ["npc.smith_gorn.default.1"] },
  "notReadyDialog": { "speaker": "Gorn", "lines": ["npc.smith_gorn.not_ready.1"] }
}
```

### Top-Level Fields

| Field | Required | Description |
|-------|----------|-------------|
| `citizenId` | Yes | Must match the Citizen ID from the Citizens system |
| `_config_version` | No | Schema version for auto-update detection (current: "2") |
| `quests` | Yes | Array of quest dialog entries |
| `selectionIntro` | No | Greeting above the quest choice when the NPC offers several quests at once (empty = first line of the default dialog) |
| `defaultDialog` | No | Dialog when no entry fits. Without it, the NPC keeps opening its shop, bank and Core dialogs |
| `notReadyDialog` | No | Shown when entries are open but none fits yet |
| `proximityMessages` | No | Chat whisper messages for proximity detection |
| `proximityRange` | No | Whisper range in blocks, 1 to 64 (default: 12) |
| `proximityCooldown` | No | Seconds between whispers per player, 0 to 86400 (default: 300) |

### Quest Dialog Entry

Each entry in the `quests` array ties a quest to this NPC with phase-specific dialogs:

| Field | Required | Description |
|-------|----------|-------------|
| `questId` | Yes | Quest definition ID to link |
| `priority` | No | Lower number = checked first (default: 10) |
| `requires` | No | Array of quest IDs that must be completed first |
| `offer` | No | Dialog shown when quest is available to accept |
| `active` | No | Dialog shown while quest is in progress |
| `complete` | No | Dialog shown when objectives are done and quest can be turned in |

:::tip
Not every NPC needs all three phases. You can split quests across NPCs -- for example, NPC A has the `offer` phase while NPC B has the `complete` phase. This lets players pick up a quest from one NPC and turn it in at another.
:::

## Dialog Formats

### Simple Format

Uses a flat list of text lines. For offer dialogs, add `acceptButton`/`declineButton`:

```json
{
  "speaker": "Gorn",
  "lines": ["Would you like to help me forge some iron?"],
  "acceptButton": "Sure!",
  "declineButton": "Maybe later.",
  "action": "start_quest"
}
```

### Full Format (Nodes)

Uses a tree of dialog nodes for branching conversations. Node types: **TEXT** (shows lines, advances to `next`) and **CHOICE** (shows clickable options):

```json
{
  "speaker": "Gorn",
  "nodes": [
    { "id": "greeting", "type": "TEXT", "lines": ["Welcome!"], "next": "accept" },
    {
      "id": "accept", "type": "CHOICE", "lines": ["Will you help me?"],
      "choices": [
        { "text": "Of course!", "macro": "start_quest" },
        { "text": "Not now." }
      ]
    }
  ]
}
```

### Actions and Macros

| Action | Description |
|--------|-------------|
| `start_quest` | Starts the linked quest for the player. All requirements apply |
| `complete_quest` | Claims the linked quest like the **Claim** button: objectives are checked and consumed items are verified, then the rewards are paid |
| `set_fact:name=value` | Sets a story fact for the player (`set_fact:name` sets it to `true`). Also read as `set_fact name=value` |
| any other text | Runs as a **console command**. Adding, changing or removing it needs `ks.core.admin.dialog.console` (see [Permissions](./permissions#the-console-rule)) |

In the full format, macros are set on individual nodes or choices via the `"macro"` field. In `defaultDialog` and `notReadyDialog`, which belong to no quest, only `set_fact` and console commands run.

Before 2.0.0, `complete_quest` force-completed every objective. It now claims normally; story turn-ins with their own dialog steps stay dialogs.

:::info
Dialog text values can be literal strings or localization keys (e.g., `npc.smith_gorn.default.1`). If a matching key exists in the localization files, the translated text is shown.
:::

## Multiple Quests Per NPC

A single NPC can offer multiple quests. The `requires` field controls ordering and `priority` determines check order. When two or more quests are available at the same time, the **quest giver window** opens with every offered quest as a card (three per page), its objectives, rewards and, for locked quests, the reason.

Example of a sequential quest chain (quests unlock one after another):

```json
{
  "citizenId": "guide_finn",
  "quests": [
    { "questId": "tutorial_awakening", "priority": 1, "requires": [] },
    { "questId": "tutorial_first_steps", "priority": 2, "requires": ["tutorial_awakening"] },
    { "questId": "tutorial_workbench", "priority": 3, "requires": ["tutorial_first_steps"] }
  ]
}
```

## Proximity Detection

### Chat Whispers

When a player comes within `proximityRange`, a chat whisper is sent based on the current quest phase (offer open, quest running, turn-in ready, otherwise). The message appears as `[NPC Name] text`. The NPC plays a wave animation when a quest is available. Placeholders `{PlayerName}` and `{CitizenName}` are replaced automatically. The cooldown prevents spam (default: 300 seconds per NPC per player). An empty text means no whisper in that situation.

### Proximity Hint HUD

Nearby quest NPCs also show a hint with the NPC's picture on the HUD. It is set server-wide in `config.json`:

```json
{ "proximityToast": { "enabled": true, "toastRange": 20.0 } }
```

## World Map Markers

Quest NPCs automatically receive world map markers based on the player's quest status:

| Marker | Meaning |
|--------|---------|
| `quest_available` | NPC has a quest the player can accept |
| `quest_turn_in` | NPC can receive a completed quest |
| `quest_progress` | Player has an active quest from this NPC |

Markers update automatically when a player accepts, completes, or abandons a quest. They are per-player, so different players see different markers on the same NPC.

## Editing in game

The **NPC profiles** tab of the [admin window](./admin-panel#npc-profiles) (`/ksquestadmin npcprofile [citizenId]`) edits everything on this page:

- A list of all profiles with **Profile without NPC**, **Give to another NPC** and **Who uses this NPC?**.
- Quest entries with phase cards, and a node editor for the offer, active and complete dialogs.
- Default, "not ready" and proximity texts per language. Shared texts apply everywhere, and every NPC can have its own text.
- **Phase preview** for a chosen player and **Test dialog**, which runs no actions.
- **Open in Core's dialog editor** for the NPC's Core dialogs.

From Core's NPC management window, **Quest profile …** on the Talk tab opens the profile of that NPC, and **Back** returns to that NPC on the Talk tab, also after the questbook view or Core's dialog editor was open in between. An NPC without a profile gets a **Create profile for this NPC** button. Before an NPC's ID is changed or the NPC is deleted in Core, the NPC management lists everything Quests links to it.

## Core dialogs and quests

Core's own dialog editor can also drive quests (with Core 2.9.0 or newer):

- **Actions:** *Start quest* (all requirements apply; the player is told why when it cannot start), *Set fact* (writes into the Quests facts) and *Open window* with `questbook` or `questbook.settings`.
- **Conditions:** `quest_active`, `quest_completed`, `quest_available`, `quest_ready` (active and every objective done) and `fact` (reads the Quests facts, for example `chapter_<id>_completed`).

## File Location

Profile files are stored in `mods/kyuubisoft_questbook/quest_npc_profiles/`. Default profiles are extracted from the mod JAR on first startup. You can edit existing profiles or add new ones by creating additional JSON files in this folder. Shipped profiles you delete stay deleted.

:::warning
The `citizenId` in the profile **must** match an existing Citizen in the Citizens system. If the Citizen does not exist, the profile is loaded but has no effect. The admin window lists such profiles as "Profile without NPC".
:::