Struct Runner 

pub struct Runner<S: VariableStorage> { /* private fields */ }

Drives execution of a compiled Program, yielding DialogueEvents one at a time.

Pull model

The host calls Runner::next_event in a loop until it returns Ok(None) (dialogue ended) or until it receives a DialogueEvent::Options, at which point it must call Runner::select_option before continuing.

Implementations

impl<S: VariableStorage> Runner<S>

pub const fn program(&self) -> &Program

Returns read-only access to the compiled program (node titles, declarations, etc.).

pub const fn phase(&self) -> RunnerPhase

Returns the runner’s current phase for UI or protocol guards.

pub fn new(program: Program, storage: S) -> Self

Creates a new runner for the given program and variable storage.

pub fn start(&mut self, node: &str) -> Result<()>

Starts execution at the given node.

Clears any queued events and abandons an in-flight choice so a new conversation cannot inherit stale DialogueEvent::DialogueComplete or option state from a prior Runner::start.

Errors

Returns DialogueError::UnknownNode if the title does not exist in the program.

pub fn next_event(&mut self) -> Result<Option<DialogueEvent>>

Returns the next event, or Ok(None) when dialogue is finished.

Errors

Returns a DialogueError on runtime failures.

pub fn select_option(&mut self, index: usize) -> Result<()>

Selects an option by index after receiving DialogueEvent::Options.

Errors

Returns DialogueError::ProtocolViolation if called when not awaiting an option selection, or if index is out of range.

pub const fn storage(&self) -> &S

Returns a shared reference to the variable storage.

pub const fn storage_mut(&mut self) -> &mut S

Returns a mutable reference to the variable storage.

pub fn all_variables(&self) -> Vec<(String, Value)>

Returns all variables known to storage (see VariableStorage::all_variables).

For HashMapStorage this is every key/value pair. Custom stores return whatever their VariableStorage::all_variables implementation provides (often empty unless overridden).

pub fn variable(&self, name: &str) -> Option<Value>

Returns a clone of the value for name, or None if unset.

pub fn variable_ref(&self, name: &str) -> Option<Cow<'_, Value>>

Borrows the value for name when the storage can lend it without cloning.

pub const fn library_mut(&mut self) -> &mut FunctionLibrary

Returns a mutable reference to the function library (for registering host functions).

pub fn set_saliency(&mut self, strategy: impl SaliencyStrategy)

Replaces the saliency strategy used for line and node group selection.

pub fn set_provider(&mut self, provider: impl LineProvider)

Sets the line provider used for localisation lookup.

pub fn snapshot(&self) -> RunnerSnapshot

Captures the current session state into a RunnerSnapshot.

The snapshot records the active node title, visit counts, and the set of exhausted <<once>> blocks. Variable storage is not included; persist it via Runner::storage alongside the snapshot when saving.

Restoring with Runner::restore will restart execution from the beginning of the snapshotted node.

Enable the serde feature on bubbles-dialogue if you need Serialize / Deserialize on RunnerSnapshot.

pub fn restore(&mut self, snapshot: RunnerSnapshot) -> Result<()>

Applies a previously captured RunnerSnapshot, restoring visit counts and the <<once>> exhaustion set, then re-enters the snapshotted node from its beginning.

Errors

Returns DialogueError::UnknownNode if the snapshotted node no longer exists in the program (e.g. after a script update).