Struct Story 

pub struct Story<'p, R: StoryRng = FastRng> { /* private fields */ }

Per-instance mutable state for executing stories.

Created from a Program via Story::new. Holds all mutable state (stacks, globals, output buffer) while the immutable program data lives in Program.

Generic over R: StoryRng — defaults to FastRng. Use DotNetRng for .NET-compatible deterministic output.

Implementations

impl<'p, R: StoryRng> Story<'p, R>

pub fn new(program: &'p Program, line_tables: Vec<Vec<LineEntry>>) -> Self

Create a new story instance from a linked program and its line tables.

pub fn set_plural_resolver(&mut self, resolver: Box<dyn PluralResolver>)

Set the plural resolver for Select resolution in localized lines.

pub fn set_line_tables(&mut self, tables: Vec<Vec<LineEntry>>)

Replace the active line tables (e.g. for locale swapping).

pub fn line_tables(&self) -> &[Vec<LineEntry>]

Read-only access to the current line tables.

pub fn transcript(&self) -> &[OutputPart]

The full append-only transcript of all output parts produced so far.

pub fn transcript_len(&self) -> usize

Number of parts in the transcript.

pub fn reset_cursor(&mut self)

Reset the transcript read cursor to the beginning (for re-rendering).

pub fn resolve_transcript_slice( &self, range: Range<usize>, ) -> Vec<(String, Vec<String>)>

Resolve a slice of the transcript against the current line tables. Returns (text, tags) tuples — one per line in the resolved output.

pub fn pending_choices(&self) -> Vec<Choice>

Re-resolve all pending choices against the current line tables. Returns the same choices that would appear in Line::Choices, but freshly resolved (useful after locale switch).

pub fn resolve_fragment(&self, idx: u32) -> String

Resolve a fragment against the current line tables.

pub fn choice_fragment_idx(&self, choice_index: usize) -> Option<u32>

Get the fragment index for a pending choice’s display text, if any.

pub fn fragments(&self) -> &[Fragment]

Read-only access to the fragment store (for transcript serialization).

pub fn program(&self) -> &Program

Read-only access to the program.

pub fn into_snapshot(self) -> (StorySnapshot<R>, Vec<Vec<LineEntry>>)

Detach story state from the program, consuming the story.

pub fn from_snapshot( program: &'p Program, snapshot: StorySnapshot<R>, line_tables: Vec<Vec<LineEntry>>, ) -> Self

Reattach a snapshot to a program with line tables.

pub fn continue_single(&mut self) -> Result<Line, RuntimeError>

Execute until one line of content (up to newline), or until a yield point (choices/end) if no newline occurs first.

The returned Line variant tells you what to do next:

• Line::Text — more output may follow, keep calling.
• Line::Choices — call choose then resume.
• Line::End — the story has permanently ended.

pub fn continue_single_observed( &mut self, observer: &mut dyn WriteObserver, ) -> Result<Line, RuntimeError>

Like continue_single but with a WriteObserver that receives notifications for every state mutation.

pub fn continue_single_with( &mut self, handler: &dyn ExternalFnHandler, ) -> Result<Line, RuntimeError>

Like continue_single but with a custom external function handler.

pub fn continue_maximally(&mut self) -> Result<Vec<Line>, RuntimeError>

Execute until the next yield point, collecting all lines.

Returns a Vec<Line> where the last element is always Line::Choices or Line::End, and all preceding elements are Line::Text.

pub fn continue_maximally_with( &mut self, handler: &dyn ExternalFnHandler, ) -> Result<Vec<Line>, RuntimeError>

Like continue_maximally but with a custom external function handler.

pub fn continue_maximally_observed( &mut self, observer: &mut dyn WriteObserver, ) -> Result<Vec<Line>, RuntimeError>

Execute until the next yield point with a WriteObserver that receives notifications for every state mutation.

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

Select a choice by index, then resume with continue_single or continue_maximally.

pub fn stats(&self) -> &Stats

Read-only access to the default flow’s VM statistics.

pub fn has_pending_external(&self) -> bool

Returns true if the default flow has a pending external call (an External frame on top of the call stack).

pub fn resolve_external(&mut self, value: Value)

Resolve a pending external call on the default flow by providing the return value. For fire-and-forget calls, pass Value::Null.

After resolving, call continue_maximally to continue execution.

pub fn invoke_fallback(&mut self) -> Result<(), RuntimeError>

Resolve a pending external call on the default flow by invoking the ink-defined fallback body. The fallback is a function call whose output becomes the return value.

After invoking, call continue_maximally to continue execution.

pub fn spawn_flow( &mut self, name: &str, entry_point: DefinitionId, ) -> Result<(), RuntimeError>

Spawn a new flow instance starting at the given entry point.

entry_point is the DefinitionId of the target container (e.g., a knot). Each flow instance gets its own globals, visit counts, and execution state.

pub fn continue_flow_maximally( &mut self, name: &str, ) -> Result<Vec<Line>, RuntimeError>

Run a named flow instance until the next yield point.

pub fn continue_flow_maximally_with( &mut self, name: &str, handler: &dyn ExternalFnHandler, ) -> Result<Vec<Line>, RuntimeError>

Run a named flow instance with an external function handler.

pub fn choose_flow( &mut self, name: &str, index: usize, ) -> Result<(), RuntimeError>

Select a choice in a named flow.

pub fn destroy_flow(&mut self, name: &str) -> Result<(), RuntimeError>

Destroy a named flow instance.

pub fn flow_names(&self) -> Vec<&str>

List active flow names.

pub fn debug_state(&self) -> String

Dump the current execution state for debugging.

Returns a human-readable summary of the call stack, current position, value stack, output buffer, globals, and pending choices.

pub fn did_safe_exit(&self) -> bool

Returns whether the last execution cycle ended with a safe exit (explicit -> DONE opcode). If false after a Done line, the story ran out of content.

pub fn did_unsafe_yield(&self) -> bool

Returns whether the last execution cycle passed through an empty choice set (a Yield opcode with no pending choices).

pub fn step_once( &mut self, ) -> Result<Option<(String, u32, usize)>, RuntimeError>

Execute a single VM step and return a debug trace of what happened.

Returns (opcode_description, container_idx, offset_before) or None if the step didn’t decode an opcode (frame exhaustion, thread completion, etc).

Trait Implementations

impl<R: StoryRng> Clone for Story<'_, R>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.