Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

schedule v3 ("stageless") #4391

Closed
wants to merge 46 commits into from
Closed

Conversation

maniwani
Copy link
Contributor

@maniwani maniwani commented Apr 1, 2022

Objective

Solution

Blocked On

Closely Related

(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

@github-actions github-actions bot added the S-Needs-Triage This issue needs to be labelled label Apr 1, 2022
@alice-i-cecile alice-i-cecile self-requested a review April 2, 2022 02:18
@alice-i-cecile alice-i-cecile added C-Feature A new feature, making something new possible A-ECS Entities, components, systems, and events C-Usability A targeted quality-of-life change that makes Bevy easier to use C-Bug An unexpected or incorrect behavior and removed S-Needs-Triage This issue needs to be labelled labels Apr 2, 2022
use bevy_utils::tracing::Instrument;
use fixedbitset::FixedBitSet;

/// Runs systems on a single thread.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

}
}

/// Runs systems on a single thread and immediately applies their commands.
Copy link
Member

@alice-i-cecile alice-i-cecile Apr 2, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be cross-referenced with SingleThreadedRunner.

@maniwani maniwani force-pushed the stageless branch 3 times, most recently from 0173759 to 3ab5ce0 Compare April 4, 2022 00:31
@maniwani
Copy link
Contributor Author

maniwani commented Aug 9, 2022

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.

@maniwani maniwani closed this Aug 9, 2022
@maniwani maniwani deleted the stageless branch November 13, 2022 19:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-ECS Entities, components, systems, and events C-Bug An unexpected or incorrect behavior C-Feature A new feature, making something new possible C-Usability A targeted quality-of-life change that makes Bevy easier to use X-Controversial There is active debate or serious implications around merging this PR
Projects
Archived in project
Development

Successfully merging this pull request may close these issues.

5 participants