Understanding StartupSet

[rowanfr]

I'm currently trying to learn how to use Base Sets, in particular StartupSet. On the documentation for bevy 0.10.1 it states that it runs once at the beginning of my app but when I use it in my code as shown below:

use bevy::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_system(command_spawn.in_base_set(StartupSet::Startup))
        .add_system(query.in_base_set(CoreSet::Update))
        .run();
}
#[derive(Component)]
struct num(u32);

fn command_spawn(
    mut commands: Commands,
) {
    commands.spawn(num(12));
    println!("Order check")
}

fn query(
    query: Query<&num>
){
    println!("query iter len: {}",query.iter().len());
}

Despite using StartupSet::Startup with the documentation stating that it "Runs once when an App starts up", it repeatedly creates new entities and prints to the console "Order Check". Thankfully the order remains consistent with the output being:

Order check
query iter len: 1
Order check
query iter len: 2
...

However I'm trying to understand if this system is repeatedly called because I did something wrong in using "StartupSet::Startup". Just to clarify this isn't a question of how to ensure that something only runs once at startup as ".add_startup_system()" works perfectly for that purpose, this is more to trying to understand Base Sets along with how to use them to schedule properly.

[nicopap]

base sets are a bit of a odd one. The concept will be completely revamped in 0.11.

But to answer your question, let's take a look at the implementation of add_startup_system

    pub fn add_startup_system<M>(&mut self, system: impl IntoSystemConfig<M>) -> &mut Self {
        self.add_system(system.in_schedule(CoreSchedule::Startup))
    }

It seems that it uses .in_schedule instead of .in_base_set. So, in bevy 0.10, the startup schedule is completely distinct from the default schedule.

If you use add_system(sys1), you add sys1 to the main schedule, the one that runs every frame. Even if you label it with the .in_base_set(StartupSet::Startup). Therefore sys1 runs every frame.

Why can you add sys1 to StartupSet::Startup inside the main schedule then? To me it's surprising as well. So I took a look.

First let's do the dictionary game and define our concepts, so we are on the same page:

• Labels are metadata you add to systems.
• Sets are groups of systems. .in_set adds a label to a system to tell the schedule what set it is part of.
• Base Sets are groups of systems, that cannot overlap (ie: no system can be in two different Base Sets), .in_base_set works like .in_set.
• Schedules are collections of systems with metadata.

Sets and base sets by themselves are useless. In fact, they don't even exist! We just labelled systems with names. It's only thanks to Schedule that those make sense.

Think of a jar. Your systems are balls. You can paint a ball yellow, green or blue before putting it in the jar.

You now have three groups of balls in your jar: all the yellow balls, all the green balls and all the blue balls. Yet, you never added a "group" of balls in the jar.

Schedules themselves do not have sets or base sets. They only infer them from all the systems it has.
So if you add a system in the StartupSet::Startup set in the main schedule, you will also add the StartupSet::Startup to it! But it will only contain that system you added. While all its friends in the startup schedule will never see it.

A schedule has no way to tell whether a set "should" be part of it, it can only see which sets its system are said to be part of. You can put pink balls in your jar labelled "only yellow, green or blue balls" if you will.

---

On a more practical notes, what's the point of sets?

Remember that you can order systems with regard to each other:

app.add_system(sys1.after(sys2)).add_system(sys2)

It happens you can also order system sets. This means that an entire group of systems will be ordered with regard to another entire group of systems, much better than individually tagging and explicitly saying "a1 after b1", "a1 after b2", "a2 after b1"…

Schedule has a run method that allows to execute all the systems in the specified order. Unlike BaseSet and SystemSet which really are just labels to put on systems.

[rowanfr]

Thank you for the detailed explanation. After looking through the App documentation I'm fairly certain the base sets were added to the schedule though the use of the implicit add_default_schedules section which is why they maintain order between themselves but the systems not being in the appropriate CoreSchedule or the CoreSchedule not being set makes Bevy presume that they should all be in CoreSchedule::Main by default. The documentation for App (App) state:

default_schedule_label: Box<dyn ScheduleLabel + 'static, Global>
The schedule that systems are added to by default.
This is initially set to CoreSchedule::Main.

If one places the base sets in the appropriate schedule they retain the expected execution order as shown in executing the code below.

use bevy::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_system(command_spawn.in_schedule(CoreSchedule::Startup).in_base_set(StartupSet::Startup))
        .add_system(post_startup.in_schedule(CoreSchedule::Startup).in_base_set(StartupSet::PostStartup))
        .add_system(query.in_base_set(CoreSet::Update))
        .run();
}
#[derive(Component)]
struct num(u32);

fn command_spawn(
    mut commands: Commands,
) {
    commands.spawn(num(12));
    println!("Order check StartupSet::Startup")
}

fn post_startup(){
    println!("Order check StartupSet::PostStartup")
}

fn query(
    query: Query<&num>
){
    println!("query iter len: {}",query.iter().len());
}

Which prints:

Order check StartupSet::Startup
Order check StartupSet::PostStartup
query iter len: 1
query iter len: 1
...

Seperatly I could only get the initial print statement "Order check StartupSet::Startup" to register in the console by using the bevy/dynamic_linking feature, but that's not really in the scope of this discussion and I think the core issue has been resolved. The core of this issue was how to ensure that StartupSet is executed at the beginning of each app run and why it wasn't functioning as expected, both of which have been resolved.