Struct FlowInstance 

pub struct FlowInstance { /* private fields */ }

A single independent execution context within a story. The default flow runs from the root container; named flows can be spawned at arbitrary entry points via FlowInstance::new_at.

A FlowInstance is opaque from outside the crate: its internal fields (flow, status, stats) are crate-private, but consumers can hold, clone, serialize, and pass &mut FlowInstance to the runtime’s step functions. Use the inherent methods (step_single_line, choose, transcript, status, etc.) for all interaction.

Implementations

impl FlowInstance

pub fn new_at_root(program: &Program) -> (Self, Context)

Create a new flow instance starting at the program’s root container, along with a fresh Context initialized from the program’s global defaults.

pub fn new_at(program: &Program, container_idx: u32) -> (Self, Context)

Create a new flow instance starting at an arbitrary container index, along with a fresh Context. Use this to spawn a named flow at a specific entry point. The caller is responsible for deciding whether to share the returned Context with other flows or discard it and reuse an existing one.

pub fn step_single_line<R: StoryRng>( &mut self, program: &Program, line_tables: &[Vec<LineEntry>], context: &mut (impl ContextAccess + ?Sized), handler: &dyn ExternalFnHandler, resolver: Option<&dyn PluralResolver>, ) -> Result<Line, RuntimeError>

Execute until one complete line of output is available, or until a yield point (choices/done/ended) if no newline occurs first.

Returns a Line telling the caller what happened (Text/Done/ Choices/End). This is the simple API for consumers whose external handler never defers: if the handler returns ExternalResult::Pending, this errors with UnresolvedExternalCall. For pausable world-access bindings, use advance.

pub fn advance<R: StoryRng>( &mut self, program: &Program, line_tables: &[Vec<LineEntry>], context: &mut (impl ContextAccess + ?Sized), handler: &dyn ExternalFnHandler, resolver: Option<&dyn PluralResolver>, ) -> Result<StepOutcome, RuntimeError>

Like step_single_line, but surfaces a deferred external (ExternalResult::Pending) as StepOutcome::AwaitingExternal instead of an error — so a world-access binding hit during normal playback can pause cleanly. Resolve the pending external and call advance again to continue.

pub fn choose( &mut self, context: &mut (impl ContextAccess + ?Sized), index: usize, ) -> Result<(), RuntimeError>

Select a choice by index. Call step_single_line afterward to continue execution from the chosen branch.

pub fn status(&self) -> StoryStatus

The current execution status of this flow.

pub fn stats(&self) -> &Stats

Runtime statistics (instructions, materialization counts, etc.) accumulated over this flow’s execution.

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

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

The transcript stores structural references (e.g. LineRef) rather than resolved strings, so it can be re-rendered in any locale by passing a different set of line tables to transcript::render_transcript.

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, e.g. after a locale swap).

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

The fragments captured during execution (for re-rendering choice display text and computed substrings in a different locale).

pub fn has_pending_external(&self) -> bool

Returns true if this flow is frozen on an unresolved external call — i.e. the VM hit a CallExternal opcode and the handler returned ExternalResult::Pending, leaving the External frame on top of the call stack.

The orchestration layer (e.g. a Bevy resolver system) polls this to decide whether the flow needs an external resolved before it can be driven further. Resolve via resolve_external.

pub fn pending_external_fn_id(&self) -> Option<DefinitionId>

The DefinitionId of the pending external function, if this flow is frozen on one. Returns None otherwise.

pub fn pending_external_args(&self) -> &[Value]

The arguments to the pending external call, in declaration order. Empty if no external call is pending.

pub fn pending_external_name<'p>(&self, program: &'p Program) -> Option<&'p str>

The ink-declared name of the pending external function, resolved against program’s name table. Returns None if no external is pending (or the entry is missing, which would indicate a malformed program).

The orchestration layer uses this to look up the binding registered for this name.

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

Resolve a pending external call by supplying its return value. Pops the External frame and pushes value onto the value stack so the VM can resume. For fire-and-forget externals, pass Value::Null.

No-op if no external call is pending. After resolving, drive the flow forward with step_single_line.

pub fn begin_function_eval<R: StoryRng>( &mut self, program: &Program, line_tables: &[Vec<LineEntry>], context: &mut (impl ContextAccess + ?Sized), handler: &dyn ExternalFnHandler, container_idx: u32, args: &[Value], resolver: Option<&dyn PluralResolver>, ) -> Result<FunctionEval, RuntimeError>

Evaluate an ink function from engine code, returning its value.

This does not advance the player-visible story: a FunctionEvalFromGame boundary frame is pushed, args are passed in declaration order (exactly as a normal call site would), output is captured and discarded, and the function runs until it returns.

If the function calls an external whose handler returns ExternalResult::Pending (e.g. a binding that needs Bevy World access), evaluation pauses and returns FunctionEval::AwaitingExternal; the caller resolves the external (see resolve_external) and calls resume_function_eval.

container_idx is the function’s container, typically obtained from Program::find_address on the function name. Unlike a normal Call, this does not increment the function’s visit count — an engine query is out-of-band, matching C#’s EvaluateFunction.

Errors

• AlreadyEvaluatingFunction if a function evaluation is already in progress on this flow.
• FunctionYielded if the function presents choices or ends the story (functions must not yield).
• UnresolvedExternalCall if an external has neither a binding nor a fallback.

pub fn resume_function_eval<R: StoryRng>( &mut self, program: &Program, line_tables: &[Vec<LineEntry>], context: &mut (impl ContextAccess + ?Sized), handler: &dyn ExternalFnHandler, resolver: Option<&dyn PluralResolver>, ) -> Result<FunctionEval, RuntimeError>

Resume a function evaluation that paused on FunctionEval::AwaitingExternal, after the pending external has been resolved via resolve_external.

Errors

• NotEvaluatingFunction if no evaluation is in progress.
• Same evaluation errors as begin_function_eval.

pub fn is_evaluating_function(&self) -> bool

Returns true if a function evaluation is in progress (possibly paused awaiting an external).

Trait Implementations

impl Clone for FlowInstance

fn clone(&self) -> FlowInstance

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for FlowInstance

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.