Struct FlowSleep 

pub struct FlowSleep<M: Send + Sync + 'static = ()> { /* private fields */ }

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.

Construct via FlowSleep::persistent / FlowSleep::once, optionally chaining with_args, with_detect, and dormant.

Implementations

impl<M: Send + Sync + 'static> FlowSleep<M>

pub fn persistent(condition: impl Into<String>) -> Self

A persistent policy: condition is an ink function name returning a truthy value when the flow should wake. Re-arms every time the flow re-parks (§13.1 point 4).

pub fn once(condition: impl Into<String>) -> Self

A one-shot policy: fires once on the first condition-true, then the component is removed and the flow reverts to ordinary advancement.

pub fn latch(condition: impl Into<String>) -> Self

A reversible latch policy (issue #1081): wakes on a transition to true, then re-arms watching for the transition back to false, and so on indefinitely. See WakeArming::Latch for the full contract.

pub fn with_args(self, args: Vec<Value>) -> Self

Pass arguments to the condition function (declaration order). Builder.

pub fn with_condition_value(self, value: Value) -> Self

Attach a dynamically-resolved fn-value token (Value::FnRef/ Closure) as the wake condition — for a host that obtained the condition dynamically (a global’s current value, a returned callback token, a bind_brink_query result) rather than naming it statically via persistent/once.

When set, this takes over both halves of condition resolution: the attach-time purity gate checks value’s target row (check_value_condition_purity instead of check_named_condition_purity), and evaluation invokes the token directly (call_ink_function_value instead of resolving condition by path). condition’s string (from persistent/ once) remains only a diagnostic label at that point — it is never resolved by path while a condition_value is set. Builder.

pub fn with_detect(self, detect: DetectSummary) -> Self

Attach the condition’s dependency DetectSummary (#913), tuning the re-evaluation cadence. Without this the summary is empty — treated as all-detect-capable (re-evaluate only on a World change), the right default for a condition reading only ink World state. A summary whose bits names external (component) capabilities that are all change-detection-capable (#913 AND-merge verdict all-true) gets the §12.5 cheap path (#996): re-evaluated only when one of those components changed — provided each is registered via register_capability (an unregistered capability the wake layer cannot observe must-polls conservatively). A summary with any must-poll bit re-evaluates every pass. Builder.

pub fn reads_bookkeeping(self) -> Self

Declare that this condition reads story bookkeeping — a visit count ({knot}, TURNS_SINCE(-> knot)), a turn count, the turn index (TURNS(), CHOICE_COUNT()), or RNG state (issue #1146). Builder.

The row-directed wake-dirtying path re-evaluates a condition only when a cell it reads was actually written, and a condition’s read set comes from its effect row — which models global cells only (brink_format::DirectEffects::reads). Bookkeeping reads are invisible to it, so a condition that depends on one must say so here, or it will sit parked through the turns that move it. Nothing else needs this: a condition reading ink globals is covered by its row automatically, and a condition whose row is missing/opaque already re-evaluates on any change.

Graduating a reads-bookkeeping row dimension (so this is inferred rather than declared) is tracked as the follow-up to #1146.

Known tradeoff, not a bug: once a condition declaring this is evaluated even once, it stays perpetually flagged for re-evaluation thereafter, even if nothing it actually depends on ever changes again. Every Evaluate pass notes an unconditional bookkeeping touch in the changed-cell ledger (the unavoidable &mut BrinkGlobals residue building a condition’s context takes), and that residue is itself indistinguishable, to the row-directed path, from a real bookkeeping write — so a reads_bookkeeping() reader’s own prior evaluation re-triggers the next one. This is deliberately on the over-report side of the ledger’s “never under-report” law (module docs, crate::wake_delta): the cost is a self-sustaining re-evaluation, never a missed wake.

pub fn dormant(self) -> Self

Mark this policy dormant (docs/effects-spec.md §13.1 point 6): the flow is parked at entry and its first turn runs on the first condition-true. Attach to a freshly fulfilled flow before it has stepped. Builder.

pub fn cancel(&mut self)

Cancel the policy: its condition is henceforth a permanent false (§13.1 — “cancellation → false”). The flow stays parked and is never re-evaluated or woken by this policy again. To fully detach, remove the component; to change the wake condition, replace it with a new one.

pub fn condition(&self) -> &str

The ink function name of the wake condition — a diagnostic label only when condition_value is Some.

pub fn condition_value(&self) -> Option<&Value>

The dynamically-resolved fn-value token, if with_condition_value set one.

pub fn state(&self) -> SleepState

The current SleepState.

pub fn arming(&self) -> WakeArming

The re-arm policy.

pub fn latch_waiting_for(&self) -> bool

WakeArming::Latch only: the boolean value the condition must next equal to fire. This doubles as an outside observer’s read of which side of the latch the policy currently sits on — e.g. for a door whose condition is “is the switch on?”: true means the policy is waiting for the switch to turn on (the door is currently locked); false means it is waiting for the switch to turn off (the door is currently open). Always true (and unused) for Persistent/Once.

pub fn dependencies_all_detect_capable(&self) -> bool

Whether every dependency capability is change-detection-backed (#913 AND-merge verdict). false means the condition polls every pass. true enables the cheap path: for an empty bits map (no external dependency) that is re-evaluate-on-BrinkGlobals-change; for a non-empty one it is re-evaluate-on-watched-component-change (§12.5, #996), provided each named capability is registered via register_capability so mark_wake_dirty can observe its ticks — an unregistered capability the wake layer cannot observe still must-polls.

pub fn detect_summary(&self) -> &DetectSummary

The dependency DetectSummary this policy was built with.

pub fn declares_bookkeeping_reads(&self) -> bool

Whether the host declared this condition a reader of story bookkeeping — see reads_bookkeeping.

pub fn wants_collect(&self) -> bool

Whether Collect should step this flow this turn — the predicate advance_batch’s Collect phase applies. Only a Woken policy admits the flow; a parked, cancelled, or faulted policy costs zero (skipped).

Trait Implementations

impl<M: Send + Sync + 'static> Component for FlowSleep<M>

where Self: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

A constant indicating the storage type used for this component.

type Mutability = Mutable

A marker type to assist Bevy with determining if this component is mutable, or immutable. Mutable components will have Component<Mutability = Mutable>, while immutable components will instead have Component<Mutability = Immutable>.

fn register_required_components( _requiree: ComponentId, required_components: &mut RequiredComponentsRegistrator<'_, '_>, )

Registers required components.

fn clone_behavior() -> ComponentCloneBehavior

Called when registering this component, allowing to override clone function (or disable cloning altogether) for this component.

fn relationship_accessor() -> Option<ComponentRelationshipAccessor<Self>>

Returns ComponentRelationshipAccessor required for working with relationships in dynamic contexts.

fn on_add() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_add ComponentHook for this Component if one is defined.

fn on_insert() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_insert ComponentHook for this Component if one is defined.

fn on_discard() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_discard ComponentHook for this Component if one is defined.

fn on_remove() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_remove ComponentHook for this Component if one is defined.

fn on_despawn() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_despawn ComponentHook for this Component if one is defined.

fn map_entities<E>(_this: &mut Self, _mapper: &mut E)

where E: EntityMapper,

Maps the entities on this component using the given EntityMapper. This is used to remap entities in contexts like scenes and entity cloning. When deriving Component, this is populated by annotating fields containing entities with #[entities]

impl<M> FromReflect for FlowSleep<M>

where FlowSleep<M>: Any + Send + Sync, M: TypePath + Send + Sync + 'static,

fn from_reflect(reflect: &dyn PartialReflect) -> Option<Self>

Constructs a concrete instance of Self from a reflected value.

fn take_from_reflect( reflect: Box<dyn PartialReflect>, ) -> Result<Self, Box<dyn PartialReflect>>

Attempts to downcast the given value to Self using, constructing the value using from_reflect if that fails.

impl<M> GetTypeRegistration for FlowSleep<M>

where FlowSleep<M>: Any + Send + Sync, M: TypePath + Send + Sync + 'static,

fn get_type_registration() -> TypeRegistration

Returns the default TypeRegistration for this type.

fn register_type_dependencies(registry: &mut TypeRegistry)

Registers other types needed by this type.

impl<M> PartialReflect for FlowSleep<M>

where FlowSleep<M>: Any + Send + Sync, M: TypePath + Send + Sync + 'static,

fn get_represented_type_info(&self) -> Option<&'static TypeInfo>

Returns the TypeInfo of the type represented by this value.

fn try_apply(&mut self, value: &dyn PartialReflect) -> Result<(), ApplyError>

Tries to apply a reflected value to this value.

fn reflect_kind(&self) -> ReflectKind

Returns a zero-sized enumeration of “kinds” of type.

fn reflect_ref(&self) -> ReflectRef<'_>

Returns an immutable enumeration of “kinds” of type.

fn reflect_mut(&mut self) -> ReflectMut<'_>

Returns a mutable enumeration of “kinds” of type.

fn reflect_owned(self: Box<Self>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type.

fn try_into_reflect( self: Box<Self>, ) -> Result<Box<dyn Reflect>, Box<dyn PartialReflect>>

Attempts to cast this type to a boxed, fully-reflected value.

fn try_as_reflect(&self) -> Option<&dyn Reflect>

Attempts to cast this type to a fully-reflected value.

fn try_as_reflect_mut(&mut self) -> Option<&mut dyn Reflect>

Attempts to cast this type to a mutable, fully-reflected value.

fn into_partial_reflect(self: Box<Self>) -> Box<dyn PartialReflect>

Casts this type to a boxed, reflected value.

fn as_partial_reflect(&self) -> &dyn PartialReflect

Casts this type to a reflected value.

fn as_partial_reflect_mut(&mut self) -> &mut dyn PartialReflect

Casts this type to a mutable, reflected value.

fn reflect_partial_eq(&self, value: &dyn PartialReflect) -> Option<bool>

Returns a “partial equality” comparison result.

fn reflect_partial_cmp(&self, value: &dyn PartialReflect) -> Option<Ordering>

Returns a “partial comparison” result.

fn reflect_clone(&self) -> Result<Box<dyn Reflect>, ReflectCloneError>

Attempts to clone Self using reflection.

fn apply(&mut self, value: &(dyn PartialReflect + 'static))

Applies a reflected value to this value.

fn to_dynamic(&self) -> Box<dyn PartialReflect>

Converts this reflected value into its dynamic representation based on its kind.

fn reflect_clone_and_take<T>(&self) -> Result<T, ReflectCloneError>

where T: 'static, Self: Sized + TypePath,

For a type implementing PartialReflect, combines reflect_clone and take in a useful fashion, automatically constructing an appropriate ReflectCloneError if the downcast fails.

fn reflect_hash(&self) -> Option<u64>

Returns a hash of the value (which includes the type).

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

Debug formatter for the value.

fn is_dynamic(&self) -> bool

Indicates whether or not this type is a dynamic type.

impl<M> Reflect for FlowSleep<M>

where FlowSleep<M>: Any + Send + Sync, M: TypePath + Send + Sync + 'static,

fn into_any(self: Box<Self>) -> Box<dyn Any>

Returns the value as a Box<dyn Any>.

fn as_any(&self) -> &dyn Any

Returns the value as a &dyn Any.

fn as_any_mut(&mut self) -> &mut dyn Any

Returns the value as a &mut dyn Any.

fn into_reflect(self: Box<Self>) -> Box<dyn Reflect>

Casts this type to a boxed, fully-reflected value.

fn as_reflect(&self) -> &dyn Reflect

Casts this type to a fully-reflected value.

fn as_reflect_mut(&mut self) -> &mut dyn Reflect

Casts this type to a mutable, fully-reflected value.

fn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>>

Performs a type-checked assignment of a reflected value to this value.

impl<M> Struct for FlowSleep<M>

where FlowSleep<M>: Any + Send + Sync, M: TypePath + Send + Sync + 'static,

fn field(&self, name: &str) -> Option<&dyn PartialReflect>

Gets a reference to the value of the field named name as a &dyn PartialReflect.

fn field_mut(&mut self, name: &str) -> Option<&mut dyn PartialReflect>

Gets a mutable reference to the value of the field named name as a &mut dyn PartialReflect.

fn field_at(&self, index: usize) -> Option<&dyn PartialReflect>

Gets a reference to the value of the field with index index as a &dyn PartialReflect.

fn field_at_mut(&mut self, index: usize) -> Option<&mut dyn PartialReflect>

Gets a mutable reference to the value of the field with index index as a &mut dyn PartialReflect.

fn name_at(&self, index: usize) -> Option<&str>

Gets the name of the field with index index.

fn index_of_name(&self, name: &str) -> Option<usize>

Gets the index of the field with the given name.

fn field_len(&self) -> usize

Returns the number of fields in the struct.

fn iter_fields(&self) -> FieldIter<'_>

Returns an iterator over the values of the reflectable fields for this struct.

fn to_dynamic_struct(&self) -> DynamicStruct

Creates a new DynamicStruct from this struct.

fn get_represented_struct_info(&self) -> Option<&'static StructInfo>

Will return None if TypeInfo is not available.

impl<M> TypePath for FlowSleep<M>

where FlowSleep<M>: Any + Send + Sync, M: TypePath + Send + Sync + 'static,

fn type_path() -> &'static str

Returns the fully qualified path of the underlying type.

fn short_type_path() -> &'static str

Returns a short, pretty-print enabled path to the type.

fn type_ident() -> Option<&'static str>

Returns the name of the type, or None if it is anonymous.

fn crate_name() -> Option<&'static str>

Returns the name of the crate the type is in, or None if it is anonymous.

fn module_path() -> Option<&'static str>

Returns the path to the module the type is in, or None if it is anonymous.

impl<M> Typed for FlowSleep<M>

where FlowSleep<M>: Any + Send + Sync, M: TypePath + Send + Sync + 'static,

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.