Add example

Cargo.toml

@@ -319,6 +319,10 @@ path = "examples/ecs/component_change_detection.rs"
 name = "event"
 path = "examples/ecs/event.rs"
 
+[[example]]
+name = "exclusive_system_tricks"
+path = "examples/ecs/exclusive_system_tricks.rs"
+
 [[example]]
 name = "fixed_timestep"
 path = "examples/ecs/fixed_timestep.rs"

examples/README.md

@@ -167,6 +167,7 @@ Example | File | Description
 `ecs_guide` | [`ecs/ecs_guide.rs`](./ecs/ecs_guide.rs) | Full guide to Bevy's ECS
 `component_change_detection` | [`ecs/component_change_detection.rs`](./ecs/component_change_detection.rs) | Change detection on components
 `event` | [`ecs/event.rs`](./ecs/event.rs) | Illustrates event creation, activation, and reception
+`exclusive_system_tricks` | [`ecs/exclusive_system_tricks.rs`](./ecs/exclusive_system_tricks.rs) | A basic guide to using exclusive systems and exclusive world access.
 `fixed_timestep` | [`ecs/fixed_timestep.rs`](./ecs/fixed_timestep.rs) | Shows how to create systems that run every fixed timestep, rather than every tick
 `generic_system` | [`ecs/generic_system.rs`](./ecs/generic_system.rs) | Shows how to create systems that can be reused with different types
 `hierarchy` | [`ecs/hierarchy.rs`](./ecs/hierarchy.rs) | Creates a hierarchy of parents and children entities

examples/ecs/exclusive_system_tricks.rs

@@ -0,0 +1,57 @@
+use bevy::{
+    ecs::system::{lifetimeless::*, SystemState},
+    prelude::*,
+};
+
+fn main() {
+    App::new()
+        .init_resource::<MyCustomSchedule>()
+        .insert_resource(5u32)
+        .add_system(simple_exclusive_system.exclusive_system())
+        .add_system(stateful_exclusive_system.exclusive_system())
+        .run();
+}
+
+#[derive(Default)]
+struct MyCustomSchedule(Schedule);
+
+#[derive(Component)]
+struct MyComponent;
+
+/// Just a simple exclusive system - this function will run with mutable access to
+/// the main app world. This lets it call into other schedules, or modify and query the
+/// world in hard-to-predict ways, which makes it a powerful primitive. However, because
+/// this is usually not needed, and because such wide access makes parallelism impossible,
+/// it should generally be avoided.
+fn simple_exclusive_system(world: &mut World) {
+    world.resource_scope(|world, mut my_schedule: Mut<MyCustomSchedule>| {
+        // The resource_scope method is one of the main tools for working with &mut World.
+        // This method will temporarily remove the resource from the ECS world and let you
+        // access it while still keeping &mut World. A particularly popular pattern is storing
+        // schedules, stages, and other similar "runnables" in the world, taking them out
+        // using resource_scope, and running them with the world:
+        my_schedule.0.run(world);
+        // This is fairly simple, but you can implement rather complex custom executors in this manner.
+    });
+}
+
+/// While it's usually not recommended due to parallelism concerns, you can also use exclusive systems
+/// as mostly-normal systems but with the ability to change parameter sets and flush commands midway through.
+fn stateful_exclusive_system(
+    world: &mut World,
+    mut part_one_state: Local<SystemState<(SRes<u32>, SCommands)>>,
+    mut part_two_state: Local<SystemState<SQuery<Read<MyComponent>>>>,
+) {
+    let (resource, mut commands) = part_one_state.get(world);
+    let res = *resource as usize;
+    commands.spawn_batch((0..res).map(|_| (MyComponent,)));
+
+    // Don't forget to apply your state, or commands won't take effect!
+    part_one_state.apply(world);
+    let query = part_two_state.get(world);
+    let entity_count = query.iter().len();
+    // note how the entities spawned in this system are observed,
+    // and how resources fetched in earlier stages can still be
+    // used if they're cloned out, or small enough to copy out.
+    assert_eq!(entity_count, res);
+}