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<'_>
impl LogicCommands<'_>
Sourcepub fn spawn<B>(&mut self, bundle: B) -> Result<(), CommandEnqueueError>where
B: Bundle<Effect: NoBundleEffect>,
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.
Sourcepub fn spawn_copies<B>(
&mut self,
bundle: B,
count: usize,
) -> Result<(), CommandEnqueueError>
pub fn spawn_copies<B>( &mut self, bundle: B, count: usize, ) -> Result<(), CommandEnqueueError>
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.
Sourcepub fn insert<B>(
&mut self,
entity: LogicEntity,
bundle: B,
) -> Result<(), CommandEnqueueError>where
B: Bundle<Effect: NoBundleEffect>,
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.
Sourcepub fn remove<B>(
&mut self,
entity: LogicEntity,
) -> Result<(), CommandEnqueueError>where
B: Bundle<Effect: NoBundleEffect>,
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.
Sourcepub fn disable(
&mut self,
entity: LogicEntity,
) -> Result<(), CommandEnqueueError>
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.
Sourcepub fn enable(&mut self, entity: LogicEntity) -> Result<(), CommandEnqueueError>
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.
Sourcepub fn despawn(
&mut self,
entity: LogicEntity,
) -> Result<(), CommandEnqueueError>
pub fn despawn( &mut self, entity: LogicEntity, ) -> Result<(), CommandEnqueueError>
Queues a managed entity for deferred despawn.
Sourcepub fn request_exit(&mut self) -> Result<(), CommandEnqueueError>
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.
Sourcepub fn set_paused(&mut self, paused: bool) -> Result<(), CommandEnqueueError>
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.
Sourcepub fn new_transition_intent(
&mut self,
) -> Result<TransitionIntentToken, CommandEnqueueError>
pub fn new_transition_intent( &mut self, ) -> Result<TransitionIntentToken, CommandEnqueueError>
Issues a direct causal token valid during the current application frame.
Sourcepub fn replace_world(
&mut self,
intent: TransitionIntentToken,
target: WorldFactoryId,
) -> Result<(), CommandEnqueueError>
pub fn replace_world( &mut self, intent: TransitionIntentToken, target: WorldFactoryId, ) -> Result<(), CommandEnqueueError>
Queues a no-payload replacement request for stage-end arbitration.
Trait Implementations§
impl<'w, 's> ReadOnlySystemParam for LogicCommands<'w>where
ResMut<'w, CommandQueue>: ReadOnlySystemParam,
ResMut<'w, DirectIntentIssuer>: ReadOnlySystemParam,
Source§impl SystemParam for LogicCommands<'_>
impl SystemParam for LogicCommands<'_>
Source§type Item<'w, 's> = LogicCommands<'w>
type Item<'w, 's> = LogicCommands<'w>
Self, instantiated with new lifetimes. Read moreSource§fn init_access(
state: &Self::State,
system_meta: &mut SystemMeta,
component_access_set: &mut FilteredAccessSet,
world: &mut World,
)
fn init_access( state: &Self::State, system_meta: &mut SystemMeta, component_access_set: &mut FilteredAccessSet, world: &mut World, )
Source§fn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World)
fn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World)
SystemParam’s state.
This is used to apply Commands during ApplyDeferred.Source§fn queue(
state: &mut Self::State,
system_meta: &SystemMeta,
world: DeferredWorld<'_>,
)
fn queue( state: &mut Self::State, system_meta: &SystemMeta, world: DeferredWorld<'_>, )
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>
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>
SystemParamFunction. Read moreAuto 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> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
impl<T> ConditionalSend for Twhere
T: Send,
Source§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
Source§fn into_any(self: Box<T>) -> Box<dyn Any>
fn into_any(self: Box<T>) -> Box<dyn Any>
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>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
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)
fn as_any(&self) -> &(dyn Any + 'static)
&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)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot
generate &mut Any’s vtable from &mut Trait’s.