docs/bevy/examples/ecs/system_stepping.rs 7.6 K · 208 lines · raw · history

1 //! Demonstrate stepping through systems in order of execution.
2 //!
3 //! To run this example, you must enable the `bevy_debug_stepping` feature.
4
5 use bevy::{ecs::schedule::Stepping, log::LogPlugin, prelude::*};
6
7 fn main() {
8 let mut app = App::new();
9
10 app
11 // to display log messages from Stepping resource
12 .add_plugins(LogPlugin::default())
13 .add_systems(
14 Update,
15 (
16 update_system_one,
17 // establish a dependency here to simplify descriptions below
18 update_system_two.after(update_system_one),
19 update_system_three.after(update_system_two),
20 update_system_four,
21 ),
22 )
23 .add_systems(PreUpdate, pre_update_system);
24
25 // For the simplicity of this example, we directly modify the `Stepping`
26 // resource here and run the systems with `App::update()`. Each call to
27 // `App::update()` is the equivalent of a single frame render when using
28 // `App::run()`.
29 //
30 // In a real-world situation, the `Stepping` resource would be modified by
31 // a system based on input from the user. A full demonstration of this can
32 // be found in the breakout example.
33 println!(
34 r#"
35 Actions: call app.update()
36 Result: All systems run normally"#
37 );
38 app.update();
39
40 println!(
41 r#"
42 Actions: Add the Stepping resource then call app.update()
43 Result: All systems run normally. Stepping has no effect unless explicitly
44 configured for a Schedule, and Stepping has been enabled."#
45 );
46 app.insert_resource(Stepping::new());
47 app.update();
48
49 println!(
50 r#"
51 Actions: Add the Update Schedule to Stepping; enable Stepping; call
52 app.update()
53 Result: Only the systems in PreUpdate run. When Stepping is enabled,
54 systems in the configured schedules will not run unless:
55 * Stepping::step_frame() is called
56 * Stepping::continue_frame() is called
57 * System has been configured to always run"#
58 );
59 let mut stepping = app.world_mut().resource_mut::<Stepping>();
60 stepping.add_schedule(Update).enable();
61 app.update();
62
63 println!(
64 r#"
65 Actions: call Stepping.step_frame(); call app.update()
66 Result: The PreUpdate systems run, and one Update system will run. In
67 Stepping, step means run the next system across all the schedules
68 that have been added to the Stepping resource."#
69 );
70 let mut stepping = app.world_mut().resource_mut::<Stepping>();
71 stepping.step_frame();
72 app.update();
73
74 println!(
75 r#"
76 Actions: call app.update()
77 Result: Only the PreUpdate systems run. The previous call to
78 Stepping::step_frame() only applies for the next call to
79 app.update()/the next frame rendered.
80 "#
81 );
82 app.update();
83
84 println!(
85 r#"
86 Actions: call Stepping::continue_frame(); call app.update()
87 Result: PreUpdate system will run, and all remaining Update systems will
88 run. Stepping::continue_frame() tells stepping to run all systems
89 starting after the last run system until it hits the end of the
90 frame, or it encounters a system with a breakpoint set. In this
91 case, we previously performed a step, running one system in Update.
92 This continue will cause all remaining systems in Update to run."#
93 );
94 let mut stepping = app.world_mut().resource_mut::<Stepping>();
95 stepping.continue_frame();
96 app.update();
97
98 println!(
99 r#"
100 Actions: call Stepping::step_frame() & app.update() four times in a row
101 Result: PreUpdate system runs every time we call app.update(), along with
102 one system from the Update schedule each time. This shows what
103 execution would look like to step through an entire frame of
104 systems."#
105 );
106 for _ in 0..4 {
107 let mut stepping = app.world_mut().resource_mut::<Stepping>();
108 stepping.step_frame();
109 app.update();
110 }
111
112 println!(
113 r#"
114 Actions: Stepping::always_run(Update, update_system_two); step through all
115 systems
116 Result: PreUpdate system and update_system_two() will run every time we
117 call app.update(). We'll also only need to step three times to
118 execute all systems in the frame. Stepping::always_run() allows
119 us to granularly allow systems to run when stepping is enabled."#
120 );
121 let mut stepping = app.world_mut().resource_mut::<Stepping>();
122 stepping.always_run(Update, update_system_two);
123 for _ in 0..3 {
124 let mut stepping = app.world_mut().resource_mut::<Stepping>();
125 stepping.step_frame();
126 app.update();
127 }
128
129 println!(
130 r#"
131 Actions: Stepping::never_run(Update, update_system_two); continue through
132 all systems
133 Result: All systems except update_system_two() will execute.
134 Stepping::never_run() allows us to disable systems while Stepping
135 is enabled."#
136 );
137 let mut stepping = app.world_mut().resource_mut::<Stepping>();
138 stepping.never_run(Update, update_system_two);
139 stepping.continue_frame();
140 app.update();
141
142 println!(
143 r#"
144 Actions: Stepping::set_breakpoint(Update, update_system_two); continue,
145 step, continue
146 Result: During the first continue, pre_update_system() and
147 update_system_one() will run. update_system_four() may also run
148 as it has no dependency on update_system_two() or
149 update_system_three(). Nether update_system_two() nor
150 update_system_three() will run in the first app.update() call as
151 they form a chained dependency on update_system_one() and run
152 in order of one, two, three. Stepping stops system execution in
153 the Update schedule when it encounters the breakpoint for
154 update_system_two().
155 During the step we run update_system_two() along with the
156 pre_update_system().
157 During the final continue pre_update_system() and
158 update_system_three() run."#
159 );
160 let mut stepping = app.world_mut().resource_mut::<Stepping>();
161 stepping.set_breakpoint(Update, update_system_two);
162 stepping.continue_frame();
163 app.update();
164 let mut stepping = app.world_mut().resource_mut::<Stepping>();
165 stepping.step_frame();
166 app.update();
167 let mut stepping = app.world_mut().resource_mut::<Stepping>();
168 stepping.continue_frame();
169 app.update();
170
171 println!(
172 r#"
173 Actions: Stepping::clear_breakpoint(Update, update_system_two); continue
174 through all systems
175 Result: All systems will run"#
176 );
177 let mut stepping = app.world_mut().resource_mut::<Stepping>();
178 stepping.clear_breakpoint(Update, update_system_two);
179 stepping.continue_frame();
180 app.update();
181
182 println!(
183 r#"
184 Actions: Stepping::disable(); app.update()
185 Result: All systems will run. With Stepping disabled, there's no need to
186 call Stepping::step_frame() or Stepping::continue_frame() to run
187 systems in the Update schedule."#
188 );
189 let mut stepping = app.world_mut().resource_mut::<Stepping>();
190 stepping.disable();
191 app.update();
192 }
193
194 fn pre_update_system() {
195 println!("▶ pre_update_system");
196 }
197 fn update_system_one() {
198 println!("▶ update_system_one");
199 }
200 fn update_system_two() {
201 println!("▶ update_system_two");
202 }
203 fn update_system_three() {
204 println!("▶ update_system_three");
205 }
206 fn update_system_four() {
207 println!("▶ update_system_four");
208 }