DialogueRunner API

Core methods for running and interacting with dialogues.

createDialogueRunner()

Creates a new DialogueRunner instance with optional configuration.

Signature:

function createDialogueRunner(options?: DialogueRunnerOptions): DialogueRunner

Parameters:

Returns: DialogueRunner — A new runner instance ready to execute dialogues.

Example:

import { createDialogueRunner } from '@motioneffector/dialogue'

// Basic usage
const runner = createDialogueRunner()

// With configuration
const runner = createDialogueRunner({
  gameFlags: myFlagStore,
  speakers: { npc: { name: 'Villager' } },
  onNodeEnter: (node, speaker) => console.log(node.text)
})

Throws:

• ValidationError — When gameFlags is not a valid FlagStore
• ValidationError — When actionHandlers contains non-function values
• ValidationError — When i18n adapter is missing required methods

runner.start()

Starts a dialogue from its start node. Clears previous state and conversation flags.

Signature:

start(dialogue: DialogueDefinition): Promise<DialogueState>

Parameters:

Returns: Promise<DialogueState> — The initial state including current node and available choices.

Example:

const dialogue = {
  id: 'greeting',
  startNode: 'start',
  nodes: {
    start: { text: 'Hello!', choices: [{ text: 'Hi', next: 'end' }] },
    end: { text: 'Goodbye!', isEnd: true }
  }
}

const state = await runner.start(dialogue)
console.log(state.currentNode.text)  // "Hello!"
console.log(state.isEnded)           // false

Throws:

• ValidationError — When start node is not found

runner.getChoices()

Returns available choices for the current node, filtered by conditions.

Signature:

getChoices(options?: GetChoicesOptions): ChoiceDefinition[] | ChoiceWithAvailability[]

Parameters:

Returns: ChoiceDefinition[] — Available choices (default), or ChoiceWithAvailability[] if includeUnavailable: true.

Example:

// Get only available choices
const choices = runner.getChoices()

// Include unavailable choices with availability info
const allChoices = runner.getChoices({ includeUnavailable: true })
allChoices.forEach(choice => {
  console.log(`${choice.text}: ${choice.available ? 'available' : choice.reason}`)
})

// Include disabled choices
const withDisabled = runner.getChoices({ includeDisabled: true })

// Custom filter
const tagged = runner.getChoices({
  filter: choice => choice.tags?.includes('important')
})

runner.choose()

Selects a choice by index and advances to the next node.

Signature:

choose(index: number): Promise<DialogueState>

Parameters:

Returns: Promise<DialogueState> — The new state after the choice.

Example:

const choices = runner.getChoices()
console.log(choices[0].text)  // "Accept quest"

const newState = await runner.choose(0)
console.log(newState.currentNode.text)  // Next node's text

Throws:

• ValidationError — When no active dialogue
• ValidationError — When dialogue has ended
• ValidationError — When index is out of bounds
• ValidationError — When choice is disabled
• ValidationError — When choice conditions are not met
• ValidationError — When target node is not found

runner.getCurrentNode()

Returns the current node definition with interpolated text.

Signature:

getCurrentNode(): NodeDefinition | null

Returns: NodeDefinition | null — The current node, or null if no dialogue is active.

Example:

const node = runner.getCurrentNode()
if (node) {
  console.log(node.text)
  console.log(node.speaker)
}

runner.isEnded()

Checks if the current dialogue has ended.

Signature:

isEnded(): boolean

Returns: boolean — True if the dialogue has reached an end node.

Example:

while (!runner.isEnded()) {
  displayNode(runner.getCurrentNode())
  const choice = await getUserChoice(runner.getChoices())
  await runner.choose(choice)
}
console.log('Dialogue complete!')

Types

DialogueRunnerOptions

interface DialogueRunnerOptions {
  gameFlags?: FlagStore
  actionHandlers?: Record<string, ActionHandler>
  speakers?: Record<string, Speaker>
  i18n?: I18nAdapter
  interpolation?: Record<string, InterpolationFunction>
  onNodeEnter?: (node: NodeDefinition, speaker?: Speaker) => void
  onNodeExit?: (node: NodeDefinition) => void
  onChoiceSelected?: (choice: ChoiceDefinition, index: number) => void
  onDialogueStart?: (dialogue: DialogueDefinition) => void
  onDialogueEnd?: (dialogueId: string, endNode?: NodeDefinition) => void
  onActionExecuted?: (action: Action, result?: unknown) => void
  onConditionEvaluated?: (condition: Condition, result: boolean) => void
}

GetChoicesOptions

interface GetChoicesOptions {
  includeUnavailable?: boolean
  includeDisabled?: boolean
  filter?: (choice: ChoiceDefinition) => boolean
}

DialogueState

interface DialogueState {
  currentNode: NodeDefinition
  availableChoices: ChoiceDefinition[]
  isEnded: boolean
}