Navigation API

Methods for navigating dialogue history and moving between nodes.

runner.getHistory()

Returns the history of visited nodes with choice and flag data.

Signature:

getHistory(): HistoryEntry[]

Returns: HistoryEntry[] — Array of history entries in chronological order.

Example:

const history = runner.getHistory()

history.forEach((entry, index) => {
  console.log(`${index + 1}. Node: ${entry.nodeId}`)
  if (entry.choice) {
    console.log(`   Choice: ${entry.choice.text}`)
  }
  console.log(`   Time: ${new Date(entry.timestamp).toISOString()}`)
})

runner.back()

Returns to the previous node and restores conversation flags to their state at that point.

Signature:

back(): Promise<void>

Returns: Promise<void>

Example:

await runner.start(dialogue)
await runner.choose(0)  // Move to next node

console.log(runner.getHistory().length)  // 1

await runner.back()  // Return to previous node

console.log(runner.getHistory().length)  // 0
console.log(runner.getCurrentNode()?.text)  // Original node

Notes:

• Does nothing if history is empty
• Restores conversation flags from the history snapshot
• Fires onNodeEnter for the restored node
• Does not restore game flags (those are persistent)

runner.restart()

Restarts the dialogue from the start node, clearing history.

Signature:

restart(options?: RestartOptions): Promise<DialogueState>

Parameters:

Returns: Promise<DialogueState> — The initial state after restart.

Example:

// Standard restart - clears history and conversation flags
await runner.restart()

// Preserve conversation flags
await runner.restart({ preserveConversationFlags: true })

Throws:

• ValidationError — When no active dialogue

runner.jumpTo()

Jumps directly to a specific node, adding the current node to history.

Signature:

jumpTo(nodeId: string): Promise<void>

Parameters:

Returns: Promise<void>

Example:

await runner.start(dialogue)

// Jump to a specific node
await runner.jumpTo('secret-ending')

console.log(runner.getCurrentNode()?.text)  // Secret ending text
console.log(runner.getHistory().length)     // 1 (jump was recorded)

Throws:

• ValidationError — When no active dialogue
• ValidationError — When target node does not exist

Notes:

• Adds the previous node to history (enables back())
• Fires onNodeExit for the previous node
• Fires onNodeEnter for the target node
• Does not execute node actions on the target (unlike normal transitions)

Types

HistoryEntry

interface HistoryEntry {
  nodeId: string
  node: NodeDefinition
  choiceIndex?: number
  choice?: ChoiceDefinition
  timestamp: number
  conversationFlags: Record<string, FlagValue>
}

RestartOptions

interface RestartOptions {
  preserveConversationFlags?: boolean
}