# Dialogue Authoring Guide

The dialogue subsystem stores authored conversations as `DialogueTree` objects.
Each tree has a `startNodeId`, an NPC owner, a priority, optional start
conditions, and a `Map<number, DialogueNode>` keyed by node ID.

## Node Types

- `TEXT`: spoken line. Use `nextNodeId` to continue, or omit it for a terminal
  line.
- `CHOICE`: player-facing choices. Each `DialogueChoice` targets another node
  and can carry conditions, actions, relationship deltas, and consequence tags.
- `CONDITION`: routing node with `condition`, `trueBranchId`, and
  `falseBranchId`.
- `ACTION`: executes actions and can route with `nextNodeId`.
- `BRANCH`: generic routing node. It can use a condition, or fall through to
  `nextNodeId`.
- `RANDOM`: weighted routing through `randomBranches`.

Run `validateDialogueTree` on authored trees. Errors catch missing start nodes,
missing targets, empty choice nodes, invalid random weights, and incomplete
condition branches. Warnings identify unreachable nodes.

## Conditions

Conditions use a `ConditionOperator`, key, value, and optional `scope`.

- Session variables: default `variables` map.
- Local variables: `DialogueVariableScope.LOCAL`, resettable per conversation.
- NPC variables: `DialogueVariableScope.NPC` plus `npcId` for persistent
  per-character state.
- Global story variables: `DialogueVariableScope.GLOBAL`.

The runtime supports comparisons, inventory flags, quest state, relationship
thresholds, player stats, time-of-day windows such as `21-5`, and prior choice
checks with `CHOICE_MADE`.

## Actions

Actions are deterministic state updates. Existing actions handle items, quests,
gold, experience, flags, relationships, combat, teleport, and sound. The
extended runtime also supports scoped variables, animation commands, and spawn
commands:

- `SET_LOCAL_VARIABLE`, `SET_NPC_VARIABLE`, `SET_GLOBAL_VARIABLE`
- `PLAY_ANIMATION`: writes `lastAnimation` and `animation_<key>`
- `SPAWN_ENTITY`: writes `lastSpawnedEntity` and `spawn_<key>`

Downstream presentation/gameplay systems can consume these command variables and
flags after dialogue traversal.

## Localization and Voice

Use stable `textId` values on nodes and choices. Add tree-level `stringTable`
entries with default text, per-locale translations, and per-locale voice-over
asset paths. Use `localizeDialogueNode` and `localizeDialogueChoices` at
presentation boundaries.

## Tags and Typewriter

Inline tags use square brackets, for example:

```text
Hold[pause=500][happy] the line.
```

`parseDialogueTags` strips tags from visible text and returns structured tag
metadata. `createTypewriterState`, `advanceTypewriter`, and `skipTypewriter`
provide deterministic typewriter behavior over the stripped text.

## Save/Load and Runtime Flow

Use `serializeDialogueState` for save data and `restoreDialogueState` with the
available tree registry to resume mid-conversation. Snapshots persist current
tree ID, current node ID, history, quest state, flags, variables, scoped
variables, choice consequences, queue state, bark cooldowns, and elapsed turns.

Dialogue requests can be queued with `enqueueDialogueRequest`, started with
`dequeueNextDialogueRequest`, or routed through `interruptOrQueueDialogue`.
Higher-priority requests interrupt lower-priority active conversations.

## Barks and Imports

Barks are context-triggered one-liners with contexts, weights, conditions, and
cooldowns. Select with `selectDialogueBark` and apply cooldowns with
`applyDialogueBarkCooldown`.

Simple Ink and Yarn Spinner text can be imported with `importInkDialogue` and
`importYarnDialogue`. Imported trees should still pass `validateDialogueTree`
before shipping.
