Skip to main content

LogicCommands

Struct LogicCommands 

Source
pub struct LogicCommands<'w> { /* private fields */ }
Expand description

Managed, stage-deferred command access for ordinary Sim;Logic Systems.

Commands are retained in deterministic call order and become visible only after the current stage passes whole-batch validation.

Implementations§

Source§

impl LogicCommands<'_>

Source

pub fn spawn<B>(&mut self, bundle: B) -> Result<(), CommandEnqueueError>
where B: Bundle<Effect: NoBundleEffect>,

Queues one approved, side-effect-free bundle for deferred spawn.

Approved required components are materialized at the stage barrier. An explicit value in bundle takes precedence over its required default.

No entity handle is returned. The runtime assigns it at the stage barrier after the complete batch succeeds.

Source

pub fn spawn_copies<B>( &mut self, bundle: B, count: usize, ) -> Result<(), CommandEnqueueError>
where B: Bundle<Effect: NoBundleEffect> + Copy,

Queues count copies of one approved bundle for consecutive deferred spawn.

Every eventual entity consumes one slot from the bounded stage command budget even though the runtime retains only one erased bundle template. A request that does not fit poisons the complete stage batch just like repeated Self::spawn calls that cross the limit, and no prefix from this call is retained. At the stage barrier the bundle type is validated once, the entity limit is checked for every copy before mutation, and then distinct managed entities are created consecutively at this command’s position in queue order.

count == 0 is an immediate successful no-op: it occupies no command slot, retains no value, and does not validate or register B. Required components, explicit-over-required precedence, Disabled accounting, and Transform or camera interpolation snapping otherwise match singular spawn exactly. No handles are returned because identities do not become live until the stage barrier.

Copy deliberately excludes user-defined cloning work and destructors. Application remains linear in count; this method does not promise a native bulk ECS insertion.

Source

pub fn insert<B>( &mut self, entity: LogicEntity, bundle: B, ) -> Result<(), CommandEnqueueError>
where B: Bundle<Effect: NoBundleEffect>,

Queues approved components to be added to or replaced on one entity.

Existing explicit component types are replaced. Required components are materialized only when absent. The target and complete bundle are validated at the stage barrier before any structural command is applied. Inserting into and despawning the same entity in one stage is a batch conflict regardless of enqueue order.

Multiple inserts apply in call order, so the last explicit value of one component type wins. An explicit or newly required Transform2d or ActiveCamera2d starts snapped; a required Transform that already exists keeps its interpolation history. The standard Bevy Disabled component may also be inserted directly, though Self::disable names that whole-entity operation more clearly.

Source

pub fn remove<B>( &mut self, entity: LogicEntity, ) -> Result<(), CommandEnqueueError>
where B: Bundle<Effect: NoBundleEffect>,

Queues approved explicit component types for removal from one entity.

Removal is visible only after the current stage barrier. Required components are never removed implicitly, and naming an approved component that is absent is a successful no-op. Insert and remove commands apply in call order, but removing a component still required by the entity’s final component set rejects the complete structural batch before mutation. Removing and despawning the same entity in one stage is likewise a batch conflict.

Removing the standard Bevy Disabled component re-enables the entity after the barrier, though Self::enable names that operation more clearly. Retain its LogicEntity handle before disabling it: ordinary managed queries deliberately exclude disabled entities.

Source

pub fn disable( &mut self, entity: LogicEntity, ) -> Result<(), CommandEnqueueError>

Queues an entity to become inactive after the current stage barrier.

The entity keeps its identity, components, interpolation history, and place in the managed entity limit. Subsequent stages and same-frame extraction exclude it. Systems in the current stage continue to see the pre-barrier state. Repeated calls remain disabled, and this command has the same validation, ordering, atomicity, and despawn-conflict rules as Self::insert. Every call occupies one bounded Command slot, including a repeated disable.

Retain the entity’s LogicEntity before disabling it: ordinary managed queries deliberately cannot rediscover disabled entities. Pass that saved handle to Self::enable later.

Source

pub fn enable(&mut self, entity: LogicEntity) -> Result<(), CommandEnqueueError>

Queues a disabled entity to become active after the stage barrier.

Subsequent stages and same-frame extraction can observe the entity again. Enabling an already enabled entity is a successful no-op. This command has the same validation, ordering, atomicity, and despawn-conflict rules as Self::remove. It requires a handle saved before the entity became unavailable to ordinary managed queries. Every call occupies one bounded Command slot, including a no-op enable.

Source

pub fn despawn( &mut self, entity: LogicEntity, ) -> Result<(), CommandEnqueueError>

Queues a managed entity for deferred despawn.

Source

pub fn request_exit(&mut self) -> Result<(), CommandEnqueueError>

Requests successful application exit after the current stage barrier.

All Systems in the current stage still run. The request takes effect only if the complete command batch passes validation; repeated requests coalesce in the result, but each call still consumes one command slot. A fixed-stage request stops remaining catch-up ticks, and no new render extraction is produced. Pending input edges are discarded and interpolation endpoints are snapped, so a headless host that deliberately continues does not replay pre-exit input or display pre-exit state. If World replacement is requested in the same batch, exit takes precedence.

This method is unavailable during isolated World Startup. It does not terminate the process itself: the desktop host exits its event loop, while headless hosts inspect the resulting frame report. It produces no WorldExit lifecycle record and promises neither a cleanup hook nor one final presentation.

Source

pub fn set_paused(&mut self, paused: bool) -> Result<(), CommandEnqueueError>

Queues a change to fixed-simulation pause at the stage barrier.

FrameUpdate, input collection, extraction, and presentation continue while fixed simulation is paused. Every successfully enqueued call consumes one bounded command slot, including a request for the current value. Multiple calls in one successful stage are last-write-wins after every System in that stage has observed its entry-time clock state. A failed System or rejected command batch discards the pause request.

Entering pause stops remaining fixed catch-up work without discarding its accumulated simulation time, clears undelivered fixed input edges, and snaps managed interpolation. Resume makes retained work eligible on the next application frame; paused wall time and input edges are not replayed. Pause is Application-owned and survives World replacement. Replacement keeps its own stronger time cleanup and stage-skipping rules; a rejected transition does not undo an otherwise committed pause. Application exit suppresses a pause change from the same batch.

This method is unavailable during isolated World Startup. It does not bind an input action or implement toggle policy.

Source

pub fn new_transition_intent( &mut self, ) -> Result<TransitionIntentToken, CommandEnqueueError>

Issues a direct causal token valid during the current application frame.

Source

pub fn replace_world( &mut self, intent: TransitionIntentToken, target: WorldFactoryId, ) -> Result<(), CommandEnqueueError>

Queues a no-payload replacement request for stage-end arbitration.

Trait Implementations§

Source§

impl<'w, 's> ReadOnlySystemParam for LogicCommands<'w>
where ResMut<'w, CommandQueue>: ReadOnlySystemParam, ResMut<'w, DirectIntentIssuer>: ReadOnlySystemParam,

Source§

impl SystemParam for LogicCommands<'_>

Source§

type State = FetchState

Used to store data which persists across invocations of a system.
Source§

type Item<'w, 's> = LogicCommands<'w>

The item type returned when constructing this system param. The value of this associated type should be Self, instantiated with new lifetimes. Read more
Source§

fn init_state(world: &mut World) -> Self::State

Creates a new instance of this param’s State.
Source§

fn init_access( state: &Self::State, system_meta: &mut SystemMeta, component_access_set: &mut FilteredAccessSet, world: &mut World, )

Registers any World access used by this SystemParam. Read more
Source§

fn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World)

Applies any deferred mutations stored in this SystemParam’s state. This is used to apply Commands during ApplyDeferred.
Source§

fn queue( state: &mut Self::State, system_meta: &SystemMeta, world: DeferredWorld<'_>, )

Queues any deferred mutations to be applied at the next ApplyDeferred.
Source§

unsafe fn get_param<'w, 's>( state: &'s mut Self::State, system_meta: &SystemMeta, world: UnsafeWorldCell<'w>, change_tick: Tick, ) -> Result<Self::Item<'w, 's>, SystemParamValidationError>

Creates a parameter to be passed into a SystemParamFunction. Read more

Auto Trait Implementations§

§

impl<'w> !RefUnwindSafe for LogicCommands<'w>

§

impl<'w> !UnwindSafe for LogicCommands<'w>

§

impl<'w> Freeze for LogicCommands<'w>

§

impl<'w> Send for LogicCommands<'w>

§

impl<'w> Sync for LogicCommands<'w>

§

impl<'w> Unpin for LogicCommands<'w>

§

impl<'w> UnsafeUnpin for LogicCommands<'w>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> ConditionalSend for T
where T: Send,

Source§

impl<T> Downcast for T
where T: Any,

Source§

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

Convert Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can then be further downcast into Box<ConcreteType> where ConcreteType implements Trait.
Source§

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait.
Source§

fn as_any(&self) -> &(dyn Any + 'static)

Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s.
Source§

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s.
Source§

impl<T> Downcast<T> for T

Source§

fn downcast(&self) -> &T

Source§

impl<T> DowncastSync for T
where T: Any + Send + Sync,

Source§

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync> ⓘ

Convert Arc<Trait> (where Trait: Downcast) to Arc<Any>. Arc<Any> can then be further downcast into Arc<ConcreteType> where ConcreteType implements Trait.
Source§

impl<S, T> Duplex<S> for T
where T: FromSample<S> + ToSample<S>,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<S> FromSample<S> for S

Source§

fn from_sample_(s: S) -> S

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoResult<T> for T

Source§

fn into_result(self) -> Result<T, RunSystemError>

Converts this type into the system output type.
Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T, U> ToSample<U> for T
where U: FromSample<T>,

Source§

fn to_sample_(self) -> U

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> Upcast<T> for T

Source§

fn upcast(&self) -> Option<&T>

Source§

impl<T> WasmNotSend for T
where T: Send,

Source§

impl<T> WasmNotSendSync for T

Source§

impl<T> WasmNotSync for T
where T: Sync,

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more