diff --git a/crates/bevy_ecs/src/schedule/config.rs b/crates/bevy_ecs/src/schedule/config.rs index 55f38ca19c..96ab05d4eb 100644 --- a/crates/bevy_ecs/src/schedule/config.rs +++ b/crates/bevy_ecs/src/schedule/config.rs @@ -311,8 +311,8 @@ where /// If automatically inserting [`apply_deferred`](crate::schedule::apply_deferred) like /// this isn't desired, use [`before_ignore_deferred`](Self::before_ignore_deferred) instead. /// - /// Note: The given set is not implicitly added to the schedule when this system set is added. - /// It is safe, but no dependencies will be created. + /// Calling [`.chain`](Self::chain) is often more convenient and ensures that all systems are added to the schedule. + /// Please check the [caveats section of `.after`](Self::after) for details. fn before(self, set: impl IntoSystemSet) -> SystemConfigs { self.into_configs().before(set) } @@ -323,8 +323,23 @@ where /// If automatically inserting [`apply_deferred`](crate::schedule::apply_deferred) like /// this isn't desired, use [`after_ignore_deferred`](Self::after_ignore_deferred) instead. /// - /// Note: The given set is not implicitly added to the schedule when this system set is added. - /// It is safe, but no dependencies will be created. + /// Calling [`.chain`](Self::chain) is often more convenient and ensures that all systems are added to the schedule. + /// + /// # Caveats + /// + /// If you configure two [`System`]s like `(GameSystem::A).after(GameSystem::B)` or `(GameSystem::A).before(GameSystem::B)`, the `GameSystem::B` will not be automatically scheduled. + /// + /// This means that the system `GameSystem::A` and the system or systems in `GameSystem::B` will run independently of each other if `GameSystem::B` was never explicitly scheduled with [`configure_sets`] + /// If that is the case, `.after`/`.before` will not provide the desired behaviour + /// and the systems can run in parallel or in any order determined by the scheduler. + /// Only use `after(GameSystem::B)` and `before(GameSystem::B)` when you know that `B` has already been scheduled for you, + /// e.g. when it was provided by Bevy or a third-party dependency, + /// or you manually scheduled it somewhere else in your app. + /// + /// Another caveat is that if `GameSystem::B` is placed in a different schedule than `GameSystem::A`, + /// any ordering calls between them—whether using `.before`, `.after`, or `.chain`—will be silently ignored. + /// + /// [`configure_sets`]: https://docs.rs/bevy/latest/bevy/app/struct.App.html#method.configure_sets fn after(self, set: impl IntoSystemSet) -> SystemConfigs { self.into_configs().after(set) }