Crate bevy_brink

Expand description

Bevy integration for brink ink stories.

This crate exposes the brink runtime as a Bevy plugin: story programs are loaded as Assets, flow state lives on Components, story-wide globals live in Resources. All types are parameterized over a ZST marker so multiple independent story instances can coexist in one app.

Most games will use the default () marker and just do:

app.add_plugins(BrinkPlugin::<()>::default());

Games with multiple concurrent story instances declare marker types and register a plugin per marker:

struct MainStory;
struct DreamSequence;

app.add_plugins((
    BrinkPlugin::<MainStory>::default(),
    BrinkPlugin::<DreamSequence>::default(),
));

Re-exports§

pub use brink_runtime as runtime;

Structs§

BlockId: The runtime types that appear in bevy-brink’s own public signatures, re-exported so consumers can name them without depending on brink-runtime: FlowInstance, Program, Choice, Step’s return, RuntimeError’s error, FallbackHandler for the “no bindings” advance path, the scoped story-state types a host needs to build a policy and a per-step routing view (see docs/scoped-flow-state-spec.md): WorldPolicy, Scope, PolicyError, and ContextView (usually built via flow_context_view instead of by hand) — and the per-entity durability types produced/consumed by BrinkGlobals::save_state/load_state and save_flow_state/load_flow_state (F6.3, see the globals module’s “Save/load” docs): SaveState and LoadReport.
BrinkAssetsPlugin: Registers asset types and loaders that are shared across all markers.
BrinkAwaiting: Marker inserted on a flow while it awaits a bind_brink_async external.
BrinkBaseLocale: A flow’s canonical base line tables (the .inkb’s #line_tables).
BrinkBatchReport: Diagnostic record of the most recent advance_batch turn under marker M — the access bookkeeping (BH-1 wiring) plus phase counts the scenario harness (BH-B) and tests read. Overwritten each batch turn.
BrinkBindings: Registry of synchronous ink→engine bindings for story marker M.
BrinkCallBatchRequest: A pending deferred batch engine→ink call. Spawned on its own entity by brink_call_batch; consumed by resolve_brink_call_batches.
BrinkCallBatchResolved: Fired (targeted at the per-call entity) when a deferred batch call finishes. One entry per queued call, in call order — a failing call yields Err in its own slot rather than aborting the batch, matching call_ink_functions’s no-short-circuit contract. React with .observe(|on: On<BrinkCallBatchResolved>| …) on the brink_call_batch return value.
BrinkCallFailed: Fired (targeted at the per-call entity) when a deferred call fails (unknown function, unbound world query, runtime error, …).
BrinkCallRequest: A pending deferred engine→ink call. Spawned on its own entity by brink_call; consumed by resolve_brink_calls.
BrinkCallResolved: Fired (targeted at the per-call entity) when a deferred call succeeds. React with .observe(|on: On<BrinkCallResolved>| …) on the brink_call return value.
BrinkChoicesPresented: Fired when a flow reaches a Step::Choices — pick one via BrinkFlow::choose (or choose_recording in dev builds for replay-after-hot-reload).
BrinkConfigWarnings: The formatted rejection messages from validating a with_config override’s [lints] table, if any were rejected.
BrinkContext: A single flow’s private override layer over the shared BrinkGlobals<M> World.
BrinkCurrentLocale: The active locale for story marker M. None = base/source language.
BrinkDeadHandleDeref: Fired (opt-in — see HandleRegistry::get_or_dead) when a binding dereferences a dead handle. Telemetry only: the binding itself still returns whatever declared failure value it chooses; this event doesn’t change that value, it just lets a host observe the miss.
BrinkExecMode: The host-selected ExecMode every flow of marker M starts in (F35, ruled 2026-07-19).
BrinkExternalAwaited: Fired (once, targeted at the flow entity) when a flow parks on a bind_brink_async external.
BrinkFlow: A single live ink flow, attached to an entity. Holds the VM’s per-flow state: call stacks, output buffer, pending choices, and the accumulated transcript.
BrinkFlowRequest: Marker component requesting that this entity become a flow once its story assets are available.
BrinkFlowReset: Fired by the plugin’s reload-replay system before it starts rebuilding a flow against a freshly-reloaded program.
BrinkGlobals: The single shared World for a story identified by marker M.
BrinkHandler: An ExternalFnHandler backed by a BrinkBindings registry.
BrinkLineDelivered: Fired when a flow produces a Step::Line — mid-stream content; more may follow on subsequent steps. Typewriter-style UIs accumulate; click-to-continue UIs concatenate until a terminal event arrives.
BrinkLocale: The active locale for a flow — a handle to the LineTablesAsset whose strings and slot templates render this flow’s output.
BrinkLocaleChanged: Fired when the global locale changes; reconciles all flows.
BrinkLocaleOverride: Marker: a flow carrying this is excluded from global locale reconcile. Drive its BrinkLocale manually (e.g. a polyglot NPC) via apply_locale_overlay.
BrinkPendingTask: A detached Task computing a bind_brink_task external’s value, parked on the flow entity.
BrinkPlugin: A Bevy plugin that registers brink story types, messages, and asset loaders for a single story instance identified by the marker type M.
BrinkProgram: Component holding the Handle<ProgramAsset> a BrinkFlow<M> executes against.
BrinkReplayConfig: Global default ReplayMode for hot-reload replay (the shared brink_runtime primitive). Override on a specific flow with ReplayQueryModeOverride.
BrinkReplayLog: Per-flow log used to reconstruct the flow on hot-reload.
BrinkStory: Bundle that pairs a flow’s BrinkProgram (program handle) with its BrinkLocale (line-tables handle).
BrinkStoryAsset: Top-level “story” asset — a thin bundle pairing the two labeled subassets (ProgramAsset, LineTablesAsset) that together describe a loaded story.
BrinkStoryEnded: Fired when a flow reaches Step::End — the story has permanently ended (the ink -> END instruction). No more advance is meaningful.
BrinkTranscript: Cached, locale-resolved view of a flow’s transcript.
BrinkTurnDone: Fired when a flow reaches Step::Done — this turn’s output is complete (the ink -> DONE instruction). The story is not over; call advance again for the next turn.
BrinkWorld: brink_runtime::World — the single story-state layer shared by every flow under a marker, carried by BrinkGlobals. Aliased to avoid the glob-import collision with bevy::prelude::World (the ECS world): use bevy::prelude::*; use bevy_brink::*; would make a bare World ambiguous. Name story state BrinkWorld and the ECS world World. Shared game state that lives above individual flows.
BrinkWorldDelta: The per-marker changed-cell ledger: batch Apply records into it, the wake pass drains it. See the module docs for the attribution contract.
BrinkWorldPolicy: Host-supplied WorldPolicy for marker M’s shared BrinkGlobals World, installed once at plugin setup via BrinkPlugin::with_policy and read by fulfill_flow_requests when it creates BrinkGlobals<M> on first fulfillment.
BrktLoader: Asset loader for .brkt (serialized transcript) files. Decodes via brink_runtime::transcript::read_transcript.
CapabilityChanges: Per-frame, per-capability change verdict — the §12.5 hook BH-4’s Detect phase (crate::sleep::mark_wake_dirty) consumes so a component-backed detect-capable wake condition gets the cheap re-evaluate-on-change path without the missed-wake class.
CapabilityEffects: The effects object on a manifest external (docs/effects-spec.md §13.2): {"reads": [...], "writes": [...], "detect": {...}}. Every field is optional (defaults empty) — an external with no effects key at all touches no ECS capability.
CapabilityManifest: The top-level manifest shape: {"externals": [...]}. Register one as a Resource (app.insert_resource(CapabilityManifest::from_json(json)?)) before or after adding crate::BrinkPlugin — order doesn’t matter, BrinkPlugin only init_resources an empty default if none is present yet.
CapabilityManifestExternal: One external’s manifest entry, restricted to the fields BH-1 needs. Deserialized from the same JSON manifest file docs/host-capability-manifest.md/brink_ir::host_manifest describes for the compiler/IDE side (name, params, kind, doc, widgets, path, …) — this type only names name and effects; every other key present in a real manifest file is ignored by serde’s default “unknown fields are fine” behavior, so the same file serves both consumers.
CapabilityRegistry: App-level registry mapping capability names to ComponentIds, keyed by marker M (mirrors HandleKinds<M>). Populated via BrinkCapabilityAppExt::register_capability. BTreeMap for deterministic iteration (CLAUDE.md determinism rule).
CapabilityTable: Per-story table of joined ContainerAccess, keyed by the loaded ProgramAsset’s AssetId (a bevy-brink app may have several stories loaded — under one marker or several — at once). Rebuilt by rebuild_capability_table at the story load/unload boundary (§12.5’s ruled invariant — “story load/unload is when the params rebuild”).
Choice: The runtime types that appear in bevy-brink’s own public signatures, re-exported so consumers can name them without depending on brink-runtime: FlowInstance, Program, Choice, Step’s return, RuntimeError’s error, FallbackHandler for the “no bindings” advance path, the scoped story-state types a host needs to build a policy and a per-step routing view (see docs/scoped-flow-state-spec.md): WorldPolicy, Scope, PolicyError, and ContextView (usually built via flow_context_view instead of by hand) — and the per-entity durability types produced/consumed by BrinkGlobals::save_state/load_state and save_flow_state/load_flow_state (F6.3, see the globals module’s “Save/load” docs): SaveState and LoadReport.
ContainerAccess: One container’s (knot/stitch’s) joined ECS access — the output of folding an EffectRowEntry through the CapabilityManifest and CapabilityRegistry (docs/effects-spec.md §9).
ContextView: The runtime types that appear in bevy-brink’s own public signatures, re-exported so consumers can name them without depending on brink-runtime: FlowInstance, Program, Choice, Step’s return, RuntimeError’s error, FallbackHandler for the “no bindings” advance path, the scoped story-state types a host needs to build a policy and a per-step routing view (see docs/scoped-flow-state-spec.md): WorldPolicy, Scope, PolicyError, and ContextView (usually built via flow_context_view instead of by hand) — and the per-entity durability types produced/consumed by BrinkGlobals::save_state/load_state and save_flow_state/load_flow_state (F6.3, see the globals module’s “Save/load” docs): SaveState and LoadReport.
DetectSummary: The distilled detect-bit verdict for a policy’s condition dependency set (#913, ruled 2026-07-18). Built from the per-container AND-merged ContainerAccess::detect map, or supplied directly by a host that knows its condition’s dependencies.
FallbackHandler: The runtime types that appear in bevy-brink’s own public signatures, re-exported so consumers can name them without depending on brink-runtime: FlowInstance, Program, Choice, Step’s return, RuntimeError’s error, FallbackHandler for the “no bindings” advance path, the scoped story-state types a host needs to build a policy and a per-step routing view (see docs/scoped-flow-state-spec.md): WorldPolicy, Scope, PolicyError, and ContextView (usually built via flow_context_view instead of by hand) — and the per-entity durability types produced/consumed by BrinkGlobals::save_state/load_state and save_flow_state/load_flow_state (F6.3, see the globals module’s “Save/load” docs): SaveState and LoadReport.
FlowAccessRecord: Per-flow record of a batch turn: which flow, its story, and the aggregate container Access BH-1 computed for that story. Recorded by advance_batch into BrinkBatchReport.
FlowInstance: The runtime types that appear in bevy-brink’s own public signatures, re-exported so consumers can name them without depending on brink-runtime: FlowInstance, Program, Choice, Step’s return, RuntimeError’s error, FallbackHandler for the “no bindings” advance path, the scoped story-state types a host needs to build a policy and a per-step routing view (see docs/scoped-flow-state-spec.md): WorldPolicy, Scope, PolicyError, and ContextView (usually built via flow_context_view instead of by hand) — and the per-entity durability types produced/consumed by BrinkGlobals::save_state/load_state and save_flow_state/load_flow_state (F6.3, see the globals module’s “Save/load” docs): SaveState and LoadReport.
FlowLocal: The runtime types that appear in bevy-brink’s own public signatures, re-exported so consumers can name them without depending on brink-runtime: FlowInstance, Program, Choice, Step’s return, RuntimeError’s error, FallbackHandler for the “no bindings” advance path, the scoped story-state types a host needs to build a policy and a per-step routing view (see docs/scoped-flow-state-spec.md): WorldPolicy, Scope, PolicyError, and ContextView (usually built via flow_context_view instead of by hand) — and the per-entity durability types produced/consumed by BrinkGlobals::save_state/load_state and save_flow_state/load_flow_state (F6.3, see the globals module’s “Save/load” docs): SaveState and LoadReport.
FlowSleep: A standing reactive-wake policy on a flow entity (docs/effects-spec.md §13.1). Attach it to a fulfilled flow entity; the plugin’s wake systems do the rest. See the module docs for the full contract.
GroundTruthLog: Log of every query-binding dispatch observed so far under marker M. Populated by [record] (called from bindings.rs’s dispatch_one_external); drained/inspected by check. A Resource like CapabilityTable<M>, so a host/test/scenario-harness driving several batch turns accumulates one log across all of them — call GroundTruthLog::reset between comparisons that should be independent (exactly like brink_runtime::effect_trace::reset).
HandleEntityRemap: An EntityMapper a Resource = Entity HandleKind’s resolve can consult (world.resource::<HandleEntityRemap>()) and populate (set_mapped) when reconstructing scene-based entities whose cross-references named another handle-entity by its old session’s Entity id. Reset at the start of every load_handles call.
HandleKinds: Type-erased index over every kind registered via BrinkHandleAppExt::register_handle_kind for marker M. BTreeMap keyed by HandleKind::KIND for deterministic iteration.
HandleRegistry: Per-kind token registry: opaque u64 id allocation plus live-resource storage. A Resource, inserted by register_handle_kind.
HandleRetentionMetrics
HandleSaveEntry: One (id, SaveKey) entry, SaveKey erased to JSON so heterogeneous kinds can share one persisted table (HandleSaveState).
HandleSaveState: The token→SaveKey table, persisted beside the ink SaveState (spec §4: “bevy-brink owns opaque token ids and the per-kind registries, persists the token → SaveKey table beside the ink SaveState”). Keyed by HandleKind::KIND; BTreeMap/sorted-by-id Vec for deterministic serialization.
InkLoader: Asset loader for .ink (source) files.
InkbLoader: Asset loader for .inkb (compiled bytecode) files.
InklLoader: Asset loader for .inkl (compiled locale overlay) files. Decodes via brink_format::read_inkl into a LocaleAsset.
KindRetention: Per-kind live/GC counters, updated by gc_on_turn_done. A diagnostics feature, not a semantic (spec §8: “the dev-build snapshot-retention metric rides the bevy-brink slice as a diagnostics feature”).
LineTablesAsset: The localized line-table portion of a compiled story — the swappable rendering data.
LoadReport: The runtime types that appear in bevy-brink’s own public signatures, re-exported so consumers can name them without depending on brink-runtime: FlowInstance, Program, Choice, Step’s return, RuntimeError’s error, FallbackHandler for the “no bindings” advance path, the scoped story-state types a host needs to build a policy and a per-step routing view (see docs/scoped-flow-state-spec.md): WorldPolicy, Scope, PolicyError, and ContextView (usually built via flow_context_view instead of by hand) — and the per-entity durability types produced/consumed by BrinkGlobals::save_state/load_state and save_flow_state/load_flow_state (F6.3, see the globals module’s “Save/load” docs): SaveState and LoadReport.
LocaleAsset: A parsed .inkl locale overlay. Apply it to a story’s base line tables with apply_locale_overlay (or let the global locale machinery do it).
LocalizedTablesCache: Caches localized line tables per (base, locale) so all flows in a locale share one LineTablesAsset rather than rebuilding it per flow.
ObservedAccess: One real bind_brink_query dispatch, observed at the exact point bevy actually ran it. The runtime counterpart of brink_runtime::effect_trace::ObservedRow — this module never constructs an opaque/approximate access; every entry is the concrete Access bevy’s own System::initialize reported for the bound system.
OutputLine: The runtime types that appear in bevy-brink’s own public signatures, re-exported so consumers can name them without depending on brink-runtime: FlowInstance, Program, Choice, Step’s return, RuntimeError’s error, FallbackHandler for the “no bindings” advance path, the scoped story-state types a host needs to build a policy and a per-step routing view (see docs/scoped-flow-state-spec.md): WorldPolicy, Scope, PolicyError, and ContextView (usually built via flow_context_view instead of by hand) — and the per-entity durability types produced/consumed by BrinkGlobals::save_state/load_state and save_flow_state/load_flow_state (F6.3, see the globals module’s “Save/load” docs): SaveState and LoadReport.
Program: The runtime types that appear in bevy-brink’s own public signatures, re-exported so consumers can name them without depending on brink-runtime: FlowInstance, Program, Choice, Step’s return, RuntimeError’s error, FallbackHandler for the “no bindings” advance path, the scoped story-state types a host needs to build a policy and a per-step routing view (see docs/scoped-flow-state-spec.md): WorldPolicy, Scope, PolicyError, and ContextView (usually built via flow_context_view instead of by hand) — and the per-entity durability types produced/consumed by BrinkGlobals::save_state/load_state and save_flow_state/load_flow_state (F6.3, see the globals module’s “Save/load” docs): SaveState and LoadReport.
ProgramAsset: The immutable bytecode portion of a compiled story — what the VM actually executes — together with the fresh starting World (globals seeded from VAR/CONST/LIST defaults; zero visit and turn counts, all-World policy).
RehydrationReport: Load-time outcome for every handle token referenced by the ink state being loaded, bucketed per spec §4.
ReplayQueryModeOverride: Per-flow override of the global BrinkReplayConfig replay mode. Insert on a flow entity to make that flow replay with a specific ReplayMode.
SaveState: The runtime types that appear in bevy-brink’s own public signatures, re-exported so consumers can name them without depending on brink-runtime: FlowInstance, Program, Choice, Step’s return, RuntimeError’s error, FallbackHandler for the “no bindings” advance path, the scoped story-state types a host needs to build a policy and a per-step routing view (see docs/scoped-flow-state-spec.md): WorldPolicy, Scope, PolicyError, and ContextView (usually built via flow_context_view instead of by hand) — and the per-entity durability types produced/consumed by BrinkGlobals::save_state/load_state and save_flow_state/load_flow_state (F6.3, see the globals module’s “Save/load” docs): SaveState and LoadReport.
TranscriptAsset: A loaded .brkt transcript — the output history of a (past) playthrough, re-renderable against any matching program + locale.
TranscriptData: Re-exported so consumers can name the decoded-transcript type and its error without depending on brink-runtime directly. A decoded transcript: the output parts, the source program’s checksum (to verify compatibility before rendering), and the captured fragments (for re-rendering choice display text and computed substrings).
Violation: One under-report: a real bind_brink_query dispatch touched a component its story’s capability manifest never declares — the exact class this issue guards (names the flow, the component, and the binding).
WorldDelta: The set of shared-World cells written over one accounting window — the changed-set mark_wake_dirty intersects each wake condition’s read row against.
WorldPolicy: The runtime types that appear in bevy-brink’s own public signatures, re-exported so consumers can name them without depending on brink-runtime: FlowInstance, Program, Choice, Step’s return, RuntimeError’s error, FallbackHandler for the “no bindings” advance path, the scoped story-state types a host needs to build a policy and a per-step routing view (see docs/scoped-flow-state-spec.md): WorldPolicy, Scope, PolicyError, and ContextView (usually built via flow_context_view instead of by hand) — and the per-entity durability types produced/consumed by BrinkGlobals::save_state/load_state and save_flow_state/load_flow_state (F6.3, see the globals module’s “Save/load” docs): SaveState and LoadReport.

Enums§

AccessKind: Whether a violating access was a read or a write — named in Violation so a report can say exactly which.
Advance: Result of advancing a flow one step via BrinkFlow::step_one.
BrinkArgError: Error produced when ink arguments can’t be parsed into a binding’s expected shape. Returned by BrinkCommand::from_ink_args.
BrinkCallError: Errors from an engine→ink call (call_ink_function).
BrktLoaderError: Errors that can occur loading a .brkt file.
CapabilityError: Errors from manifest parsing or the row join.
CompileStoryInlineError: Errors from compile_story_inline.
ExecMode: The runtime types that appear in bevy-brink’s own public signatures, re-exported so consumers can name them without depending on brink-runtime: FlowInstance, Program, Choice, Step’s return, RuntimeError’s error, FallbackHandler for the “no bindings” advance path, the scoped story-state types a host needs to build a policy and a per-step routing view (see docs/scoped-flow-state-spec.md): WorldPolicy, Scope, PolicyError, and ContextView (usually built via flow_context_view instead of by hand) — and the per-entity durability types produced/consumed by BrinkGlobals::save_state/load_state and save_flow_state/load_flow_state (F6.3, see the globals module’s “Save/load” docs): SaveState and LoadReport.
FlowStart: Where a freshly-spawned flow should begin executing.
HandleLoadError: load_handles failure — only reachable under RehydrationPolicy::StrictKinds.
InkLoaderError: Errors that can occur loading an .ink source file.
InkbLoaderError: Errors that can occur loading an .inkb file.
InklLoaderError: Errors that can occur loading an .inkl file.
LocaleMode: Re-exported so consumers can choose Overlay/Strict application without a direct brink-runtime dependency. Controls how missing scopes are handled when applying a locale overlay.
PolicyError: The runtime types that appear in bevy-brink’s own public signatures, re-exported so consumers can name them without depending on brink-runtime: FlowInstance, Program, Choice, Step’s return, RuntimeError’s error, FallbackHandler for the “no bindings” advance path, the scoped story-state types a host needs to build a policy and a per-step routing view (see docs/scoped-flow-state-spec.md): WorldPolicy, Scope, PolicyError, and ContextView (usually built via flow_context_view instead of by hand) — and the per-entity durability types produced/consumed by BrinkGlobals::save_state/load_state and save_flow_state/load_flow_state (F6.3, see the globals module’s “Save/load” docs): SaveState and LoadReport.
RehydrationPolicy: Host policy for handling a token whose kind isn’t currently registered at load time (spec §4). Lenient is the production default — unregistered kinds are just reported, never-fail-load holds. StrictKinds is the dev/CI knob: an unregistered kind fails the load loudly (a registration drifted out of sync with a save file, which is a bug worth surfacing immediately rather than silently dropping state).
RuntimeError: The runtime types that appear in bevy-brink’s own public signatures, re-exported so consumers can name them without depending on brink-runtime: FlowInstance, Program, Choice, Step’s return, RuntimeError’s error, FallbackHandler for the “no bindings” advance path, the scoped story-state types a host needs to build a policy and a per-step routing view (see docs/scoped-flow-state-spec.md): WorldPolicy, Scope, PolicyError, and ContextView (usually built via flow_context_view instead of by hand) — and the per-entity durability types produced/consumed by BrinkGlobals::save_state/load_state and save_flow_state/load_flow_state (F6.3, see the globals module’s “Save/load” docs): SaveState and LoadReport.
Scope: The runtime types that appear in bevy-brink’s own public signatures, re-exported so consumers can name them without depending on brink-runtime: FlowInstance, Program, Choice, Step’s return, RuntimeError’s error, FallbackHandler for the “no bindings” advance path, the scoped story-state types a host needs to build a policy and a per-step routing view (see docs/scoped-flow-state-spec.md): WorldPolicy, Scope, PolicyError, and ContextView (usually built via flow_context_view instead of by hand) — and the per-entity durability types produced/consumed by BrinkGlobals::save_state/load_state and save_flow_state/load_flow_state (F6.3, see the globals module’s “Save/load” docs): SaveState and LoadReport.
SleepState: The lifecycle state of a FlowSleep policy — inspector-visible, and the single field FlowSleep::wants_collect reads to tell Collect whether the flow steps this turn.
Step: The runtime types that appear in bevy-brink’s own public signatures, re-exported so consumers can name them without depending on brink-runtime: FlowInstance, Program, Choice, Step’s return, RuntimeError’s error, FallbackHandler for the “no bindings” advance path, the scoped story-state types a host needs to build a policy and a per-step routing view (see docs/scoped-flow-state-spec.md): WorldPolicy, Scope, PolicyError, and ContextView (usually built via flow_context_view instead of by hand) — and the per-entity durability types produced/consumed by BrinkGlobals::save_state/load_state and save_flow_state/load_flow_state (F6.3, see the globals module’s “Save/load” docs): SaveState and LoadReport.
TranscriptError: Re-exported so consumers can name the decoded-transcript type and its error without depending on brink-runtime directly. Errors from transcript serialization/deserialization.
Value: Re-exported so #[derive(BrinkCommand)]-generated code (and binding authors) can name the ink runtime value type without depending on brink-format directly. A runtime value in the ink VM.
WakeArming: When a woken flow re-parks, does its policy re-arm or retire?
WakeConditionPurityError: A wake condition failed the attach-time purity check. See the module section above for the contract this enforces.

Traits§

BrinkBindingsAppExt: App-extension verbs for registering synchronous ink→engine bindings.
BrinkCallCommandsExt: Commands extension for requesting a deferred engine→ink call.
BrinkCapabilityAppExt: App-builder extension for registering capability names.
BrinkCommand: A Bevy Event that can be built from an ink external call’s arguments, for use with bind_brink_command.
BrinkHandleAppExt: App-builder extension for registering HandleKind implementors.
BrinkResolveExternalExt: Commands extension to resolve a flow’s awaited async external.
HandleKind: Per-kind rehydration contract: save-side keying (live resource → durable SaveKey) and load-side resolution (SaveKey → new resource). Verbatim from docs/t1d-spec.md §4 (2026-07-14 mechanics ruling).
IntoBrinkArgs: Converts call-site arguments into the ink argument vector. Implemented for (), tuples of Into<Value> (up to 4), Vec<Value>, and &[Value] — so both (in_combat, 3) and an explicit &[..] work.
SetBrinkLocale: Commands extension to switch the global locale.

Functions§

advance_batch: Batch-mode flow driver (§12.4; BH-2): advance every pending flow under marker M as one batch turn with frame-start read pinning, per-flow buffered writes/commands, and a deterministic flow-id-ordered Apply.
advance_batch_parallel: Parallel batch-mode flow driver (§12.2–§12.4; BH-3): identical semantics to advance_batch, but the Step phase runs on ComputeTaskPool with each flow’s FlowInstance accessed through an [UnsafeWorldCell] (bevy’s own executor pattern). Per-flow Step ([super::step_one]) and the flow-id-ordered Apply ([super::apply_batch_writes]) are literally the same functions shared with the serial driver; Collect is a hand-duplicated query kept filter-identical by hand (see the module docs above). Together these keep the two drivers byte-identical (the determinism law).
advance_flow: Advance a flow by one line from an exclusive (&mut World) context, resolving any world-access query bindings inline via run_system_with.
any_flow_awaiting_external: Run condition: true if any BrinkFlow<M> is paused on a pending external (so the resolver only runs when there’s work).
apply_locale_overlay: Apply a locale overlay to a story’s base line tables, inserting the resulting localized LineTablesAsset and returning its handle.
call_ink_function: Synchronously evaluate an ink function on a flow entity from an exclusive (&mut World) context, returning its value.
call_ink_function_value: Synchronously invoke an ink function value (#fn(…) — a FnRef or Closure) on a flow entity from an exclusive (&mut World) context, returning its value — the host callback-invocation surface (T1c-3, docs/t1c-spec.md §6).
call_ink_functions: Apply a batch of engine→ink calls to one flow in a single VM-eval setup, returning one Result per call in the order supplied.
capture_transcript: Serialize a flow’s current transcript to .brkt bytes for saving.
catch_up_loaded_locales: Plugin system: when the current locale’s .inkl finishes loading (or is hot-reloaded) after a switch/spawn, reconcile so flows pick it up. Reads asset events; no-ops when nothing relevant loaded.
check: The ground-truth check itself: for every dispatch [record]ed into log, assert its real bevy Access is a subset of the story’s BH-1 row-join access (CapabilityTable::access_for, aggregated across containers via [aggregate_access] — the same aggregate BH-2/BH-3 already consume for their own bookkeeping, since v1 has no per-container narrowing on the host side either, docs/effects-spec.md §7). A story with no capability table loaded at all (no manifest/registry wired) joins to an empty Access — any real component touch is then correctly a violation, since nothing was declared.
check_named_condition_purity: Check purity for a named wake condition (FlowSleep::condition’s shape) — resolves condition to a DefinitionId via Program::definition_id_for_path, then inspects its EffectRows row.
check_value_condition_purity: Check purity for a dynamic fn-value wake condition — a Value (FnRef/Closure) resolved token rather than a static name, e.g. one a host obtained from a global or a bind_brink_query result. Resolves the value’s target via Value::fn_target, then inspects the same EffectRows row check_named_condition_purity does.
compile_story_inline: Compile an in-memory ink source string straight into story assets, inserting them into app’s asset collections and returning the resulting Handle<BrinkStoryAsset> (G3, issue #1060).
compute_container_access: The row join (docs/effects-spec.md §9): compute every container’s ContainerAccess from a story’s decoded EffectRows table (T2-3/PR #878), joined against manifest and registry.
detect_capability_changes: Typed change-tracker for one registered capability component C (§12.5, #996). Wired into Update by BrinkCapabilityAppExt::register_capability, one per distinct component, ordered before mark_wake_dirty.
digit_key_to_choice_index: If a Digit1..=Digit9 key was just pressed and the corresponding 0-based index is within 0..max, return that index. Otherwise return None.
dump_container_access: Render a human-readable container -> access set table (BH-B’s scenario harness + interactive debugging, per this issue’s “dev-visible dump” deliverable). Deterministic: the input is keyed by DefinitionId (BTreeMap order) and each container’s name lists are pre-sorted.
flow_context_view: Build the ContextView routing view for one flow’s step: World-scoped units go straight to the shared globals; Local-scoped units read through / write to ctx’s own override layer (see docs/scoped-flow-state-spec.md).
fulfill_flow_requests: Plugin-managed system: walk pending BrinkFlowRequest<M> entities, fulfill each whose assets are ready, and bootstrap the entity’s per-flow components.
gc_on_turn_done: Observer: at every -> DONE (spec §4’s quiescent sweep point), computes the currently-reachable handle-token set — every token in the shared World’s globals plus every flow’s own local state, script state being fully enumerable (value-model §6 license) — and drops every registered kind’s unreachable entries. No script-side destructors exist or are needed.
is_valid_system: The is_valid(h) binding body — ships as a standard bind_brink_query binding (not a language intrinsic, per spec §4). Registered automatically by BrinkPlugin under the name "is_valid".
load_flow_state: Reconcile a SaveState into one flow, routed by scope — see the module docs’ “Save/load” section.
load_handles: Rehydrate every handle token referenced (the SaveState about to be loaded — BrinkGlobals’s or one flow’s) against persisted (the companion HandleSaveState loaded alongside it), keeping token ids stable (spec §4: “rebinds registries at load keeping token ids stable — ink state is untouched; only the registry’s right-hand side rebinds”).
mark_wake_dirty: Ordinary (non-exclusive) system: flag which parked policies need their condition re-evaluated this frame, consuming the #913 detect verdict and the change signals it can observe.
on_locale_changed: Observer (registered by the plugin) that reconciles every non-override flow’s locale when BrinkLocaleChanged fires.
poll_brink_tasks: Plugin system: poll detached bind_brink_task futures; when one finishes, resolve its flow’s pending external with the value and drop the BrinkPendingTask. Polling is non-blocking (poll_once). The plugin gates this on any_with_component::<BrinkPendingTask<M>>.
rebuild_capability_table: Plugin-managed system: rebuild a loaded story’s ContainerAccess table whenever its ProgramAsset (re)loads, and drop it when the asset unloads — the load/unload boundary §12.5 rules access sets rebuild at.
refresh_transcripts: Plugin-managed system: re-render BrinkTranscript<M> for any flow entity whose transcript has grown, whose locale handle changed, or whose locale’s LineTablesAsset content was hot-reloaded.
render_transcript_asset: Re-render a loaded transcript against a program + locale line tables, producing (text, tags) per line — the same output the live BrinkTranscript would show.
replay_on_reload: Plugin-managed system: when ProgramAsset reloads (file watcher saw a change), rebuild each tracked flow against the new bytecode and replay any recorded choices to restore approximate position.
resolve_brink_call_batches: Exclusive system (registered by the plugin) that resolves pending BrinkCallBatchRequest<M>s: evaluates each queued batch through call_ink_functions — one SystemState setup per batch, calls running front-to-back — fires BrinkCallBatchResolved at the batch entity with the full per-call result Vec, and despawns it.
resolve_brink_calls: Exclusive system (registered by the plugin) that resolves pending BrinkCallRequest<M>s: evaluates each function via call_ink_function, fires BrinkCallResolved / BrinkCallFailed at the call entity, and despawns it.
resolve_pending_externals: Exclusive plugin system: service flows that paused on a pending external during normal playback (after a non-exclusive step_one yielded Advance::AwaitingQuery).
run_flow_sleep: Exclusive system: re-evaluate flagged wake conditions in each flow’s own context, wake on true, and re-arm/remove policies at turn boundaries (docs/effects-spec.md §13.1). Gated by the plugin on any_with_component::<FlowSleep<M>>, so it does no work when no flow sleeps.
save_flow_state: Capture one flow’s effective durable game state as a SaveState — see the module docs’ “Save/load” section.
save_handles: Snapshot every registered kind’s live tokens as a HandleSaveState, to be persisted alongside a SaveState (e.g. BrinkGlobals::save_state).

Type Aliases§

BrinkQueryInput: Input type for a world-access (bind_brink_query) binding system: the flow entity that triggered the call, plus the ink arguments.
ContainerAccessTable: A story’s full joined access table: every container’s (knot/stitch’s) DefinitionId mapped to its ContainerAccess.

Derive Macros§

BrinkCommand: #[derive(BrinkCommand)] — generates BrinkCommand::from_ink_args. Shares its name with the trait (macro vs. type namespace), so a single use bevy_brink::BrinkCommand; brings both into scope. Derive BrinkCommand for a struct of supported scalar fields. See the crate docs for the field-type mapping and limitations.

Crate bevy_brink

Crate bevy_brink Copy item path

Re-exports§

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Derive Macros§

Crate bevy_brink