# Quest + NPC Workflow

This guide walks you through a complete side quest with an NPC quest giver: the player accepts it from the NPC, chops wood, brings logs back and gets a reward. You can do everything in game with the admin windows (recommended) or with files.

## Overview

You will create:

- A **citizen (NPC)** that stands in the world (KyuubiSoft Core)
- A **quest** with objectives and rewards (KyuubiSoft Quests)
- An **NPC quest profile** that links the citizen to the quest with dialogs
- **Texts** for every language you want

You need `ks.quest.admin` for the Quests admin window and `ks.citizen.admin` (or `ks.admin`) for Core's NPC tools.

---

## Route A: in game (recommended)

### Step 1: Create the NPC

1. Stand where the NPC should be and run `/kscitizen create woodcutter_wren`.
2. Run `/kscitizen edit woodcutter_wren` to open Core's NPC management window. Set the name ("Wren"), the appearance and the behaviour, then **Save**.

See [Citizens & NPCs](https://wiki.kyuubisoft.com/hytale/citizens/) for everything the NPC window can do.

### Step 2: Create the quest

1. Open the Quests admin window with `/ksquestadmin panel`.
2. On **Quests**, choose **New quest**, pick a template and give it the ID `wren_firewood`.
3. In the quest editor:
   - **Basics:** type *Side*, category, difficulty, icon.
   - **Texts:** name and description per language. Missing languages fall back to English.
   - **Objectives:** *Chop wood* `Wood_Oak*` × 20, then *Deliver* `Wood_Oak_Trunk` × 10 with **Deliver to** `woodcutter_wren`.
   - **Rewards:** for example 5 quest tokens and 5 `Food_Bread`. The editor shows the final values after the tier factor.
   - **NPC phases:** Wren offers the quest and takes it in.
4. **Save.** The check blocks saving if something is wrong and shows where.

### Step 3: Set up the NPC profile

1. Back in Core's NPC management (`/kscitizen edit woodcutter_wren`), open the **Talk** tab and press **Quest profile …**. This opens the Quests profile editor for Wren; **Create profile for this NPC** creates the profile file.
2. The quest entry for `wren_firewood` has three phase cards: **offer**, **active** and **complete**. Write the lines per language. In the node editor, give the accept choice the action **Accept quest** and the last node of the complete dialog **Turn in quest**.
3. Optional: proximity whispers (range, pause and texts) and a default dialog for when no quest fits.
4. **Save**, then **Back** returns you to the NPC.

### Step 4: Test

- **Test dialog** in the profile editor plays the dialog without running any action.
- **Test for me** in the quest editor: **Start for me**, **Nearly done** (every objective one step from the end) and **Reset**.
- Then talk to Wren as a player: accept, chop, come back. The delivery confirmation shows the logs Wren takes; **Hand in**, then claim the reward.

---

## Route B: with files

### Step 1: Create the NPC

Create the NPC in game with `/kscitizen create woodcutter_wren` (it is saved to Core's `custom/custom_citizens.json`), or write it into that file by hand. The fields are described in [Citizen Configuration](https://wiki.kyuubisoft.com/hytale/citizens/citizen-config/).

### Step 2: Create the quest

Create or edit `mods/kyuubisoft_questbook/custom/custom_quests.json`:

```json
{
  "quests": [
    {
      "id": "wren_firewood",
      "type": "side",
      "category": "gathering",
      "icon_item": "Wood_Oak_Trunk",
      "name": { "en-US": "Firewood for Wren", "de-DE": "Feuerholz für Wren" },
      "description": {
        "en-US": "Wren needs oak logs for the winter.",
        "de-DE": "Wren braucht Eichenstämme für den Winter."
      },
      "objectives": [
        { "id": "chop", "type": "blocks_chopped", "target": "Wood_Oak*", "count": 20 },
        { "id": "bring", "type": "deliver", "target": "Wood_Oak_Trunk", "count": 10, "deliverTo": "woodcutter_wren" }
      ],
      "rewards": [
        { "type": "quest_tokens", "amount": 5 },
        { "type": "item", "item_id": "Food_Bread", "amount": 5 }
      ]
    }
  ]
}
```

| Field | Description |
|-------|-------------|
| `id` | Unique quest ID (snake_case) |
| `type` | `side`, `story`, `daily` or `weekly` |
| `icon_item` | Item ID shown as the quest icon |
| `name`, `description` | Texts per language (or use translation keys, see Step 3) |
| `objectives` | What the player must do: `type`, `target`, `count`. See [Objectives](https://wiki.kyuubisoft.com/hytale/quest-system/objectives/) |
| `rewards` | What the player gets. See [Rewards](https://wiki.kyuubisoft.com/hytale/quest-system/rewards/) |
| `prerequisites` | Optional: quests, facts, level or permission needed first. See [Story Quests](https://wiki.kyuubisoft.com/hytale/quest-system/story-quests/#prerequisites) |

### Step 3: Texts (optional)

Instead of inline texts you can use translation keys in `mods/kyuubisoft_questbook/localization/custom_en-US.json` (and `custom_de-DE.json` and so on):

```json
{
  "quest.wren_firewood.name": "Firewood for Wren",
  "quest.wren_firewood.description": "Wren needs oak logs for the winter.",
  "quest.wren_firewood.obj.chop": "Chop oak trees",
  "quest.wren_firewood.obj.bring": "Bring 10 oak logs to Wren"
}
```

| Key | Usage |
|-----|-------|
| `quest.<questId>.name` | Quest name |
| `quest.<questId>.description` | Quest description |
| `quest.<questId>.obj.<objectiveId>` | Objective text |

Custom files (`custom_<lang>.json`) are never overwritten by updates.

### Step 4: Create the NPC quest profile

Create `mods/kyuubisoft_questbook/quest_npc_profiles/woodcutter_wren.json`:

```json
{
  "citizenId": "woodcutter_wren",
  "quests": [
    {
      "questId": "wren_firewood",
      "priority": 10,
      "offer": {
        "speaker": "Wren",
        "nodes": [
          { "id": "greeting", "type": "TEXT", "lines": ["Winter is coming and my woodpile is empty."], "next": "ask" },
          {
            "id": "ask", "type": "CHOICE", "lines": ["Could you bring me ten oak logs?"],
            "choices": [
              { "text": "I'll do it!", "macro": "start_quest" },
              { "text": "Not right now." }
            ]
          }
        ]
      },
      "active": { "speaker": "Wren", "lines": ["Still need those ten oak logs."] },
      "complete": { "speaker": "Wren", "lines": ["Wonderful, that will keep me warm!"], "action": "complete_quest" }
    }
  ],
  "defaultDialog": { "speaker": "Wren", "lines": ["Thanks again for the firewood!"] }
}
```

| Field | Description |
|-------|-------------|
| `citizenId` | Must match the NPC ID |
| `quests` | One entry per quest, with `offer`, `active` and `complete` dialogs |
| `macro` / `action` | `start_quest` accepts, `complete_quest` claims the quest (objectives and consumed items are checked), `set_fact:name=value` sets a story fact. Any other text runs as a console command and needs `ks.core.admin.dialog.console` |
| `defaultDialog` | Shown when no entry fits. Without it, the NPC keeps its shop, bank and Core dialogs |

Lines can be plain text or translation keys. See [NPC Quest Profiles](https://wiki.kyuubisoft.com/hytale/quest-system/npc-quest-profiles/) for every field, proximity whispers and the full node format.

### Step 5: Reload and test

1. `/ksquestadmin reload` reloads quests, NPC profiles and texts.
2. If you edited Core's NPC file by hand, `/kscitizen reload` loads it.
3. `/ksquestadmin debugmode` shows live tracking events in the server console.
4. Talk to the NPC, accept the quest, chop, deliver, claim.
5. `/ksquestadmin reset <yourname> wren_firewood` resets the quest so you can test again.

---

## Troubleshooting

| Problem | Solution |
|---------|----------|
| NPC does not appear | Check the NPC's world and position in Core's NPC management, or `/kscitizen respawn <id>` |
| NPC has no quest dialog | `citizenId` must match the NPC ID; the profile editor lists "Profile without NPC" |
| Quest does not start | Check the prerequisites; the Questbook shows the reason a quest is locked |
| Objectives do not count | Check objective `type` and `target`; use the admin window's pickers or `/ksquestadmin debugmode` |
| Delivery takes nothing | The player must carry the item and the objective's `deliverTo` must be this NPC |
| Rewards not given | Check reward `type` and `item_id`; a full inventory keeps the rest as a pending reward |

The admin window's **check** finds most of these problems before you test.

## Mod Editor alternative

The browser-based **Mod Editor** at modeditor.kyuubisoft.com can also create quests, NPC profiles and translations and export them as files or ZIP. See the [Mod Editor Workflow](./mod-editor-workflow) guide.