bevy_startup_tree

Bevy Compatibility:

lib.rs:

Insert dependency trees of startup systems into Bevy Apps.

Define dependency trees of startup systems for a Bevy App with the startup_tree macro. Insert trees into an App with the AddStartupTree::add_startup_tree extension method. It is strongly recommended that the macro is used to generate the data structure that is consumed by add_startup_tree.

This is useful in scenarios where the startup logic is complex and would benefit from being broken up into multiple systems. Some of this startup logic can be run in parallel; others may require that certain systems run in a particular order. For example, a system that spawns a complex bevy_ui can get very large, deeply nested, and difficult to maintain. Such a system can be divided into multiple that work together to create the complex entity hierarchy. Systems that spawn children entities must run after the one that spawns the parent; this is where bevy_startup_tree becomes useful.

Bevy Compatibility

Behavior

The systems that make up a startup tree, or nodes, are grouped by depth. The startup_tree macro generates a 2-D array where each row with index i contains the nodes at depth i in the tree. This 2-D array is consumed by add_startup_tree where each depth sub-array is combined into a SystemSet.

startup_tree! {
    sys_1_a,
    sys_1_b => sys_2
}

This macro invocation would generate the following 2-D array:

 [ [sys_1_a, sys_1_b], [sys_2] ]
 

Note that there are two sub-arrays: one for the nodes at depth 0 and one for depth 1.

The sets for each sub-array run in order during the Startup schedule. Thus, the system sets inserted into the Startup schedule for the above tree would be:

• Depth 0 tree set
• Depth 0 tree flush set
• Depth 1 tree set
• Depth 1 tree flush set

Example

The following is an example Bevy App with a startup tree. Note that the app will go through the startup phase, run a single frame cycle, and then exit.

use bevy::{log::LogPlugin, prelude::*};
use bevy_startup_tree::{startup_tree, AddStartupTree};

fn main() {
    App::new()
        .add_plugins((TaskPoolPlugin::default(), LogPlugin::default()))
        .add_systems(PreStartup, begin)
        .add_startup_tree(startup_tree! {
            sys_1_a,
            sys_1_b => sys_2_a,
            sys_1_c => {
                sys_2_b,
                sys_2_c => sys_3_a,
            },
        })
        .add_systems(PostStartup, end)
        .run();
}

fn begin() { info!("[Begin]"); }
fn sys_1_a() { info!("1.a"); }
fn sys_1_b() { info!("1.b"); }
fn sys_1_c() { info!("1.c"); }
fn sys_2_a() { info!("2.a"); }
fn sys_2_b() { info!("2.b"); }
fn sys_2_c() { info!("2.c"); }
fn sys_3_a() { info!("3.a"); }
fn end() { info!("[End]"); }

Output

 2023-01-08T19:38:41.664766Z  INFO example_app: [Begin]
 2023-01-08T19:38:41.664906Z  INFO example_app: 1.b
 2023-01-08T19:38:41.664937Z  INFO example_app: 1.c
 2023-01-08T19:38:41.664959Z  INFO example_app: 1.a
 2023-01-08T19:38:41.665104Z  INFO example_app: 2.c
 2023-01-08T19:38:41.665133Z  INFO example_app: 2.a
 2023-01-08T19:38:41.665141Z  INFO example_app: 2.b
 2023-01-08T19:38:41.665204Z  INFO example_app: 3.a
 2023-01-08T19:38:41.665264Z  INFO example_app: [End]
 

Note that all of the logs for a depth (those with the same number) are grouped together because these systems belong to the same set. The sets run in order, causing the numbers to be sorted. However, the systems within a set do not, causing the letters for a given number to be unordered.

The begin and end systems demonstrates when the tree runs during startup. To run a system before the tree, insert it into the PreStartup schedule. To run a system after the tree, insert it into the PostStartup schedule.