Crate brink_runtime

Expand description

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.

use std::sync::Arc;

let (program, line_tables) = brink_runtime::link(&story_data)?;
let mut story = brink_runtime::Story::new(Arc::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§

Budget: Caller-supplied cap on a Speculation’s VM stepping, in place of the runtime’s hardcoded STEP_LIMIT/LINE_LIMIT ceilings.
Choice: A single choice presented to the player.
ContextView: Routing view implementing ContextAccess over (&mut World, &mut FlowLocal).
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.
ExternalsReport: Diagnostic record of which externals a KindTieredHandler let through live versus fell back, across the handler’s lifetime.
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.
FlowLocal: Per-flow override layer over the shared World.
Fragment: A finalized fragment — structural output parts plus any associated tags.
JournalEvent: One input that entered the VM.
KindTieredHandler: A stackable ExternalFnHandler that tiers externals by PolicyKind before delegating to a real handler.
ListDelta: Membership delta for one list-valued global.
ListMember: One active member of a list value, resolved for host-facing display. See Program::list_members.
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 ContextAccess implementor (typically World or the ContextView routing view) 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.
ResolvedPolicy: Fast, id/slot-based resolution of a WorldPolicy against a specific Program. Built once at World creation via ResolvedPolicy::resolve; consulted on every state access (from F2.2 on) with O(1) lookups — no string matching on the hot path.
SaveState: A persistent, name-keyed snapshot of a story’s game state.
SessionJournal: One ordered log of every input that entered the VM during a session, plus a terminal fast-restore checkpoint.
SnapshotFrame: One summarized call frame.
SnapshotList: Resolved membership of a List-valued global.
Speculation: A sandboxed, self-contained speculative run over a story’s current state. See the module docs for the full picture.
StateDiff: A pure diff between two StateSnapshots (see diff).
StateSnapshot: A typed, name-resolved snapshot of a session’s game state.
Stats: Lightweight counters tracking VM activity over a story’s lifetime.
Story: Per-instance mutable state for executing stories.
StorySession: A journaling, replayable session wrapping a Story.
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.
World: Shared game state that lives above individual flows.
WorldPolicy: Host-facing, name-based declaration of the world/local split.

Enums§

CommitError: Errors from commit.
DivergenceFound: What was found at a divergence point instead of the recorded event.
DriveOutcome: Outcome of a single FlowInstance::drive call: either the drive reached a terminal line, or it paused on a deferred external mid-drive. Both variants carry every Line produced during this call — for AwaitingExternal, that’s the (possibly empty) run of Line::Text produced before the pause; for Terminal, the terminal line is always the last element (see FlowInstance::drive).
EvalContext: Which evaluation regime a KindTieredHandler is gating for.
EventKind: The kind + payload of a JournalEvent.
ExternalReplayMode: How replay obtains external values.
ExternalResult: Result of an external function handler call.
FailReason: Why replay stopped without diverging.
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.
Mode: Execution mode of a FlowLocal, baked in at construction/fork time and read by ContextView to decide how it routes every unit.
OutputPart: A part of accumulated output.
PolicyError: Errors resolving a WorldPolicy against a Program’s symbol table.
PolicyKind: The effect category a KindTieredHandler gates on. Plain data — the consumer maps its own (richer) external classification onto this two-way split.
ReplayMode: How a replay obtains external values. Whole-flow granularity.
ReplayOutcome: Outcome of replaying a journal prefix against a program.
ReplayWarning: A non-fatal replay observation.
RuntimeError: Errors that can occur during story linking or execution.
Scope: Where a unit of story-state lives: the shared World or a flow’s private FlowLocal.
SessionError: Errors from session-level operations (distinct from VM RuntimeErrors, which are wrapped).
SnapshotStatus: Session execution status, serde-friendly.
SpeculationStep: Outcome of a single Speculation::advance call.
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.
SESSION_JOURNAL_CAP: Upper bound on journal events (unbounded-growth guard, mirroring RECORDING_CAP). Beyond it, appends are dropped and SessionJournal::truncated is set — the journal degrades honestly and restore falls back to the embedded checkpoint.
SESSION_JOURNAL_VERSION: Current SessionJournal format version.

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.
commit: Fold a forked child’s own-layer overrides back into its parent’s, making the child’s writes visible through parent (and, transitively, anything parent itself chains to or is later written through).
diff: Pure diff of two snapshots. a is “before”, b is “after”.
link: Link a StoryData into an executable Program.
load_state: Reconcile a SaveState into a flow’s context, returning a LoadReport of anything that couldn’t be applied. Globals are matched by name; visit/turn counts by id. Tolerant of story patches: unknown globals are reported, scopes the program no longer has retain their saved counts harmlessly in the live context. Note one deliberate change from the pre-F6.1b Story methods: such stale entries are not re-emitted by a subsequent save_state (which enumerates the current program’s containers, not the live maps) — ghost counts from older program versions no longer round-trip through saves indefinitely.
save_state: Capture a flow’s game state as a durable, name-keyed SaveState. Does not capture execution position — see the module docs.

Crate brink_runtime

Crate brink_runtime Copy item path

Re-exports§

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Crate brink_runtime