docs/bevy/examples/showcase/stepping.rs 8.4 K · 276 lines · raw · history

1 use bevy::{app::MainScheduleOrder, ecs::schedule::*, prelude::*};
2
3 /// Independent [`Schedule`] for stepping systems.
4 ///
5 /// The stepping systems must run in their own schedule to be able to inspect
6 /// all the other schedules in the [`App`]. This is because the currently
7 /// executing schedule is removed from the [`Schedules`] resource while it is
8 /// being run.
9 #[derive(Debug, Hash, PartialEq, Eq, Clone, ScheduleLabel)]
10 struct DebugSchedule;
11
12 /// Plugin to add a stepping UI to an example
13 #[derive(Default)]
14 pub struct SteppingPlugin {
15 schedule_labels: Vec<InternedScheduleLabel>,
16 top: Val,
17 left: Val,
18 }
19
20 impl SteppingPlugin {
21 /// add a schedule to be stepped when stepping is enabled
22 pub fn add_schedule(mut self, label: impl ScheduleLabel) -> SteppingPlugin {
23 self.schedule_labels.push(label.intern());
24 self
25 }
26
27 /// Set the location of the stepping UI when activated
28 pub fn at(self, left: Val, top: Val) -> SteppingPlugin {
29 SteppingPlugin { top, left, ..self }
30 }
31 }
32
33 impl Plugin for SteppingPlugin {
34 fn build(&self, app: &mut App) {
35 app.add_systems(Startup, build_stepping_hint);
36 if cfg!(not(feature = "bevy_debug_stepping")) {
37 return;
38 }
39
40 // create and insert our debug schedule into the main schedule order.
41 // We need an independent schedule so we have access to all other
42 // schedules through the `Stepping` resource
43 app.init_schedule(DebugSchedule);
44 let mut order = app.world_mut().resource_mut::<MainScheduleOrder>();
45 order.insert_after(Update, DebugSchedule);
46
47 // create our stepping resource
48 let mut stepping = Stepping::new();
49 for label in &self.schedule_labels {
50 stepping.add_schedule(*label);
51 }
52 app.insert_resource(stepping);
53
54 // add our startup & stepping systems
55 app.insert_resource(State {
56 ui_top: self.top,
57 ui_left: self.left,
58 systems: Vec::new(),
59 })
60 .add_systems(
61 DebugSchedule,
62 (
63 build_ui.run_if(not(initialized)),
64 handle_input,
65 update_ui.run_if(initialized),
66 )
67 .chain(),
68 );
69 }
70 }
71
72 /// Struct for maintaining stepping state
73 #[derive(Resource, Debug)]
74 struct State {
75 // vector of schedule/node id -> text index offset
76 systems: Vec<(InternedScheduleLabel, NodeId, usize)>,
77
78 // ui positioning
79 ui_top: Val,
80 ui_left: Val,
81 }
82
83 /// condition to check if the stepping UI has been constructed
84 fn initialized(state: Res<State>) -> bool {
85 !state.systems.is_empty()
86 }
87
88 const FONT_COLOR: Color = Color::srgb(0.2, 0.2, 0.2);
89 const FONT_BOLD: &str = "fonts/FiraSans-Bold.ttf";
90
91 #[derive(Component)]
92 struct SteppingUi;
93
94 /// Construct the stepping UI elements from the [`Schedules`] resource.
95 ///
96 /// This system may run multiple times before constructing the UI as all of the
97 /// data may not be available on the first run of the system. This happens if
98 /// one of the stepping schedules has not yet been run.
99 fn build_ui(
100 mut commands: Commands,
101 asset_server: Res<AssetServer>,
102 schedules: Res<Schedules>,
103 mut stepping: ResMut<Stepping>,
104 mut state: ResMut<State>,
105 ) {
106 let mut text_spans = Vec::new();
107 let mut always_run: Vec<(
108 bevy_ecs::intern::Interned<dyn ScheduleLabel + 'static>,
109 NodeId,
110 )> = Vec::new();
111
112 let Ok(schedule_order) = stepping.schedules() else {
113 return;
114 };
115
116 // go through the stepping schedules and construct a list of systems for
117 // each label
118 for label in schedule_order {
119 let schedule = schedules.get(*label).unwrap();
120 text_spans.push((
121 TextSpan(format!("{label:?}\n")),
122 TextFont {
123 font: asset_server.load(FONT_BOLD).into(),
124 ..default()
125 },
126 TextColor(FONT_COLOR),
127 ));
128
129 // grab the list of systems in the schedule, in the order the
130 // single-threaded executor would run them.
131 let Ok(systems) = schedule.systems() else {
132 return;
133 };
134
135 for (key, system) in systems {
136 // skip bevy default systems; we don't want to step those
137 #[cfg(feature = "debug")]
138 if system.name().as_string().starts_with("bevy") {
139 always_run.push((*label, NodeId::System(key)));
140 continue;
141 }
142
143 // Add an entry to our systems list so we can find where to draw
144 // the cursor when the stepping cursor is at this system
145 // we add plus 1 to account for the empty root span
146 state
147 .systems
148 .push((*label, NodeId::System(key), text_spans.len() + 1));
149
150 // Add a text section for displaying the cursor for this system
151 text_spans.push((
152 TextSpan::new(" "),
153 TextFont::default(),
154 TextColor(FONT_COLOR),
155 ));
156
157 // add the name of the system to the ui
158 text_spans.push((
159 TextSpan(format!("{}\n", system.name())),
160 TextFont::default(),
161 TextColor(FONT_COLOR),
162 ));
163 }
164 }
165
166 for (label, node) in always_run.drain(..) {
167 stepping.always_run_node(label, node);
168 }
169
170 commands.spawn((
171 Text::default(),
172 SteppingUi,
173 Node {
174 position_type: PositionType::Absolute,
175 top: state.ui_top,
176 left: state.ui_left,
177 padding: UiRect::all(px(10)),
178 ..default()
179 },
180 BackgroundColor(Color::srgba(1.0, 1.0, 1.0, 0.33)),
181 Visibility::Hidden,
182 Children::spawn(text_spans),
183 ));
184 }
185
186 fn build_stepping_hint(mut commands: Commands) {
187 let hint_text = if cfg!(feature = "bevy_debug_stepping") {
188 "Press ` to toggle stepping mode (S: step system, Space: step frame)"
189 } else {
190 "Bevy was compiled without stepping support. Run with `--features=bevy_debug_stepping` to enable stepping."
191 };
192 info!("{}", hint_text);
193 // stepping description box
194 commands.spawn((
195 Text::new(hint_text),
196 TextFont {
197 font_size: FontSize::Px(15.0),
198 ..default()
199 },
200 TextColor(FONT_COLOR),
201 Node {
202 position_type: PositionType::Absolute,
203 bottom: px(5),
204 left: px(5),
205 ..default()
206 },
207 ));
208 }
209
210 fn handle_input(keyboard_input: Res<ButtonInput<KeyCode>>, mut stepping: ResMut<Stepping>) {
211 if keyboard_input.just_pressed(KeyCode::Slash) {
212 info!("{:#?}", stepping);
213 }
214 // grave key to toggle stepping mode for the FixedUpdate schedule
215 if keyboard_input.just_pressed(KeyCode::Backquote) {
216 if stepping.is_enabled() {
217 stepping.disable();
218 debug!("disabled stepping");
219 } else {
220 stepping.enable();
221 debug!("enabled stepping");
222 }
223 }
224
225 if !stepping.is_enabled() {
226 return;
227 }
228
229 // space key will step the remainder of this frame
230 if keyboard_input.just_pressed(KeyCode::Space) {
231 debug!("continue");
232 stepping.continue_frame();
233 } else if keyboard_input.just_pressed(KeyCode::KeyS) {
234 debug!("stepping frame");
235 stepping.step_frame();
236 }
237 }
238
239 fn update_ui(
240 mut commands: Commands,
241 state: Res<State>,
242 stepping: Res<Stepping>,
243 ui: Single<(Entity, &Visibility), With<SteppingUi>>,
244 mut writer: TextUiWriter,
245 ) {
246 // ensure the UI is only visible when stepping is enabled
247 let (ui, vis) = *ui;
248 match (vis, stepping.is_enabled()) {
249 (Visibility::Hidden, true) => {
250 commands.entity(ui).insert(Visibility::Inherited);
251 }
252 (Visibility::Hidden, false) | (_, true) => (),
253 (_, false) => {
254 commands.entity(ui).insert(Visibility::Hidden);
255 }
256 }
257
258 // if we're not stepping, there's nothing more to be done here.
259 if !stepping.is_enabled() {
260 return;
261 }
262
263 // no cursor means stepping isn't enabled, so we're done here
264 let Some((cursor_schedule, cursor_system)) = stepping.cursor() else {
265 return;
266 };
267
268 for (schedule, system, text_index) in &state.systems {
269 let mark = if &cursor_schedule == schedule && *system == cursor_system {
270 "-> "
271 } else {
272 " "
273 };
274 *writer.text(ui, *text_index) = mark.to_string();
275 }
276 }