StoryGraph

StoryGraph represents an interactive dialogue flow with branching choices, condition checks against WorldFacts, fact consequences, and diagnostics.

Constructor

new StoryGraph(definitionopt)

Parameters:
NameTypeAttributesDescription
definitionObject<optional>

Classes

StoryGraph

Members

currentNodeId

Current dialogue node ID.

history

Sequence of visited node IDs in order.

state

Current story state ('unstarted', 'active', 'completed').

visitedNodes

Set of unique visited node IDs.

Methods

(static) validate(storyDef) → {Object}

Validates a story graph definition structure.

Parameters:
NameTypeDescription
storyDefObject
Returns:
Type: 
Object

addNode(node) → {this}

Adds a dialogue node to the graph.

Parameters:
NameTypeDescription
nodeObject
Returns:
Type: 
this

advance() → {Object|null}

Advances linear dialogue to the next node (when node has no choices but defines 'next').

Returns:
Type: 
Object | null

choose(choiceIndexOrId) → {Object|null}

Selects a dialogue choice by index or ID, applies consequences, and transitions.

Parameters:
NameTypeDescription
choiceIndexOrIdnumber | string
Returns:

The new current node, or null if dialogue ended

Type: 
Object | null

diagnostics() → {Object}

Runs comprehensive diagnostics on the story graph: detects missing node references, absent speakers, and contradictory conditions.

Returns:
Type: 
Object

getAvailableChoices(nodeIdopt) → {Array.<Object>}

Returns only the choices currently available according to WorldFacts.

Parameters:
NameTypeAttributesDefaultDescription
nodeIdstring<optional>
null
Returns:
Type: 
Array.<Object>

getChoices(nodeIdopt) → {Array.<Object>}

Returns all choices for a node with their availability evaluated against facts.

Parameters:
NameTypeAttributesDefaultDescription
nodeIdstring<optional>
null
Returns:
Type: 
Array.<Object>

getCurrentNode() → {Object|null}

Returns the current node enriched with available choices.

Returns:
Type: 
Object | null

getNode(nodeId) → {Object|null}

Gets a node by ID.

Parameters:
NameTypeDescription
nodeIdstring
Returns:
Type: 
Object | null

hasNode(nodeId) → {boolean}

Checks if a node ID exists in the graph.

Parameters:
NameTypeDescription
nodeIdstring
Returns:
Type: 
boolean

isActive() → {boolean}

Checks if dialogue sequence is active.

Returns:
Type: 
boolean

isCompleted() → {boolean}

Checks if dialogue sequence has completed.

Returns:
Type: 
boolean

reset()

Resets dialogue to unstarted state.

restore(snapshot) → {this}

Restores dialogue state from snapshot.

Parameters:
NameTypeDescription
snapshotObject
Returns:
Type: 
this

setFacts(facts) → {this}

Binds or updates the authoritative WorldFacts instance.

Parameters:
NameTypeDescription
factsWorldFacts
Returns:
Type: 
this

snapshot() → {Object}

Serializes runtime dialogue state for save games.

Returns:
Type: 
Object

start(nodeIdopt, factsopt) → {Object}

Starts the dialogue sequence at the given node or initialNodeId.

Parameters:
NameTypeAttributesDefaultDescription
nodeIdstring<optional>
null
factsWorldFacts<optional>
null
Returns:

Current node

Type: 
Object