Ergonomic tools for working with Commands from &mut World

[alice-i-cecile]

What problem does this solve or what need does it fill?

Even when working with exclusive world access, work often needs to be deferred to satisfy soundness.

This occurs most commonly when iterating over a query or in other looping contexts.

What solution would you like?

Add World::commands(), which fetches a fresh instance of Commands.

Add World::apply_commands(), for a simple

What alternative(s) have you considered?

This is a partial, tightly-scoped alternative to some of the frustrations that inspired bevyengine/rfcs#42.

Additional context

World::apply_commands can currently be achieved with this snippet:

use bevy::prelude::*;
use bevy::ecs::system::SystemState;

let world = World::new();

let mut system_state = SystemState::<Commands>::new(&mut world);

// Manually adding a command to the list to verify that this works
let mut commands = system_state.get_mut();
commands.spawn();

// Applies all accumulated commands to the world, causing them to take immediate effect
system_state.apply(&mut world);

[cart]

Quick callout that Commands requires an &Entities reference, which is owned by World. This would block direct mutable Word accesses, which means by itself it isn't a suitable alternative to bevyengine/rfcs#42

[alice-i-cecile]

Quick callout that Commands requires an &Entities reference, which is owned by World. This would block direct mutable Word accesses, which means by itself it isn't a suitable alternative to bevyengine/rfcs#42

Hmm, right 🤔 I'm running into this with my naive impl.

[Davier]

Another note: this used to be possible in bevy 0.4, thanks to entity reservation being behind a mutex.

[cart]

Another note: this used to be possible in bevy 0.4, thanks to entity reservation being behind a mutex.

Actually not quite. Entity reservation is thread safe due to how it uses atomics (both in 0.4 and now), but it was never behind a mutex. We just shared &Entities references using what can only be described as "disgusting disregard for everything Rust works so hard to prevent". (I'm using this uncharitable phrasing because I wrote the code).

bevy/crates/bevy_ecs/src/core/entities.rs

Line 322 in 3b2c6ce

#[derive(Debug)]

[cart]

The current implementation plays by the rules, but also makes it impossible to do what we did in 0.4.

[alice-i-cecile]

Playing with a draft of this, there are two serious problems that must be overcome.

1. As discussed above, we need a &Entities to initialize a new Commands. This is required to verify that an entity exists before operating on it with EntityCommands, as well as to reserve entities for Commands.spawn.
2. We need to store a CommandQueue somewhere. Naively adding it as a field to World won't work, because then we can't mutate the world as that would be self-referential.

When Commands is used as a system parameter, the second problem is solved by storing the CommandQueue in the Fetch of the system parameter, which is stored in the FunctionSystem, which is then owned by a stage and ultimately a schedule (which lives outside the world).

We could get around the second, less serious issue by forcing users to create a new CommandQueue in their exclusive system, and then manually applying that. This is the solution currently taken by the test cases that use commands. I'm not a huge fan: it's verbose and exposes CommandQueue to the user, when that should largely be an implementation detail.

[alice-i-cecile]

#3946 makes significant progress towards this; see the included example.

[alice-i-cecile]

Closed in favor of #6184.