bevy-brink 0.0.17

//! Bevy integration for brink ink stories.
//!
//! This crate exposes the brink runtime as a Bevy plugin: story programs
//! are loaded as `Asset`s, flow state lives on `Component`s, story-wide
//! globals live in `Resource`s. 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:
//!
//! ```no_run
//! # use bevy_app::App;
//! # use bevy_brink::BrinkPlugin;
//! # let mut app = App::new();
//! app.add_plugins(BrinkPlugin::<()>::default());
//! ```
//!
//! Games with multiple concurrent story instances declare marker types
//! and register a plugin per marker:
//!
//! ```no_run
//! # use bevy_app::App;
//! # use bevy_brink::BrinkPlugin;
//! # let mut app = App::new();
//! struct MainStory;
//! struct DreamSequence;
//!
//! app.add_plugins((
//!     BrinkPlugin::<MainStory>::default(),
//!     BrinkPlugin::<DreamSequence>::default(),
//! ));
//! ```

// Lets `#[derive(BrinkCommand)]`-generated code reference `::bevy_brink`
// from within this crate itself (the same trick serde/bevy use for their
// own derives).
extern crate self as bevy_brink;

mod asset;
mod async_bind;
mod batch;
mod bindings;
mod brkt;
mod call;
mod capability;
#[cfg(feature = "dev")]
mod config_warnings;
mod event;
mod flow;
mod globals;
#[cfg(feature = "effect-trace")]
mod ground_truth;
mod handle;
mod input;
mod line_tables;
mod locale;
mod plugin;
#[cfg(feature = "dev")]
mod replay;
mod request;
mod sleep;
#[cfg(feature = "dev")]
mod source_loader;
#[cfg(test)]
mod test_support;
mod transcript;
mod wake_delta;

pub use asset::{
    BrinkProgram, BrinkStory, BrinkStoryAsset, InkbLoader, InkbLoaderError, LineTablesAsset,
    ProgramAsset,
};
pub use async_bind::{
    BrinkAwaiting, BrinkExternalAwaited, BrinkPendingTask, BrinkResolveExternalExt,
    poll_brink_tasks,
};
pub use batch::parallel::advance_batch_parallel;
pub use batch::{BrinkBatchReport, FlowAccessRecord, advance_batch};
/// `#[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.
pub use bevy_brink_derive::BrinkCommand;
pub use bindings::{
    BrinkArgError, BrinkBindings, BrinkBindingsAppExt, BrinkCallError, BrinkCommand, BrinkHandler,
    BrinkQueryInput, advance_flow, any_flow_awaiting_external, call_ink_function,
    call_ink_function_value, call_ink_functions, resolve_pending_externals,
};
/// Re-exported so `#[derive(BrinkCommand)]`-generated code (and binding
/// authors) can name the ink runtime value type without depending on
/// `brink-format` directly.
pub use brink_format::Value;
/// The whole runtime crate, re-exported as an escape hatch: any `brink_runtime`
/// type that surfaces in a `bevy-brink` API but isn't individually re-exported
/// below is reachable as `bevy_brink::runtime::…` — so a consumer never needs a
/// direct `brink-runtime` Cargo dependency to name one.
pub use brink_runtime as runtime;
/// Re-exported so consumers can choose `Overlay`/`Strict` application without
/// a direct `brink-runtime` dependency.
pub use brink_runtime::LocaleMode;
/// `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`.
pub use brink_runtime::World as BrinkWorld;
/// Re-exported so consumers can name the decoded-transcript type and its
/// error without depending on `brink-runtime` directly.
pub use brink_runtime::transcript::{TranscriptData, TranscriptError};
/// 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`](BrinkFlow::inner), [`Program`](crate::ProgramAsset::program),
/// [`Choice`](crate::BrinkChoicesPresented::choices), [`Step`](advance_flow)'s
/// return, [`RuntimeError`](BrinkFlow::choose)'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`].
///
/// `World` is deliberately absent here — it collides with `bevy::prelude::World`
/// under a glob import, so it is re-exported under the alias [`BrinkWorld`].
pub use brink_runtime::{
    BlockId, Choice, ContextView, ExecMode, FallbackHandler, FlowInstance, FlowLocal, LoadReport,
    OutputLine, PolicyError, Program, RuntimeError, SaveState, Scope, Step, WorldPolicy,
};
pub use brkt::{
    BrktLoader, BrktLoaderError, TranscriptAsset, capture_transcript, render_transcript_asset,
};
pub use call::{
    BrinkCallBatchRequest, BrinkCallBatchResolved, BrinkCallCommandsExt, BrinkCallFailed,
    BrinkCallRequest, BrinkCallResolved, IntoBrinkArgs, resolve_brink_call_batches,
    resolve_brink_calls,
};
pub use capability::{
    BrinkCapabilityAppExt, CapabilityChanges, CapabilityEffects, CapabilityError,
    CapabilityManifest, CapabilityManifestExternal, CapabilityRegistry, CapabilityTable,
    ContainerAccess, ContainerAccessTable, compute_container_access, detect_capability_changes,
    dump_container_access, rebuild_capability_table,
};
#[cfg(feature = "dev")]
pub use config_warnings::BrinkConfigWarnings;
#[cfg(feature = "dev")]
pub use event::BrinkFlowReset;
pub use event::{BrinkChoicesPresented, BrinkLineDelivered, BrinkStoryEnded, BrinkTurnDone};
pub use flow::{Advance, BrinkFlow};
pub use globals::{
    BrinkContext, BrinkExecMode, BrinkGlobals, BrinkWorldPolicy, flow_context_view,
    load_flow_state, save_flow_state,
};
#[cfg(feature = "effect-trace")]
pub use ground_truth::{AccessKind, GroundTruthLog, ObservedAccess, Violation, check};
pub use handle::{
    BrinkDeadHandleDeref, BrinkHandleAppExt, HandleEntityRemap, HandleKind, HandleKinds,
    HandleLoadError, HandleRegistry, HandleRetentionMetrics, HandleSaveEntry, HandleSaveState,
    KindRetention, RehydrationPolicy, RehydrationReport, gc_on_turn_done, is_valid_system,
    load_handles, save_handles,
};
pub use input::digit_key_to_choice_index;
pub use line_tables::BrinkLocale;
pub use locale::{
    BrinkBaseLocale, BrinkCurrentLocale, BrinkLocaleChanged, BrinkLocaleOverride, InklLoader,
    InklLoaderError, LocaleAsset, LocalizedTablesCache, SetBrinkLocale, apply_locale_overlay,
    catch_up_loaded_locales, on_locale_changed,
};
pub use plugin::{BrinkAssetsPlugin, BrinkPlugin};
#[cfg(feature = "dev")]
pub use replay::{BrinkReplayConfig, BrinkReplayLog, ReplayQueryModeOverride, replay_on_reload};
pub use request::{BrinkFlowRequest, FlowStart, fulfill_flow_requests};
pub use sleep::{
    DetectSummary, FlowSleep, SleepState, WakeArming, WakeConditionPurityError,
    check_named_condition_purity, check_value_condition_purity, mark_wake_dirty, run_flow_sleep,
};
#[cfg(feature = "dev")]
pub use source_loader::{CompileStoryInlineError, InkLoader, InkLoaderError, compile_story_inline};
pub use transcript::{BrinkTranscript, refresh_transcripts};
pub use wake_delta::{BrinkWorldDelta, WorldDelta};