# NPC Profiles

# NPC Profiles

NPC Profiles define the dialog and behavior of quest-giving NPCs. Each profile links a **Citizen** (the physical NPC in the world) to one or more **quests** through dialog entries.

## NPC Profile List

The left sidebar shows all loaded NPC profiles. Each entry displays:

- **Citizen ID** -- the unique identifier matching a Citizen entry
- **Quest count** -- how many quests this NPC offers (shown as e.g. `3q`)
- **Source badge** -- `C` for custom profiles you created, no badge for base profiles

Click **+ New** to create a fresh NPC profile, or select an existing one to view or edit it.

## Base vs. Custom Profiles

NPC profiles follow the same base/custom pattern as other editors:

- **BASE** profiles ship with the server. They are read-only in the editor. If you need to modify a base NPC, click **Clone to Custom** to create an editable copy.
- **CUSTOM** profiles are ones you created or cloned. These are fully editable and will be included in your export.

:::warning
Base profiles reset on every server update. Always clone to custom before making permanent dialog changes.
:::

## Editing an NPC Profile

After selecting an NPC, you will see:

### Quest Selector

If the NPC has multiple quests, tabs appear at the top showing each quest ID and its priority. Click a tab to switch between quests. The priority number (e.g. `p1`) determines which quest the NPC offers first when the player has multiple available.

### Quest Info Panel

Shows a summary of the selected quest entry:

- **Priority** -- lower numbers are offered first
- **Requires** -- prerequisite quest IDs (the player must complete these before this quest appears)
- **Has Complete** -- whether a completion dialog exists

### Dialog Tabs

Every quest entry has up to three dialog phases:

| Phase | When it plays |
|-------|--------------|
| **Offer** | Player interacts with the NPC and this quest is available |
| **Active** | Player has accepted the quest but has not finished it yet |
| **Complete** | Player has finished all objectives and returns to turn in |

Click a tab to switch between phases. The Complete tab is disabled if no completion dialog is defined.

## Dialog Types

### Simple Dialog

A straightforward list of lines spoken by the NPC. Fields include:

- **Speaker** -- the display name shown above the dialog text
- **Lines** -- i18n localization keys, displayed in order. Use the arrow buttons to reorder, the X button to remove, or **+ Add line** to append
- **Action** -- an optional server command triggered on dialog completion
- **Accept / Decline Button** -- optional custom button text (i18n keys)

### Node-Based Dialog

For branching conversations. When the editor detects a node-based dialog, it shows a visual **Dialog Tree** above the editor and marks the tab with `nodes`.

Each node has:

- **Type** -- `TEXT` (NPC speaks) or `CHOICE` (player picks an option)
- **Node ID** -- unique identifier within this dialog
- **Lines** -- i18n keys for the NPC's speech
- **Next** -- which node to jump to after this one (or `accept`/`decline`/`close`)
- **Macro** -- optional macro command executed when this node is reached

For CHOICE nodes, you also define **Choices** -- each with:

- **Text** -- i18n key for the choice button
- **Next** -- which node follows if the player picks this choice
- **Macro** -- optional macro for this specific choice

:::tip
Click a node in the visual Dialog Tree to scroll the editor to that node's card. This makes it easy to navigate large dialog trees.
:::

## Proximity Messages

If the NPC has proximity messages configured, a separate section displays them. These are messages shown as floating text when a player walks near the NPC, with a configurable range and cooldown.

## Creating a New NPC Profile

Click **+ New** in the sidebar to open the creation dialog:

1. **Citizen ID** -- must match an existing Citizen entry (or one you plan to create). Must be unique.
2. **Speaker Name** -- the name shown in dialogs. Defaults to the Citizen ID if left blank.
3. **Initial Quest ID** (optional) -- if provided, creates a starter quest entry with placeholder offer/active dialog lines.

## Assigning Quests to NPCs

Use the **Assign Quest Modal** to connect quests and NPCs. It can be opened from:

- The NPC page via **"+ Quest"** on the quest selector tabs
- The Quest page via the **"+ Assign NPC"** button in the NPC Assignment section

### Normal Mode (Single NPC)

Select one NPC and choose which dialog phases it handles:

| Phase | Purpose |
|-------|---------|
| **Offer** | NPC offers the quest |
| **Active** | Dialog while quest is in progress |
| **Complete** | NPC accepts the turn-in (includes `complete_quest` macro) |

You can uncheck **Complete** to make the quest turn-in via QuestBook instead.

### Split NPC Mode

Enable the **"Split NPC"** toggle to assign different NPCs for accept and turn-in:

- **Accept NPC** handles Offer + Active phases
- **Turn-in NPC** handles the Complete phase

This creates two separate quest entries -- one per NPC. The editor's cross-reference display (NPC Roles) shows the split clearly.

### Inline Localization

When assigning, each active phase shows **EN** and **DE** text fields. Enter dialog text directly and the editor creates the i18n keys and values automatically:

- Keys follow the pattern `npc.{citizenId}.{questId}.{phase}.1`
- Values are saved to the localization store and appear in the [Localization Editor](./localization)
- Leave fields empty to create keys with placeholder values

:::tip
You can always edit dialog text later in the NPC profile editor or the Localization Editor.
:::