schedule v3 ("stageless")

[maniwani]

Objective

• replace bevy_ecs::schedule with the API outlined in Stageless: a complete scheduling overhaul rfcs#45

Solution

Blocked On

• Add &mut World as a system param and make .exclusive_system() optional #4166
• [Merged by Bors] - Nested spawns on scope #4466

Closely Related

• Improvements to execution order ambiguity reporting #4299
• Add time scaling and simplify fixed timestep use #3002

(Edit: Based on feedback, I think I'm going to split this into 2-3 PRs.)

• (PR 1, this one) Add bevy_ecs::schedule_v3 module with the new stuff.
• (PR 2) Port all bevy_* crates and examples over to the new API.
• (PR 2 or 3) Delete old bevy_ecs::schedule (and change schedule_v3 to schedule).

Glossary

• system
  • a function whose arguments are all system params
• (system) set
  • a system label
  • can have systems and other sets "under" it (meaning you can attach conditions that will skip everything in a set)
• schedule
  • executable form of a set (i.e. it's an actual container, has systems topologically sorted for speed, etc.)

Systems and sets share a common builder API and they can all be ordered together.

Detailed Changelist

• conditions
  • (run criteria)
  • "pure" systems
    • not allowed to mutate data (must impl ReadOnlySystemParamFetch)
    • not allowed to have local state⁠—change detection or Local<T> (TODO)
      • conditions aren't aware of other conditions, so ^ would lead to subtle bugs
  • return bool (removed ShouldRun)
  • can be attached to systems and sets
    • can attach more than one (all conditions must be true, logical AND)
  • tested literally right before the system (or the first system in the set) would run
• Systems
  • a resource that stores everything related to systems/sets/schedules
  • can tell you if a system or set with a label exists (might be useful for plugins)
  • allows immediate runtime insertion and removal
    • does not affect systems or schedules that have been extracted
• stages
  • removed
  • to apply queued commands, add at least one apply_system_buffers system to your app
• states
  • plain finite-state machine (removed state stack)
  • are not system sets, but can have associated sets that run during state transitions
    • OnEnter(state) and OnExit(state) (broken by recent label changes)
  • to apply queued transitions, add at least one apply_state_transition::<State> system to your app
• fixed timestep
  • is now a system set run by an exclusive system (just like state transitions)
• runner
  • (executor)
  • several variants
    • single-threaded
    • multi-threaded
    • "simple" (single-threaded and immediately applies commands after each system completes)

Preview

use bevy::prelude::*;

/* .. */

fn main() {
    App::new()
        /* ... */
        .add_system_set(
            // systems and sets have the same config API
            MySystemSet::Menu
                // Menu is child of Update and thus dependent on its conditions
                .in_set(CoreSet::Update)
                // Menu itself has a condition that must pass for anything under it to run
                .run_if(state_equals(GameState::Paused))
        )
        // built-in fixed update
        .add_system_set(MySystemSet::Physics.in_set(CoreSet::FixedUpdate))
        .add_system(
            update_text
                .in_set(MySystemSet::Menu)
                // you can attach multiple conditions now (they all have to return true)
                .run_if(some_condition_system)
                .run_if(some_other_condition_system)
        )
        // add any iterable of systems and sets
        .add_systems(
          // convenience macro for adding a sequential chain of systems and sets
          chain![
            MySystemSet::SubMenu,
            some_random_system,
            // this system will apply any commands queued by previous systems 
            apply_system_buffers.named(MySystem::MenuApplyBuffers),
          ]
          .in_set(MySystemSet::Menu)
        )
        /* ... */
        .run();
}

Resolves

a lot of stuff

Follow-up Work

• Atomic schedule groups rfcs#46
• Relaxed (if-needed) ordering constraints rfcs#47

[alice-i-cecile]

This needs to mention that the order still follows existing rules, and is not guaranteed to be stable.

[alice-i-cecile]

This should be cross-referenced with SingleThreadedRunner.

[maniwani]

Closing this since I'm most likely going to make a new PR. I expect the RFC to be merged soon and I want to formalize a more collaborative effort and migration path given the number of PRs trying to make incremental progress. This one was basically a solo attempt, but we may decide to re-open it.