Module command 

Deferred structural changes.

A callback that only has a shared world cannot spawn or despawn directly – those need &mut World. Instead it queues the change on a Commands queue; the driver applies the queue with World::apply once the callback has returned.

A queue belongs to a scope: everything queued through it lands in that scope, and every command carries the scope it was queued from so that applying it later cannot be redirected by a queue that outlived its scope.

A queued spawn still needs a handle right away, so Commands::spawn reserves one with World::reserve_entity and returns it. The handle is usable immediately – it can be stored in a component or handed to another callback – and refers to a live entity once the queue is applied.

Commands run in the order they were queued. A command that acts on a reserved entity must therefore be queued after the Spawn that brings it to life: for example Commands::despawn does nothing when the entity is not alive yet.

A queue only queues changes to what its scope owns, and a despawn it cannot take is dropped when it is queued rather than left to fail quietly when it is applied. What a command does not decide up front is where the entity has moved by the time it runs: a queued despawn re-checks its scope when it is applied, so an entity that has since left that scope survives. A Spawn pushed by hand with Commands::push carries its own ordering.

let mut world = World::new();

let entity = {
    let scope = world.root_scope();
    let commands = scope.queue();
    commands.spawn(bundle!["entity"])
};
// Nothing has happened yet.
assert!(!world.root_scope().contains(entity));
world.apply().unwrap();
assert!(world.root_scope().contains(entity));

Re-exports

use crate::bundle::Bundle; 🔒

use crate::entity::Entity; 🔒

use crate::error::EntityAccessError; 🔒

use crate::world::World; 🔒

Structs

Commands

A queue of structural changes, all of them in one scope.

Despawn

Despawns an entity and its subtree.

Link

Relinks an entity into another parent.

Spawn

Spawns a bundle on a reserved entity, in a scope.

Unlink

Detaches an entity into a scope.

Traits

Command

A structural change that can be applied later.

CommandErase

Erases a command into the world’s command storage.