Crate brink_runtime 

Runtime/VM for executing compiled ink stories.

The runtime takes a StoryData from the compiler, links it into an immutable Program, and executes it via Story.

let (program, line_tables) = brink_runtime::link(&story_data)?;
let mut story = brink_runtime::Story::new(&program, line_tables);
loop {
    match story.continue_single()? {
        Line::Text { text, .. } => print!("{text}"),
        Line::Choices { text, choices, .. } => {
            print!("{text}");
            // pick a choice...
            story.choose(0)?;
        }
        Line::End { text, .. } => {
            print!("{text}");
            break;
        }
    }
}

Re-exports

pub use rng::DotNetRng;

pub use rng::FastRng;

pub use rng::StoryRng;

Modules

rng

Pluggable PRNG for story randomization.

transcript

Transcript binary serialization (.brkt format).

Structs

Choice

A single choice presented to the player.

Context

Shared game state that lives above individual flows.

DebugChoice

A pending choice and the knot it targets.

DebugFrame

One call frame, resolved to a knot/stitch path.

DebugGlobal

A global variable and its current value.

DebugRng

Story RNG state.

DebugSnapshot

A structured, read-only snapshot of the runtime’s current state.

DebugVisit

A visit count for a named knot/stitch.

FallbackHandler

Default handler that always falls back to the ink function body.

FlowInstance

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.

Fragment

A finalized fragment — structural output parts plus any associated tags.

LoadReport

What Story::load_state couldn’t apply, so a host can surface it rather than have data silently vanish. Globals whose name no longer exists are dropped (no slot to hold them) and reported here. Visit/turn counts are never dropped — counts for scopes the current program lacks are retained harmlessly (unused until/unless the scope returns), so they aren’t reported.

ObservedContext

A ContextAccess wrapper that delegates to an inner Context and notifies a WriteObserver on every mutation.

Program

A linked, ready-to-execute program.

RecordedExternal

One recorded external-function result, captured in call order during a live run.

RecordingHandler

Wraps an ExternalFnHandler and records every inline-Resolved external result into a ReplayRecorder during a live run.

ReplayHandler

Replays recorded external results (ReplayMode::Recorded).

ReplayRecorder

An append-only, capped log of external results for one flow, plus a replay cursor. Recorded during the live run; consumed in order during replay.

SaveState

A persistent, name-keyed snapshot of a story’s game state.

Stats

Lightweight counters tracking VM activity over a story’s lifetime.

Story

Per-instance mutable state for executing stories.

StorySnapshot

Owned story state that can be detached from a Program and reattached later.

VisitEntry

One visit/turn-count entry: a scope id and its count, plus (when the scope is a named knot/stitch) an advisory author path for human inspection. The id is the load key; path is cosmetic.

Enums

ExternalResult

Result of an external function handler call.

FunctionEval

Outcome of an engine→ink function evaluation (FlowInstance::begin_function_eval / resume_function_eval).

Line

A single step of story output from Story::continue_single.

LocaleMode

Controls how missing scopes are handled when applying a locale overlay.

OutputPart

A part of accumulated output.

ReplayMode

How a replay obtains external values. Whole-flow granularity.

RuntimeError

Errors that can occur during story linking or execution.

StepOutcome

Outcome of a single FlowInstance::advance step.

StoryStatus

The current execution status of a story.

Constants

RECORDING_CAP

Upper bound on recorded externals per flow (unbounded-growth guard). Beyond it, ReplayRecorder::record drops the result and replay falls through to the ink fallback body for the uncovered tail.

SAVE_FORMAT_VERSION

Current SaveState format version. Bump when the format changes (independent of the story’s own content); version lets a loader migrate.

Traits

ContextAccess

Trait for accessing and mutating story execution state.

ExternalFnHandler

Trait for handling external function calls from ink.

WriteObserver

Observer for state mutations during story execution.

Functions

apply_locale

Apply a locale overlay to a set of base line tables.

link

Link a StoryData into an executable Program.