From cd9c39b70c40e9caf49c9f7d4338c7dcea8f742b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81lex=20Rom=C3=A1n=20N=C3=BA=C3=B1ez?=
 <eirexe@eirteam.moe>
Date: Mon, 14 Sep 2026 20:03:47 +0000
Subject: [PATCH] Add debug frame stepping (#5)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reviewed-on: https://git.eirexe.moe/EIREXE/shinespark/pulls/5
Co-authored-by: Álex Román Núñez <eirexe@eirteam.moe>
---
 .gitea/workflows/ci.yml |   2 +-
 src/debug_tools.rs      | 101 ++++++++++++++++++++++++++++++++++++++--
 2 files changed, 99 insertions(+), 4 deletions(-)

diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml
index e78cfe8..ef57c78 100644
--- a/.gitea/workflows/ci.yml
+++ b/.gitea/workflows/ci.yml
@@ -10,7 +10,7 @@ on:
 jobs:
   build-and-test:
     runs-on: ubuntu-latest
-    timeout-minutes: 15
+    timeout-minutes: 30
     steps:
       - name: Check out source
         uses: actions/checkout@v4
diff --git a/src/debug_tools.rs b/src/debug_tools.rs
index 9ad23db..28e27f2 100644
--- a/src/debug_tools.rs
+++ b/src/debug_tools.rs
@@ -3,11 +3,12 @@
 use std::{collections::HashMap, time::Duration};
 
 use bevy::{
+    input::InputSystems,
     prelude::*,
     settings::{ReflectSettingsGroup, SaveSettingsDeferred, SettingsGroup},
 };
 use bevy_egui::{EguiContexts, EguiPrimaryContextPass, egui};
-use bevy_ggrs::RollbackFrameRate;
+use bevy_ggrs::{RollbackFrameRate, RunGgrsSystems};
 use enum_cycling::EnumCycle;
 use enum_cycling_derive::EnumCycle;
 
@@ -114,6 +115,7 @@ enum DebugFlag {
     Hurtboxes,
     Camera,
     DrawThroughGeometry,
+    FrameStepping,
 }
 
 #[derive(Clone, Copy)]
@@ -174,6 +176,10 @@ const WORLD_MENU: &[DebugMenuEntry] = &[
     DebugMenuEntry::GameSpeed {
         label: "Game speed",
     },
+    DebugMenuEntry::Toggle {
+        label: "Frame stepping",
+        flag: DebugFlag::FrameStepping,
+    },
 ];
 
 const DIAGNOSTICS_MENU: &[DebugMenuEntry] = &[DebugMenuEntry::Toggle {
@@ -233,6 +239,8 @@ pub struct DebugSettings {
     selections: Vec<usize>,
     #[reflect(ignore)]
     pub player_rows: HashMap<usize, [FighterDebugRowKind; PLAYER_DEBUG_ROW_COUNT]>,
+    #[reflect(ignore)]
+    pub frame_stepping: bool,
     pub network: bool,
     pub ecb: bool,
     pub stage_collision: bool,
@@ -253,6 +261,7 @@ impl Default for DebugSettings {
             pages: vec![DebugMenuPage::Static(ROOT_MENU)],
             selections: vec![0],
             player_rows: HashMap::new(),
+            frame_stepping: false,
             network: false,
             ecb: false,
             stage_collision: false,
@@ -325,6 +334,7 @@ impl DebugSettings {
             DebugFlag::Hurtboxes => self.hurtboxes,
             DebugFlag::DrawThroughGeometry => self.draw_through_geometry,
             DebugFlag::Camera => self.camera,
+            DebugFlag::FrameStepping => self.frame_stepping,
         }
     }
 
@@ -340,6 +350,7 @@ impl DebugSettings {
                 self.draw_through_geometry = !self.draw_through_geometry
             }
             DebugFlag::Camera => self.camera = !self.camera,
+            DebugFlag::FrameStepping => self.frame_stepping = !self.frame_stepping,
         }
     }
 
@@ -356,9 +367,25 @@ impl DebugSettings {
 
 pub struct DebugToolsPlugin;
 
+#[derive(Resource, Default)]
+struct FrameStepState {
+    requested: bool,
+    time_backup: Option<Time>,
+    last_step_time: Time
+}
+
 impl Plugin for DebugToolsPlugin {
     fn build(&self, app: &mut App) {
         app.init_resource::<DebugSettings>()
+            .init_resource::<FrameStepState>()
+            .add_systems(
+                PreUpdate,
+                prepare_frame_step
+                    .after(InputSystems)
+                    .before(RunGgrsSystems)
+                    .run_if(in_state(AppState::InMatch)),
+            )
+            .add_systems(PreUpdate, restore_frame_step_time.after(RunGgrsSystems))
             .add_systems(
                 Update,
                 (handle_palette_input, sync_gizmo_depth_bias)
@@ -391,6 +418,61 @@ fn queue_settings_save(commands: &mut Commands) {
     commands.queue(SaveSettingsDeferred(Duration::from_secs_f32(0.1)));
 }
 
+fn frame_step_duration(frame_rate: usize) -> Duration {
+    Duration::from_nanos(1_000_000_000u64 / frame_rate as u64)
+}
+
+fn prepare_frame_step(
+    settings: Res<DebugSettings>,
+    gamepads: Query<&Gamepad>,
+    key: Res<ButtonInput<KeyCode>>,
+    mut state: ResMut<FrameStepState>,
+    mut time: ResMut<Time>,
+    frame_rate: Res<RollbackFrameRate>,
+) {
+    if !settings.frame_stepping {
+        state.requested = false;
+        return;
+    }
+
+    let pressed = gamepads
+        .iter()
+        .any(|gamepad| gamepad.pressed(GamepadButton::DPadDown));
+
+    let just_pressed = gamepads
+            .iter()
+            .any(|gamepad| gamepad.just_pressed(GamepadButton::DPadDown));
+
+    let just_pressed = key.just_pressed(KeyCode::F4) || just_pressed;
+    let pressed = key.pressed(KeyCode::F4) || pressed;
+
+    if just_pressed {
+        state.last_step_time = time.clone();
+    }
+
+    let can_repress = pressed && (time.elapsed() - state.last_step_time.elapsed()).as_millis() > 500;
+
+    if !settings.menu_open && (just_pressed || can_repress)
+    {
+        state.requested = true;
+    }
+
+    state.time_backup = Some(*time);
+    let delta = if state.requested {
+        frame_step_duration(**frame_rate)
+    } else {
+        Duration::ZERO
+    };
+    time.advance_by(delta);
+}
+
+fn restore_frame_step_time(mut state: ResMut<FrameStepState>, mut time: ResMut<Time>) {
+    if let Some(backup) = state.time_backup.take() {
+        *time = backup;
+        state.requested = false;
+    }
+}
+
 fn activate_selected(
     settings: &mut DebugSettings,
     page_len: usize,
@@ -408,7 +490,9 @@ fn activate_selected(
             }
             DebugMenuEntry::Toggle { flag, .. } => {
                 settings.toggle_flag(flag);
-                queue_settings_save(commands);
+                if !matches!(flag, DebugFlag::FrameStepping) {
+                    queue_settings_save(commands);
+                }
             }
             DebugMenuEntry::Submenu { entries, .. } => {
                 settings.push_page(DebugMenuPage::Static(entries));
@@ -623,7 +707,9 @@ fn draw_palette(
                                     let mut value = settings.flag(*flag);
                                     if ui.checkbox(&mut value, *label).changed() {
                                         settings.toggle_flag(*flag);
-                                        queue_settings_save(&mut commands);
+                                        if !matches!(flag, DebugFlag::FrameStepping) {
+                                            queue_settings_save(&mut commands);
+                                        }
                                     }
                                 }
                                 DebugMenuEntry::Submenu { label, .. }
@@ -839,6 +925,15 @@ mod tests {
         assert_eq!(GameSpeedDebug::Quarter.frame_rate(), 15);
     }
 
+    #[test]
+    fn frame_stepping_is_disabled_by_default_and_uses_game_speed_timestep() {
+        let settings = DebugSettings::default();
+
+        assert!(!settings.frame_stepping);
+        assert_eq!(frame_step_duration(60), Duration::from_nanos(16_666_666));
+        assert_eq!(frame_step_duration(30), Duration::from_nanos(33_333_333));
+    }
+
     #[test]
     fn empty_player_list_does_not_activate() {
         let mut settings = DebugSettings::default();