Struct Schedule 

pub struct Schedule { /* private fields */ }

A collection of systems, and the metadata and executor needed to run them in a certain order under certain conditions.

Schedule labels

Each schedule has a ScheduleLabel value. This value is used to uniquely identify the schedule when added to a World’s Schedules, and may be used to specify which schedule a system should be added to.

Example

Here is an example of a Schedule running a “Hello world” system:

fn hello_world() { println!("Hello world!") }

fn main() {
    let mut world = World::new();
    let mut schedule = Schedule::default();
    schedule.add_systems(hello_world);

    schedule.run(&mut world);
}

A schedule can also run several systems in an ordered way:

fn system_one() { println!("System 1 works!") }
fn system_two() { println!("System 2 works!") }
fn system_three() { println!("System 3 works!") }

fn main() {
    let mut world = World::new();
    let mut schedule = Schedule::default();
    schedule.add_systems((
        system_two,
        system_one.before(system_two),
        system_three.after(system_two),
    ));

    schedule.run(&mut world);
}

Schedules are often inserted into a World and identified by their ScheduleLabel only:

use bevy_ecs::schedule::ScheduleLabel;

// Declare a new schedule label.
#[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash, Default)]
struct Update;

// This system shall be part of the schedule.
fn an_update_system() {
    println!("Hello world!");
}

fn main() {
    let mut world = World::new();

    // Add a system to the schedule with that label (creating it automatically).
    world.get_resource_or_init::<Schedules>().add_systems(Update, an_update_system);

    // Run the schedule, and therefore run the system.
    world.run_schedule(Update);
}

Implementations

impl Schedule

pub fn new(label: impl ScheduleLabel) -> Schedule

Constructs an empty Schedule.

Examples found in repository

examples/ecs/custom_schedule.rs (line 22)

fn main() {
    let mut app = App::new();

    // Create a new [`Schedule`]. For demonstration purposes, we configure it to use a single threaded executor so that
    // systems in this schedule are never run in parallel. However, this is not a requirement for custom schedules in
    // general.
    let mut custom_update_schedule = Schedule::new(SingleThreadedUpdate);
    custom_update_schedule.set_executor_kind(ExecutorKind::SingleThreaded);

    // Adding the schedule to the app does not automatically run the schedule. This merely registers the schedule so
    // that systems can look it up using the `Schedules` resource.
    app.add_schedule(custom_update_schedule);

    // Bevy `App`s have a `main_schedule_label` field that configures which schedule is run by the App's `runner`.
    // By default, this is `Main`. The `Main` schedule is responsible for running Bevy's main schedules such as
    // `Update`, `Startup` or `Last`.
    //
    // We can configure the `Main` schedule to run our custom update schedule relative to the existing ones by modifying
    // the `MainScheduleOrder` resource.
    //
    // Note that we modify `MainScheduleOrder` directly in `main` and not in a startup system. The reason for this is
    // that the `MainScheduleOrder` cannot be modified from systems that are run as part of the `Main` schedule.
    let mut main_schedule_order = app.world_mut().resource_mut::<MainScheduleOrder>();
    main_schedule_order.insert_after(Update, SingleThreadedUpdate);

    // Adding a custom startup schedule works similarly, but needs to use `insert_startup_after`
    // instead of `insert_after`.
    app.add_schedule(Schedule::new(CustomStartup));

    let mut main_schedule_order = app.world_mut().resource_mut::<MainScheduleOrder>();
    main_schedule_order.insert_startup_after(PreStartup, CustomStartup);

    app.add_systems(SingleThreadedUpdate, single_threaded_update_system)
        .add_systems(CustomStartup, custom_startup_system)
        .add_systems(PreStartup, pre_startup_system)
        .add_systems(Startup, startup_system)
        .add_systems(First, first_system)
        .add_systems(Update, update_system)
        .add_systems(Last, last_system)
        .run();
}

examples/stress_tests/many_components.rs (line 107)

fn stress_test(num_entities: u32, num_components: u32, num_systems: u32) {
    let mut rng = ChaCha8Rng::seed_from_u64(42);
    let mut app = App::default();
    let world = app.world_mut();

    // register a bunch of components
    let component_ids: Vec<ComponentId> = (1..=num_components)
        .map(|i| {
            world.register_component_with_descriptor(
                // SAFETY:
                // * We don't implement a drop function
                // * u8 is Sync and Send
                unsafe {
                    ComponentDescriptor::new_with_layout(
                        format!("Component{i}").to_string(),
                        StorageType::Table,
                        Layout::new::<u8>(),
                        None,
                        true, // is mutable
                        ComponentCloneBehavior::Default,
                    )
                },
            )
        })
        .collect();

    // fill the schedule with systems
    let mut schedule = Schedule::new(Update);
    for _ in 1..=num_systems {
        let num_access_components = rng.random_range(1..10);
        let access_components: Vec<ComponentId> = component_ids
            .choose_multiple(&mut rng, num_access_components)
            .copied()
            .collect();
        let system = (QueryParamBuilder::new(|builder| {
            for &access_component in &access_components {
                if rand::random::<bool>() {
                    builder.mut_id(access_component);
                } else {
                    builder.ref_id(access_component);
                }
            }
        }),)
            .build_state(world)
            .build_any_system(base_system);
        schedule.add_systems((move || access_components.clone()).pipe(system));
    }

    // spawn a bunch of entities
    for _ in 1..=num_entities {
        let num_components = rng.random_range(1..10);
        let components: Vec<ComponentId> = component_ids
            .choose_multiple(&mut rng, num_components)
            .copied()
            .collect();

        let mut entity = world.spawn_empty();
        // We use `ManuallyDrop` here as we need to avoid dropping the u8's when `values` is dropped
        // since ownership of the values is passed to the world in `insert_by_ids`.
        // But we do want to deallocate the memory when values is dropped.
        let mut values: Vec<ManuallyDrop<u8>> = components
            .iter()
            .map(|_id| ManuallyDrop::new(rng.random_range(0..255)))
            .collect();
        let ptrs: Vec<OwningPtr> = values
            .iter_mut()
            .map(|value| {
                // SAFETY:
                // * We don't read/write `values` binding after this and values are `ManuallyDrop`,
                // so we have the right to drop/move the values
                unsafe { PtrMut::from(value).promote() }
            })
            .collect();
        // SAFETY:
        // * component_id's are from the same world
        // * `values` was initialized above, so references are valid
        unsafe {
            entity.insert_by_ids(&components, ptrs.into_iter());
        }
    }

    // overwrite Update schedule in the app
    app.add_schedule(schedule);
    app.add_plugins(MinimalPlugins)
        .add_plugins(DiagnosticsPlugin)
        .add_plugins(LogPlugin::default())
        .add_plugins(FrameTimeDiagnosticsPlugin::default())
        .add_plugins(LogDiagnosticsPlugin::filtered(HashSet::from_iter([
            DiagnosticPath::new("fps"),
        ])));
    app.run();
}

pub fn label(&self) -> Interned<dyn ScheduleLabel>

Returns the InternedScheduleLabel for this Schedule, corresponding to the ScheduleLabel this schedule was created with.

Examples found in repository

tests/ecs/ambiguity_detection.rs (line 81)

fn count_ambiguities(sub_app: &SubApp) -> AmbiguitiesCount {
    let schedules = sub_app.world().resource::<Schedules>();
    let mut ambiguities = <HashMap<_, _>>::default();
    for (_, schedule) in schedules.iter() {
        let ambiguities_in_schedule = schedule.graph().conflicting_systems().len();
        ambiguities.insert(schedule.label(), ambiguities_in_schedule);
    }
    AmbiguitiesCount(ambiguities)
}

pub fn add_systems<M>( &mut self, systems: impl IntoScheduleConfigs<Box<dyn System<Out = (), In = ()>>, M>, ) -> &mut Schedule

Add a collection of systems to the schedule.

Examples found in repository

examples/stress_tests/many_components.rs (line 125)

fn stress_test(num_entities: u32, num_components: u32, num_systems: u32) {
    let mut rng = ChaCha8Rng::seed_from_u64(42);
    let mut app = App::default();
    let world = app.world_mut();

    // register a bunch of components
    let component_ids: Vec<ComponentId> = (1..=num_components)
        .map(|i| {
            world.register_component_with_descriptor(
                // SAFETY:
                // * We don't implement a drop function
                // * u8 is Sync and Send
                unsafe {
                    ComponentDescriptor::new_with_layout(
                        format!("Component{i}").to_string(),
                        StorageType::Table,
                        Layout::new::<u8>(),
                        None,
                        true, // is mutable
                        ComponentCloneBehavior::Default,
                    )
                },
            )
        })
        .collect();

    // fill the schedule with systems
    let mut schedule = Schedule::new(Update);
    for _ in 1..=num_systems {
        let num_access_components = rng.random_range(1..10);
        let access_components: Vec<ComponentId> = component_ids
            .choose_multiple(&mut rng, num_access_components)
            .copied()
            .collect();
        let system = (QueryParamBuilder::new(|builder| {
            for &access_component in &access_components {
                if rand::random::<bool>() {
                    builder.mut_id(access_component);
                } else {
                    builder.ref_id(access_component);
                }
            }
        }),)
            .build_state(world)
            .build_any_system(base_system);
        schedule.add_systems((move || access_components.clone()).pipe(system));
    }

    // spawn a bunch of entities
    for _ in 1..=num_entities {
        let num_components = rng.random_range(1..10);
        let components: Vec<ComponentId> = component_ids
            .choose_multiple(&mut rng, num_components)
            .copied()
            .collect();

        let mut entity = world.spawn_empty();
        // We use `ManuallyDrop` here as we need to avoid dropping the u8's when `values` is dropped
        // since ownership of the values is passed to the world in `insert_by_ids`.
        // But we do want to deallocate the memory when values is dropped.
        let mut values: Vec<ManuallyDrop<u8>> = components
            .iter()
            .map(|_id| ManuallyDrop::new(rng.random_range(0..255)))
            .collect();
        let ptrs: Vec<OwningPtr> = values
            .iter_mut()
            .map(|value| {
                // SAFETY:
                // * We don't read/write `values` binding after this and values are `ManuallyDrop`,
                // so we have the right to drop/move the values
                unsafe { PtrMut::from(value).promote() }
            })
            .collect();
        // SAFETY:
        // * component_id's are from the same world
        // * `values` was initialized above, so references are valid
        unsafe {
            entity.insert_by_ids(&components, ptrs.into_iter());
        }
    }

    // overwrite Update schedule in the app
    app.add_schedule(schedule);
    app.add_plugins(MinimalPlugins)
        .add_plugins(DiagnosticsPlugin)
        .add_plugins(LogPlugin::default())
        .add_plugins(FrameTimeDiagnosticsPlugin::default())
        .add_plugins(LogDiagnosticsPlugin::filtered(HashSet::from_iter([
            DiagnosticPath::new("fps"),
        ])));
    app.run();
}

pub fn ignore_ambiguity<M1, M2, S1, S2>( &mut self, a: S1, b: S2, ) -> &mut Schedule

where S1: IntoSystemSet<M1>, S2: IntoSystemSet<M2>,

Suppress warnings and errors that would result from systems in these sets having ambiguities (conflicting access but indeterminate order) with systems in set.

pub fn configure_sets<M>( &mut self, sets: impl IntoScheduleConfigs<Interned<dyn SystemSet>, M>, ) -> &mut Schedule

Configures a collection of system sets in this schedule, adding them if they does not exist.

pub fn add_build_pass<T>(&mut self, pass: T) -> &mut Schedule

where T: ScheduleBuildPass,

Add a custom build pass to the schedule.

pub fn remove_build_pass<T>(&mut self)

where T: ScheduleBuildPass,

Remove a custom build pass.

pub fn set_build_settings( &mut self, settings: ScheduleBuildSettings, ) -> &mut Schedule

Changes miscellaneous build settings.

If settings.auto_insert_apply_deferred is false, this clears *_ignore_deferred edge settings configured so far.

Generally this method should be used before adding systems or set configurations to the schedule, not after.

Examples found in repository

tests/ecs/ambiguity_detection.rs (lines 66-71)

fn configure_ambiguity_detection(sub_app: &mut SubApp) {
    let mut schedules = sub_app.world_mut().resource_mut::<Schedules>();
    for (_, schedule) in schedules.iter_mut() {
        schedule.set_build_settings(ScheduleBuildSettings {
            // NOTE: you can change this to `LogLevel::Ignore` to easily see the current number of ambiguities.
            ambiguity_detection: LogLevel::Warn,
            use_shortnames: false,
            ..default()
        });
    }
}

examples/ecs/nondeterministic_system_order.rs (lines 26-29)

fn main() {
    App::new()
        // We can modify the reporting strategy for system execution order ambiguities on a per-schedule basis.
        // You must do this for each schedule you want to inspect; child schedules executed within an inspected
        // schedule do not inherit this modification.
        .edit_schedule(Update, |schedule| {
            schedule.set_build_settings(ScheduleBuildSettings {
                ambiguity_detection: LogLevel::Warn,
                ..default()
            });
        })
        .init_resource::<A>()
        .init_resource::<B>()
        .add_systems(
            Update,
            (
                // This pair of systems has an ambiguous order,
                // as their data access conflicts, and there's no order between them.
                reads_a,
                writes_a,
                // This pair of systems has conflicting data access,
                // but it's resolved with an explicit ordering:
                // the .after relationship here means that we will always double after adding.
                adds_one_to_b,
                doubles_b.after(adds_one_to_b),
                // This system isn't ambiguous with adds_one_to_b,
                // due to the transitive ordering created by our constraints:
                // if A is before B is before C, then A must be before C as well.
                reads_b.after(doubles_b),
                // This system will conflict with all of our writing systems
                // but we've silenced its ambiguity with adds_one_to_b.
                // This should only be done in the case of clear false positives:
                // leave a comment in your code justifying the decision!
                reads_a_and_b.ambiguous_with(adds_one_to_b),
            ),
        )
        // Be mindful, internal ambiguities are reported too!
        // If there are any ambiguities due solely to DefaultPlugins,
        // or between DefaultPlugins and any of your third party plugins,
        // please file a bug with the repo responsible!
        // Only *you* can prevent nondeterministic bugs due to greedy parallelism.
        .add_plugins(DefaultPlugins)
        .run();
}

pub fn get_build_settings(&self) -> ScheduleBuildSettings

Returns the schedule’s current ScheduleBuildSettings.

pub fn get_executor_kind(&self) -> ExecutorKind

Returns the schedule’s current execution strategy.

pub fn set_executor_kind(&mut self, executor: ExecutorKind) -> &mut Schedule

Sets the schedule’s execution strategy.

Examples found in repository

examples/ecs/custom_schedule.rs (line 23)

fn main() {
    let mut app = App::new();

    // Create a new [`Schedule`]. For demonstration purposes, we configure it to use a single threaded executor so that
    // systems in this schedule are never run in parallel. However, this is not a requirement for custom schedules in
    // general.
    let mut custom_update_schedule = Schedule::new(SingleThreadedUpdate);
    custom_update_schedule.set_executor_kind(ExecutorKind::SingleThreaded);

    // Adding the schedule to the app does not automatically run the schedule. This merely registers the schedule so
    // that systems can look it up using the `Schedules` resource.
    app.add_schedule(custom_update_schedule);

    // Bevy `App`s have a `main_schedule_label` field that configures which schedule is run by the App's `runner`.
    // By default, this is `Main`. The `Main` schedule is responsible for running Bevy's main schedules such as
    // `Update`, `Startup` or `Last`.
    //
    // We can configure the `Main` schedule to run our custom update schedule relative to the existing ones by modifying
    // the `MainScheduleOrder` resource.
    //
    // Note that we modify `MainScheduleOrder` directly in `main` and not in a startup system. The reason for this is
    // that the `MainScheduleOrder` cannot be modified from systems that are run as part of the `Main` schedule.
    let mut main_schedule_order = app.world_mut().resource_mut::<MainScheduleOrder>();
    main_schedule_order.insert_after(Update, SingleThreadedUpdate);

    // Adding a custom startup schedule works similarly, but needs to use `insert_startup_after`
    // instead of `insert_after`.
    app.add_schedule(Schedule::new(CustomStartup));

    let mut main_schedule_order = app.world_mut().resource_mut::<MainScheduleOrder>();
    main_schedule_order.insert_startup_after(PreStartup, CustomStartup);

    app.add_systems(SingleThreadedUpdate, single_threaded_update_system)
        .add_systems(CustomStartup, custom_startup_system)
        .add_systems(PreStartup, pre_startup_system)
        .add_systems(Startup, startup_system)
        .add_systems(First, first_system)
        .add_systems(Update, update_system)
        .add_systems(Last, last_system)
        .run();
}

pub fn set_apply_final_deferred( &mut self, apply_final_deferred: bool, ) -> &mut Schedule

Set whether the schedule applies deferred system buffers on final time or not. This is a catch-all in case a system uses commands but was not explicitly ordered before an instance of ApplyDeferred. By default this setting is true, but may be disabled if needed.

pub fn run(&mut self, world: &mut World)

Runs all systems in this schedule on the world, using its current execution strategy.

pub fn initialize( &mut self, world: &mut World, ) -> Result<(), ScheduleBuildError>

Initializes any newly-added systems and conditions, rebuilds the executable schedule, and re-initializes the executor.

Moves all systems and run conditions out of the ScheduleGraph.

pub fn graph(&self) -> &ScheduleGraph

Returns the ScheduleGraph.

Examples found in repository

tests/ecs/ambiguity_detection.rs (line 80)

fn count_ambiguities(sub_app: &SubApp) -> AmbiguitiesCount {
    let schedules = sub_app.world().resource::<Schedules>();
    let mut ambiguities = <HashMap<_, _>>::default();
    for (_, schedule) in schedules.iter() {
        let ambiguities_in_schedule = schedule.graph().conflicting_systems().len();
        ambiguities.insert(schedule.label(), ambiguities_in_schedule);
    }
    AmbiguitiesCount(ambiguities)
}

pub fn graph_mut(&mut self) -> &mut ScheduleGraph

Returns a mutable reference to the ScheduleGraph.

pub fn check_change_ticks(&mut self, check: CheckChangeTicks)

Iterates the change ticks of all systems in the schedule and clamps any older than MAX_CHANGE_AGE. This prevents overflow and thus prevents false positives.

pub fn apply_deferred(&mut self, world: &mut World)

Directly applies any accumulated Deferred system parameters (like Commands) to the world.

Like always, deferred system parameters are applied in the “topological sort order” of the schedule graph. As a result, buffers from one system are only guaranteed to be applied before those of other systems if there is an explicit system ordering between the two systems.

This is used in rendering to extract data from the main world, storing the data in system buffers, before applying their buffers in a different world.

pub fn systems( &self, ) -> Result<impl Iterator<Item = (SystemKey, &Box<dyn System<Out = (), In = ()>>)>, ScheduleNotInitialized>

Returns an iterator over all systems in this schedule.

Note: this method will return ScheduleNotInitialized if the schedule has never been initialized or run.

Examples found in repository

examples/games/stepping.rs (line 131)

fn build_ui(
    mut commands: Commands,
    asset_server: Res<AssetServer>,
    schedules: Res<Schedules>,
    mut stepping: ResMut<Stepping>,
    mut state: ResMut<State>,
) {
    let mut text_spans = Vec::new();
    let mut always_run: Vec<(
        bevy_ecs::intern::Interned<dyn ScheduleLabel + 'static>,
        NodeId,
    )> = Vec::new();

    let Ok(schedule_order) = stepping.schedules() else {
        return;
    };

    // go through the stepping schedules and construct a list of systems for
    // each label
    for label in schedule_order {
        let schedule = schedules.get(*label).unwrap();
        text_spans.push((
            TextSpan(format!("{label:?}\n")),
            TextFont {
                font: asset_server.load(FONT_BOLD),
                ..default()
            },
            TextColor(FONT_COLOR),
        ));

        // grab the list of systems in the schedule, in the order the
        // single-threaded executor would run them.
        let Ok(systems) = schedule.systems() else {
            return;
        };

        for (key, system) in systems {
            // skip bevy default systems; we don't want to step those
            #[cfg(feature = "debug")]
            if system.name().as_string().starts_with("bevy") {
                always_run.push((*label, NodeId::System(key)));
                continue;
            }

            // Add an entry to our systems list so we can find where to draw
            // the cursor when the stepping cursor is at this system
            // we add plus 1 to account for the empty root span
            state
                .systems
                .push((*label, NodeId::System(key), text_spans.len() + 1));

            // Add a text section for displaying the cursor for this system
            text_spans.push((
                TextSpan::new("   "),
                TextFont::default(),
                TextColor(FONT_COLOR),
            ));

            // add the name of the system to the ui
            text_spans.push((
                TextSpan(format!("{}\n", system.name())),
                TextFont::default(),
                TextColor(FONT_COLOR),
            ));
        }
    }

    for (label, node) in always_run.drain(..) {
        stepping.always_run_node(label, node);
    }

    commands.spawn((
        Text::default(),
        SteppingUi,
        Node {
            position_type: PositionType::Absolute,
            top: state.ui_top,
            left: state.ui_left,
            padding: UiRect::all(px(10)),
            ..default()
        },
        BackgroundColor(Color::srgba(1.0, 1.0, 1.0, 0.33)),
        Visibility::Hidden,
        Children::spawn(text_spans),
    ));
}

pub fn systems_len(&self) -> usize

Returns the number of systems in this schedule.

pub fn warnings(&self) -> &[ScheduleBuildWarning]

Returns warnings that were generated during the last call to Schedule::initialize.

Trait Implementations

impl Default for Schedule

fn default() -> Schedule

Creates a schedule with a default label. Only use in situations where you don’t care about the ScheduleLabel. Inserting a default schedule into the world risks overwriting another schedule. For most situations you should use Schedule::new.