DialogueRunner

Plays a story's nodes - lines, then choices or jumps - for your dialogue UI to show. It draws nothing: ask it for currentLine() or choices(), and tell it advance() or choose(index). Each of start/advance/choose returns a StoryResult: settle the story (StoryState.settle()), save and act on its posts and messages as your game needs.

Properties

backlog (Array.<StoryLineView>) — Lines shown so far, oldest first, with each choice taken (isChoice true).
backlogLimit (integer) — The most entries kept in the backlog.
random (function) — Picks the index (0 to count - 1) of a random candidate. Replace it for repeatable tests.

Constructor

new DialogueRunner(
state: StoryState,
story: StoryData,
): DialogueRunner

Parameters

state (StoryState)
story (StoryData) — the same story the state was built from

Instance Methods

`start(id: string): StoryResult`

Starts a conversation at a node id (a single node or a candidate group). Afterwards isActive() is false if no candidate passed, or the node ended straight away.

Parameters

id (string)

Returns

StoryResult

`startNode(node: StoryNode): StoryResult`

Plays a node that isn't in the story, e.g. a one-off message. It records no visits, and getPosition() returns invalid while it plays.

Parameters

node (StoryNode)

Returns

StoryResult

`cancel(): void`

Ends the conversation. Effects of the node being read don't run.

Returns

void

`isActive(): boolean`

Whether a conversation is playing. False before start(), after it finishes or cancel(), and when start() found no passing candidate - close your dialogue UI then.

Returns

boolean

`isChoosing(): boolean`

Returns

boolean — true while waiting for choose()

`currentLine(): StoryLineView`

Returns

StoryLineView — the line to show, or invalid while choosing or when inactive

`advance(): StoryResult`

Moves past the current line. After a node's last line its effects run, then its choices show, or it calls, jumps or ends.

Returns

StoryResult

`choicesFollow(): boolean`

True when the current line is the last of its node and one of the node's choices can be taken - a UI can show them with this line by calling advance() as soon as the line is displayed. Choices are checked before the node's effects run, so one that only its own effects enable doesn't count.

Returns

boolean

`choices(): Array.<ChoiceView>`

Returns

Array.<ChoiceView> — the choices to show while choosing (empty otherwise)

`choose(index: integer): StoryResult`

Takes a choice from choices(). A fallback (unlabelled) choice whose call returns is offered again unless it's once or its when changes. A disabled or out-of-range index does nothing.

Parameters

index (integer) — into choices()

Returns

StoryResult

`getPosition(): RunnerPosition`

Returns

RunnerPosition — where the conversation is, to save; invalid if inactive or playing startNode()

`restore(position: dynamic): boolean`

Resumes a saved conversation. The backlog isn't part of the position - save and restore it yourself if you show one. Candidates are saved by index, so reordering a candidate list in the story can resume a different one. If the saved node's choices are no longer available it carries on to its fallback or call/goto, and the posts and messages of any effects that run then are dropped (there is no StoryResult to return them in).

Parameters

position (dynamic) — from getPosition()

Returns

boolean — false (and inactive) if it doesn't fit this story any more