Fix various runtime shenanigans

## Summary
- add a rollback-tracked `FighterSurfaceState` as the single source of truth for stage contact
- move active stage line ownership out of individual grounded fighter states
- update landing, airborne motion, ledge departure, hit reactions, and debug save states to maintain surface contact
- add tests for contact lifecycle, connected-segment traversal, and ledge departure

Reviewed-on: #60
Co-authored-by: Álex Román Núñez <eirexe@eirteam.moe>

src/fighter/attack/mod.rs

@@ -605,7 +605,6 @@ impl Plugin for FighterAttackPlugin {
                 intersect_attacks_with_hurtboxes,
             )
                 .chain()
-                .after(crate::fighter::baked_animation::update_fighter_bone_matrices)
                 .in_set(GameplaySet::Attacks),
         );
     }

src/fighter/baked_animation/mod.rs

@@ -219,6 +219,7 @@ mod tests {
         second.translate(FGVec3::lit("0", "3", "0"));
         let mut matrices = FighterBoneMatrices::default();
         matrices.set_pose(
+            AnimKind::Wait,
             &["root".into(), "hand".into()],
             &[None, Some(0)],
             &[first, second],
@@ -239,6 +240,7 @@ mod tests {
         hand.translate(FGVec3::lit("0", "3", "0"));
         let mut matrices = FighterBoneMatrices::default();
         matrices.set_pose(
+            AnimKind::Wait,
             &["root".into(), "hand".into()],
             &[None, Some(0)],
             &[root, hand],
@@ -266,9 +268,9 @@ mod tests {
         let parents = [None, Some(0)];
         let pose = [FixedMat4::IDENTITY, FixedMat4::IDENTITY];
 
-        matrices.set_pose(&names, &parents, &pose, FGi32::ONE);
+        matrices.set_pose(AnimKind::Wait, &names, &parents, &pose, FGi32::ONE);
         let capacities = matrices.buffer_capacities();
-        matrices.set_pose(&names, &parents, &pose, FGi32::ONE);
+        matrices.set_pose(AnimKind::Wait, &names, &parents, &pose, FGi32::ONE);
 
         assert_eq!(capacities, matrices.buffer_capacities());
     }
@@ -281,6 +283,7 @@ mod tests {
         hand.translate(FGVec3::lit("0", "2", "0"));
         let mut matrices = FighterBoneMatrices::default();
         matrices.set_pose(
+            AnimKind::Wait,
             &["root".into(), "hand".into()],
             &[None, Some(0)],
             &[root, hand],

src/fighter/baked_animation/runtime.rs

@@ -71,6 +71,7 @@ pub struct FighterBoneMatrices {
     local_matrices: Vec<FixedMat4>,
     previous_local_matrices: Vec<FixedMat4>,
     model_matrices: Vec<Option<FixedMat4>>,
+    presentation_kind: Option<AnimKind>,
 }
 
 #[derive(Component, Clone, Debug, Default)]
@@ -88,6 +89,12 @@ impl FighterBoneMatrices {
         ]
     }
 
+    pub fn get_by_idx(&self, index: usize) -> Option<(FixedMat4, FixedMat4)> {
+        Some((
+            *self.previous_frame_matrices.get(index)?,
+            *self.matrices.get(index)?,
+        ))
+    }
     pub fn get(&self, bone: &str) -> Option<(FixedMat4, FixedMat4)> {
         let index = self.bone_names.iter().position(|name| name == bone)?;
         Some((
@@ -132,6 +139,7 @@ impl FighterBoneMatrices {
     }
     pub(super) fn set_pose(
         &mut self,
+        kind: AnimKind,
         bone_names: &[String],
         parents: &[Option<usize>],
         local: &[FixedMat4],
@@ -160,6 +168,7 @@ impl FighterBoneMatrices {
         self.previous_local_matrices.reserve(local.len());
         self.model_matrices.reserve(local.len());
         std::mem::swap(&mut self.matrices, &mut self.previous_frame_matrices);
+        let animation_changed = self.presentation_kind != Some(kind);
         std::mem::swap(&mut self.local_matrices, &mut self.previous_local_matrices);
         self.local_matrices.clear();
         self.local_matrices.extend_from_slice(local);
@@ -183,6 +192,14 @@ impl FighterBoneMatrices {
                 model_scale.mul(matrix.expect("baked bone hierarchy should be valid"))
             }),
         );
+        // A state transition is a discontinuity, not an animation frame to
+        // interpolate from the previous clip.  Keep the presentation pose at
+        // the new clip's first/current frame immediately.
+        if animation_changed {
+            self.previous_local_matrices
+                .clone_from(&self.local_matrices);
+        }
+        self.presentation_kind = Some(kind);
     }
 }
 
@@ -212,6 +229,7 @@ pub fn update_fighter_bone_matrices(
             .get(&fighter.manifest)
             .expect("fighter manifest should be loaded before the match starts");
         matrices.set_pose(
+            frame.kind,
             &baked.bone_names,
             &baked.parents,
             pose,

src/fighter/debug.rs

@@ -27,6 +27,7 @@ use crate::game_settings::GameSettings;
 use crate::input::FighterInput;
 use crate::math::int::FGi32;
 use crate::math::vec::FGVec2;
+use crate::math::vec3::FGVec3;
 use crate::player::Player;
 
 pub fn debug_draw_ecb(
@@ -39,6 +40,12 @@ pub fn debug_draw_ecb(
     mut gizmos: Gizmos,
 ) {
     for (ecb, trf, ecb_prev, trf_prev) in ecbs {
+        gizmos.cross(
+            FGVec3::new(trf.0.x, trf.0.y, FGi32::ZERO).to_vec3(),
+            2.0,
+            bevy::color::palettes::css::BLUE,
+        );
+
         let transformed =
             ecb.to_3d_lineloop(Transform::from_xyz(trf.x.to_num(), trf.y.to_num(), 0.0));
         gizmos.lineloop(transformed, YELLOW);
@@ -153,10 +160,17 @@ pub fn fighter_debug(
     Ok(())
 }
 
-pub fn animation_debug(query: Query<(&GlobalTransform, &FighterBoneMatrices)>, mut gizmos: Gizmos) {
-    for (global_transform, matrices) in query {
-        let (_, rotation, translation) = global_transform.to_scale_rotation_translation();
-        let marker_transform = Transform::from_translation(translation).with_rotation(rotation);
+pub fn animation_debug(
+    query: Query<(
+        &FighterTranslation,
+        &FighterFacingDirection,
+        &FighterBoneMatrices,
+    )>,
+    mut gizmos: Gizmos,
+) {
+    for (global_transform, facing_dir, matrices) in query {
+        let global_transform = global_transform.get_3d_transform(facing_dir);
+        let marker_transform = global_transform.to_mat4();
         for (_, matrix) in matrices.iter() {
             let pos = marker_transform.transform_point(Vec3::new(
                 matrix.cols[3][0].to_num(),

src/fighter/ecb.rs

@@ -1,28 +1,44 @@
 use bevy::prelude::*;
 
-use crate::math::{int::FGi32, vec::FGVec2};
+use crate::{
+    fighter::{
+        FighterFacingDirection, FighterSurfaceState, FighterTranslation,
+        baked_animation::FighterBoneMatrices,
+    }, math::{int::FGi32, vec::FGVec2},
+};
 
 /// Environment collision box: the diamond used to resolve a fighter against
 /// the stage. Purely geometry — the collision response lives in
 /// [`super::collision`].
-#[derive(Component, Debug, Clone, Copy, Hash)]
+#[derive(Component, Debug, Clone, Copy, Hash, Default)]
 #[require(FighterPreviousECB)]
 pub struct FighterECB {
-    pub vertical_half: FGi32,
-    pub horizontal_half: FGi32,
+    pub top: FGVec2,
+    pub bottom: FGVec2,
+    pub left: FGVec2,
+    pub right: FGVec2,
+}
+
+#[derive(Component, Debug, Clone)]
+pub struct FighterECBBoneIndices {
+    pub indices: Vec<usize>,
 }
 
 #[derive(Component, Debug, Clone, Copy, Default, Hash)]
 pub struct FighterPreviousECB {
-    pub vertical_half: FGi32,
-    pub horizontal_half: FGi32,
+    pub top: FGVec2,
+    pub bottom: FGVec2,
+    pub left: FGVec2,
+    pub right: FGVec2,
 }
 
 impl From<FighterECB> for FighterPreviousECB {
     fn from(ecb: FighterECB) -> Self {
         Self {
-            vertical_half: ecb.vertical_half,
-            horizontal_half: ecb.horizontal_half,
+            top: ecb.top,
+            bottom: ecb.bottom,
+            left: ecb.left,
+            right: ecb.right,
         }
     }
 }
@@ -35,53 +51,84 @@ pub fn snapshot_fighter_ecb(fighters: Query<(&FighterECB, &mut FighterPreviousEC
 
 impl FighterECB {
     pub fn to_3d_lineloop(&self, trf: Transform) -> [Vec3; 4] {
-        let rel_up = trf.transform_point(Vec3::new(
-            0.0,
-            (self.vertical_half + self.vertical_half).to_num(),
-            0.0,
-        ));
-        let rel_down = trf.transform_point(Vec3::new(0.0, 0.0, 0.0));
-        let rel_left = trf.transform_point(Vec3::new(
-            (-self.horizontal_half).to_num(),
-            self.vertical_half.to_num(),
-            0.0,
-        ));
-        let rel_right = trf.transform_point(Vec3::new(
-            self.horizontal_half.to_num(),
-            self.vertical_half.to_num(),
-            0.0,
-        ));
-        [rel_up, rel_right, rel_down, rel_left]
+        [self.top, self.right, self.bottom, self.left]
+            .map(|point| trf.transform_point(Vec3::new(point.x.to_num(), point.y.to_num(), 0.0)))
     }
 
     pub fn get_bottom_point(&self) -> FGVec2 {
-        FGVec2::new(FGi32::ZERO, FGi32::ZERO)
+        self.bottom
     }
 }
 
 impl FighterPreviousECB {
     pub fn to_3d_lineloop(&self, trf: Transform) -> [Vec3; 4] {
-        let rel_up = trf.transform_point(Vec3::new(
-            0.0,
-            (self.vertical_half + self.vertical_half).to_num(),
-            0.0,
-        ));
-        let rel_down = trf.transform_point(Vec3::new(0.0, 0.0, 0.0));
-        let rel_left = trf.transform_point(Vec3::new(
-            (-self.horizontal_half).to_num(),
-            self.vertical_half.to_num(),
-            0.0,
-        ));
-        let rel_right = trf.transform_point(Vec3::new(
-            self.horizontal_half.to_num(),
-            self.vertical_half.to_num(),
-            0.0,
-        ));
-        [rel_up, rel_right, rel_down, rel_left]
+        [self.top, self.right, self.bottom, self.left]
+            .map(|point| trf.transform_point(Vec3::new(point.x.to_num(), point.y.to_num(), 0.0)))
     }
 
     pub fn get_bottom_point(&self) -> FGVec2 {
-        FGVec2::new(FGi32::ZERO, FGi32::ZERO)
+        self.bottom
+    }
+}
+
+pub fn update_ecb(
+    query: Query<(
+        &mut FighterECB,
+        &FighterSurfaceState,
+        &FighterECBBoneIndices,
+        &FighterBoneMatrices,
+        &FighterTranslation,
+        &FighterFacingDirection,
+    )>,
+) {
+    for (mut ecb, surface_state, bone_indices, bone_matrices, translation, facing_dir) in query {
+        let trf = translation.get_3d_transform(facing_dir);
+
+        let transformed_ecb_bones = bone_indices.indices.iter().filter_map(|idx| {
+            let Some((_, bone_matrix)) = bone_matrices.get_by_idx(*idx) else {
+                return None;
+            };
+
+            let pt = trf.transform_point(bone_matrix.get_translation());
+
+            Some(FGVec2::new(pt.x, pt.y) - translation.0)
+        }).collect::<Vec<_>>();
+
+        let max_x = transformed_ecb_bones.iter().max_by(|a, b| a.x.cmp(&b.x)).map(|final_val| final_val.x).unwrap_or(FGi32::lit("0.5"));
+        let min_x = transformed_ecb_bones.iter().min_by(|a, b| a.x.cmp(&b.x)).map(|final_val| final_val.x).unwrap_or(FGi32::lit("-0.5"));
+        let max_y = transformed_ecb_bones.iter().max_by(|a, b| a.y.cmp(&b.y)).map(|final_val| final_val.y).unwrap_or(FGi32::lit("0.5"));
+        let min_y = transformed_ecb_bones.iter().min_by(|a, b| a.y.cmp(&b.y)).map(|final_val| final_val.y).unwrap_or(FGi32::lit("-0.5"));
+
+        let midpoint_height = (max_y + min_y) / FGi32::lit("2.0");
+        let top = FGVec2::new(FGi32::ZERO, max_y);
+        let bottom = FGVec2::new(FGi32::ZERO, min_y);
+        let left = FGVec2::new(min_x, midpoint_height);
+        let right = FGVec2::new(max_x, midpoint_height);
+
+        let ecb_lock_frames_remaining = if let FighterSurfaceState::Airborne { ecb_lock_frames_remaining } = *surface_state {
+            ecb_lock_frames_remaining
+        } else {
+            0
+        };
+
+        ecb.top = top;
+
+        if ecb_lock_frames_remaining == 0 {
+            ecb.bottom = bottom;
+        }
+
+        ecb.left = left;
+        ecb.right = right;
+
+        if surface_state.is_grounded() {
+            ecb.bottom = FGVec2::ZERO;
+        }
+    }
+}
+
+pub fn decrement_ecb_lockout(surface_states: Query<&mut FighterSurfaceState>) {
+    for mut state in surface_states {
+        state.tick_ecb_lock();
     }
 }
 
@@ -92,12 +139,16 @@ mod tests {
     #[test]
     fn previous_ecb_copies_current_dimensions() {
         let current = FighterECB {
-            vertical_half: FGi32::lit("0.5"),
-            horizontal_half: FGi32::lit("0.25"),
+            bottom: FGVec2::lit("0.0", "-0.5"),
+            top: FGVec2::lit("0.0", "0.5"),
+            left: FGVec2::lit("-0.5", "0.0"),
+            right: FGVec2::lit("0.5", "0.0"),
         };
         let previous = FighterPreviousECB::from(current);
 
-        assert_eq!(previous.vertical_half, current.vertical_half);
-        assert_eq!(previous.horizontal_half, current.horizontal_half);
+        assert_eq!(previous.top, current.top);
+        assert_eq!(previous.bottom, current.bottom);
+        assert_eq!(previous.left, current.left);
+        assert_eq!(previous.right, current.right);
     }
 }

src/fighter/manifest.rs

@@ -65,6 +65,7 @@ pub struct FighterManifest {
     pub animations: HashMap<AnimKind, String>,
     pub attack_scripts: HashMap<AttackKind, String>,
     pub hurtboxes: Vec<FighterHurtbox>,
+    pub ecb_bones: Vec<String>,
 }
 
 #[derive(Resource)]

src/fighter/mod.rs

@@ -34,24 +34,13 @@ pub use motion::{
 pub use surface::FighterSurfaceState;
 
 use crate::{
-    AppState,
-    fighter::{
+    AppState, fighter::{
         attack::{
             AttackKind, FighterAttackPlugin, FighterAttackScriptAssets, FighterDamage,
             FighterKnockbackVelocity, FighterPendingHitReaction, FighterSolvedHurtboxes,
             FighterStaleMoveQueue,
-        },
-        baked_animation::{FighterBoneIndexMap, FighterBoneMatrices},
-        manifest::FighterManifest,
-        state::{FighterState, air::AirborneStateCommon, fall::FallState},
-        visual::FighterAnimations,
-    },
-    input::FighterInput,
-    math::{int::FGi32, vec::FGVec2},
-    player::Player,
-    schedule::GameplaySet,
-    scripting::FighterAttackScript,
-    stage::line::StageCollision,
+        }, baked_animation::{FighterBoneIndexMap, FighterBoneMatrices}, ecb::FighterECBBoneIndices, manifest::FighterManifest, state::{FighterState, air::AirborneStateCommon, fall::FallState}, visual::FighterAnimations,
+    }, input::FighterInput, math::{int::FGi32, vec::FGVec2}, player::Player, schedule::GameplaySet, scripting::FighterAttackScript, stage::line::StageCollision,
 };
 use state::state_interrupt_system;
 
@@ -182,10 +171,15 @@ impl Plugin for FighterPlugin {
             )*/
             .add_systems(
                 GgrsSchedule,
-                state::state_collision_interrupt_system.in_set(GameplaySet::Collision),
+                (
+                    (ecb::update_ecb, ecb::decrement_ecb_lockout, state::state_collision_interrupt_system).chain(),
+                    baked_animation::update_fighter_bone_matrices,
+                )
+                    .chain()
+                    .in_set(GameplaySet::Collision),
             )
             .add_systems(
-                Update,
+                PostUpdate,
                 (
                     motion::apply_fighter_translation_to_visuals,
                     animation::apply_animation,
@@ -286,6 +280,7 @@ pub fn spawn_fighter(
     animations: FighterAnimations,
     attack_scripts: FighterAttackScriptAssets,
     visual_root: WorldAssetRoot,
+    ecb_bone_indices: Vec<usize>,
 ) -> Entity {
     commands
         .spawn((
@@ -296,14 +291,14 @@ pub fn spawn_fighter(
             Fighter { manifest: manifest },
             FighterFacingDirection::Right,
             FighterPreviousFacingDirection(FighterFacingDirection::Right),
-            FighterSurfaceState::Airborne,
+            FighterSurfaceState::default(),
             Transform::from_scale(Vec3::splat(model_scale.to_num())),
             (
-                FighterECB {
-                    vertical_half: FGi32::lit("5.0"),
-                    horizontal_half: FGi32::lit("2.5"),
-                },
+                FighterECB::default(),
                 FighterHitboxes::default(),
+                FighterECBBoneIndices {
+                    indices: ecb_bone_indices
+                }
             ),
             (
                 FighterVelocity::default(),

src/fighter/motion.rs

@@ -8,7 +8,7 @@ use crate::debug_tools::PresentationMotionMode;
 use crate::fighter::FighterHitstopShake;
 use crate::game_settings::GameSettings;
 use crate::{
-    fighter::{FighterECB, FighterFacingDirection, baked_animation::FixedMat4},
+    fighter::{FighterFacingDirection, baked_animation::FixedMat4},
     math::{int::FGi32, vec::FGVec2, vec3::FGVec3},
 };
 
@@ -56,7 +56,6 @@ pub fn apply_fighter_translation_to_visuals(
     query: Query<(
         &FighterTranslation,
         &FighterPreviousTranslation,
-        &FighterECB,
         &FighterHitstopShake,
         &mut Transform,
     )>,
@@ -65,17 +64,16 @@ pub fn apply_fighter_translation_to_visuals(
     game_settings: Res<GameSettings>,
 ) {
     let overstep_fraction = timing.overstep_fraction();
-    for (translation, previous_translation, ecb, hitstop_shake, mut transform) in query {
+    for (translation, previous_translation, hitstop_shake, mut transform) in query {
         let translation = sample_presentation_translation(
             *previous_translation,
             *translation,
             overstep_fraction,
             debug_settings.motion_sampling,
         );
-        let bottom = ecb.get_bottom_point();
         transform.translation = Vec3::new(
-            translation.x + bottom.x.to_num::<f32>(),
-            translation.y + bottom.y.to_num::<f32>(),
+            translation.x,
+            translation.y,
             0.0,
         );
 

src/fighter/state/air.rs

@@ -83,9 +83,7 @@ pub fn apply_air_motion(
     velocity: &FighterVelocity,
     translation: &mut FighterTranslation,
     prev_translation: &mut FighterPreviousTranslation,
-    surface: &mut FighterSurfaceState,
 ) {
-    surface.leave_ground();
     // Vertical velocity should be 0 on the ground
     prev_translation.0 = translation.0;
     translation.0 += velocity.0;
@@ -111,7 +109,6 @@ pub fn update_standard_motion(
         ctx.velocity,
         ctx.translation,
         ctx.prev_translation,
-        ctx.surface,
     );
 }
 
@@ -120,7 +117,12 @@ pub fn collision_interrupt(
     landing_type: LandingType,
 ) -> Option<FighterState> {
     let res = ctx.air_collide_with_stage()?;
-    ctx.translation.0 = res.hit_position - ctx.ecb.get_bottom_point();
+    let diff = res.hit_position - ctx.translation.0;
+    ctx.ecb.bottom -= diff;
+    ctx.ecb.top -= diff;
+    ctx.ecb.left -= diff;
+    ctx.ecb.right -= diff;
+    ctx.translation.0 = res.hit_position;
     ctx.surface.land(res.line_id);
     Some(FighterState::Land(LandingState::create(landing_type)))
 }

src/fighter/state/air_dodge.rs

@@ -38,7 +38,6 @@ impl FighterStateImpl for AirDodgeState {
             state_context.velocity,
             state_context.translation,
             state_context.prev_translation,
-            state_context.surface,
         );
     }
 
@@ -59,6 +58,10 @@ impl FighterStateImpl for AirDodgeState {
     fn is_visually_grounded<'a>(&'a self) -> bool {
         false
     }
+
+    fn surface_policy(&self) -> super::SurfacePolicy {
+        super::SurfacePolicy::Airborne(crate::fighter::surface::EcbLockPolicy::StartOnDetach)
+    }
 }
 
 pub fn check_input(state_context: &InterruptContext) -> Option<FighterState> {

src/fighter/state/fall.rs

@@ -46,5 +46,8 @@ impl FighterStateImpl for FallState {
     ) -> bool {
         false
     }
-}
 
+    fn surface_policy(&self) -> super::SurfacePolicy {
+        super::SurfacePolicy::Airborne(crate::fighter::surface::EcbLockPolicy::StartOnDetach)
+    }
+}

src/fighter/state/ground.rs

@@ -178,7 +178,7 @@ pub fn collide_with_stage_grounded(
     can_walk_off: bool,
 ) -> GroundedMotionResult {
     let translation = &mut state_context.translation;
-    let ecb = state_context.ecb;
+    let ecb = &state_context.ecb;
     let stage_collision = state_context.stage_collision;
 
     let Some(current_line_id) = state_context.surface.line_id() else {
@@ -218,12 +218,18 @@ pub fn collide_with_stage_grounded(
                 GroundedMotionResult::InGround
             }
             GroundedPositionResult::InAir => {
-                state_context.surface.leave_ground();
+                state_context.surface.apply_airborne_policy(
+                    crate::fighter::surface::EcbLockPolicy::StartOnDetach,
+                    state_context.leave_ground_ecb_lock_duration,
+                );
                 GroundedMotionResult::InAir
             }
         }
     } else {
-        state_context.surface.leave_ground();
+        state_context.surface.apply_airborne_policy(
+            crate::fighter::surface::EcbLockPolicy::StartOnDetach,
+            state_context.leave_ground_ecb_lock_duration,
+        );
         GroundedMotionResult::InAir
     }
 }
@@ -363,9 +369,11 @@ mod tests {
         let mut translation = FighterTranslation(FGVec2::lit("11", "0"));
         let previous_translation = FighterPreviousTranslation(translation.0);
         let mut velocity = FighterVelocity::default();
-        let ecb = FighterECB {
-            vertical_half: FGi32::ONE,
-            horizontal_half: FGi32::ONE,
+        let mut ecb = FighterECB {
+            bottom: FGVec2::lit("0.0", "-0.5"),
+            top: FGVec2::lit("0.0", "0.5"),
+            left: FGVec2::lit("-0.5", "0.0"),
+            right: FGVec2::lit("0.5", "0.0"),
         };
         let previous_ecb = FighterPreviousECB::from(ecb);
         let mut context = CollisionContext {
@@ -373,9 +381,10 @@ mod tests {
             prev_translation: &previous_translation,
             velocity: &mut velocity,
             surface: &mut surface,
-            ecb: &ecb,
+            ecb: &mut ecb,
             prev_ecb: &previous_ecb,
             stage_collision: &stage_collision,
+            leave_ground_ecb_lock_duration: 10,
         };
 
         assert!(matches!(
@@ -411,9 +420,11 @@ mod tests {
         let mut translation = FighterTranslation(FGVec2::lit("11", "0"));
         let previous_translation = FighterPreviousTranslation(translation.0);
         let mut velocity = FighterVelocity::default();
-        let ecb = FighterECB {
-            vertical_half: FGi32::ONE,
-            horizontal_half: FGi32::ONE,
+        let mut ecb = FighterECB {
+            bottom: FGVec2::lit("0.0", "-0.5"),
+            top: FGVec2::lit("0.0", "0.5"),
+            left: FGVec2::lit("-0.5", "0.0"),
+            right: FGVec2::lit("0.5", "0.0"),
         };
         let previous_ecb = FighterPreviousECB::from(ecb);
         let mut context = CollisionContext {
@@ -421,16 +432,17 @@ mod tests {
             prev_translation: &previous_translation,
             velocity: &mut velocity,
             surface: &mut surface,
-            ecb: &ecb,
+            ecb: &mut ecb,
             prev_ecb: &previous_ecb,
             stage_collision: &stage_collision,
+            leave_ground_ecb_lock_duration: 10,
         };
 
         assert!(matches!(
             collide_with_stage_grounded(&mut context, true),
             GroundedMotionResult::InAir
         ));
-        assert_eq!(surface, FighterSurfaceState::Airborne);
+        assert!(matches!(surface, FighterSurfaceState::Airborne { .. }));
     }
 }
 

src/fighter/state/hitstun.rs

@@ -83,7 +83,6 @@ impl FighterStateImpl for HitstunState {
         match self.hitstop_kind {
             HitstopStateKind::Grounded => {}
             HitstopStateKind::Airborne => {
-                ctx.surface.leave_ground();
                 air::integrate_gravity(ctx.velocity, ctx.fighter_attributes, false);
             }
         }
@@ -126,4 +125,13 @@ impl FighterStateImpl for HitstunState {
             HitstopStateKind::Airborne => false,
         }
     }
+
+    fn surface_policy(&self) -> super::SurfacePolicy {
+        match self.hitstop_kind {
+            HitstopStateKind::Grounded => super::SurfacePolicy::Grounded,
+            HitstopStateKind::Airborne => super::SurfacePolicy::Airborne(
+                crate::fighter::surface::EcbLockPolicy::StartOnDetach,
+            ),
+        }
+    }
 }

src/fighter/state/jump.rs

@@ -186,6 +186,16 @@ impl FighterStateImpl for JumpState {
     fn is_visually_grounded<'a>(&'a self) -> bool {
         false
     }
+
+    fn surface_policy(&self) -> super::SurfacePolicy {
+        use crate::fighter::surface::EcbLockPolicy;
+        match self.jump_type {
+            JumpType::DoubleJump => super::SurfacePolicy::Airborne(EcbLockPolicy::Restart),
+            JumpType::ShortHop | JumpType::LongJump => {
+                super::SurfacePolicy::Airborne(EcbLockPolicy::StartOnDetach)
+            }
+        }
+    }
 }
 
 pub fn check_input(state_context: &InterruptContext) -> Option<FighterState> {

src/fighter/state/mod.rs

@@ -21,6 +21,7 @@ use crate::fighter::{
     FighterHitstopShake, FighterHitstopShakeKind, FighterHitstopShakeRole,
     FighterPreviousTranslation, FighterSurfaceState, FighterTranslation, FighterVelocity,
 };
+use crate::fighter::surface::EcbLockPolicy;
 use crate::game_settings::GameSettings;
 use crate::input::FighterInput;
 use crate::math::int::FGi32;
@@ -41,6 +42,12 @@ pub mod turn;
 pub mod wait;
 pub mod walk;
 
+#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)]
+pub enum SurfacePolicy {
+    Grounded,
+    Airborne(EcbLockPolicy),
+}
+
 macro_rules! fighter_states {
     ($($variant:ident => $ty:ty),* $(,)?) => {
         #[derive(Component, Clone, Debug, Hash)]
@@ -72,6 +79,10 @@ macro_rules! fighter_states {
             pub fn is_visually_grounded(&self) -> bool {
                 match self { $(Self::$variant(s) => s.is_visually_grounded()),* }
             }
+
+            pub fn surface_policy(&self) -> SurfacePolicy {
+                match self { $(Self::$variant(s) => s.surface_policy()),* }
+            }
         }
 
         $(impl From<$ty> for FighterState {
@@ -99,6 +110,10 @@ pub trait FighterStateImpl: Sized {
     }
 
     fn is_visually_grounded<'a>(&'a self) -> bool;
+
+    fn surface_policy(&self) -> SurfacePolicy {
+        SurfacePolicy::Grounded
+    }
 }
 
 pub struct AnimationStatus {
@@ -173,9 +188,10 @@ pub struct CollisionContext<'a> {
     pub prev_translation: &'a FighterPreviousTranslation,
     pub velocity: &'a mut FighterVelocity,
     pub surface: &'a mut FighterSurfaceState,
-    pub ecb: &'a FighterECB,
+    pub ecb: &'a mut FighterECB,
     pub prev_ecb: &'a FighterPreviousECB,
     pub stage_collision: &'a StageCollision,
+    pub leave_ground_ecb_lock_duration: u32,
 }
 
 impl CollisionContext<'_> {
@@ -218,7 +234,7 @@ pub struct FighterFrameQuery {
     pub surface: &'static mut FighterSurfaceState,
     pub knockback_velocity: &'static mut FighterKnockbackVelocity,
     pub stale_move_queue: &'static mut FighterStaleMoveQueue,
-    pub ecb: &'static FighterECB,
+    pub ecb: &'static mut FighterECB,
     pub prev_ecb: &'static FighterPreviousECB,
     pub facing_direction: &'static mut FighterFacingDirection,
     pub animation_frame: &'static mut FighterAnimationFrame,
@@ -310,15 +326,17 @@ impl<'w, 's> FighterFrameQueryItem<'w, 's> {
     fn collision_context<'a>(
         &'a mut self,
         stage_collision: &'a StageCollision,
+        game_settings: &'a GameSettings,
     ) -> CollisionContext<'a> {
         CollisionContext {
             translation: &mut self.translation,
             prev_translation: &self.prev_translation,
             velocity: &mut self.velocity,
             surface: &mut self.surface,
-            ecb: &self.ecb,
+            ecb: &mut self.ecb,
             prev_ecb: &self.prev_ecb,
             stage_collision,
+            leave_ground_ecb_lock_duration: game_settings.fighter_common.leave_ground_ecb_frame_lock_duration
         }
     }
 }
@@ -373,11 +391,18 @@ fn transition_state(
     frame: &mut FighterFrameQueryItem,
     attributes: &FighterAttributes,
     attack_script_assets: &FighterAttackScriptAssets,
+    game_settings: &GameSettings,
 ) {
     let old_name = current.name();
     let new_name = next.name();
 
     current.on_exit(&mut frame.exit_context());
+    if let SurfacePolicy::Airborne(lock_policy) = next.surface_policy() {
+        frame.surface.apply_airborne_policy(
+            lock_policy,
+            game_settings.fighter_common.leave_ground_ecb_frame_lock_duration,
+        );
+    }
     next.on_enter(&mut frame.enter_context(attributes, attack_script_assets));
     *current = next;
     info!("{} -> {}", old_name, new_name);
@@ -448,10 +473,6 @@ pub fn state_interrupt_system(
                 }
             }
 
-            if matches!(hitstop_kind, hitstun::HitstopStateKind::Airborne) {
-                frame.surface.leave_ground();
-            }
-
             info!("Entering hitstop kind: {:?}", hitstop_kind);
             Some(FighterState::Hitstun(HitstunState::new(
                 reaction,
@@ -475,6 +496,7 @@ pub fn state_interrupt_system(
                 &mut frame,
                 &manifest.attributes,
                 attack_script_assets,
+                &game_settings,
             );
         };
     }
@@ -484,6 +506,7 @@ pub fn state_collision_interrupt_system(
     mut query: Query<StatefulFighterQuery>,
     stage_collision: Res<StageCollision>,
     fighter_manifests: Res<Assets<FighterManifest>>,
+    game_settings: Res<GameSettings>,
 ) {
     for fighter in &mut query {
         let StatefulFighterQueryItem {
@@ -502,7 +525,7 @@ pub fn state_collision_interrupt_system(
             .get(&fighter.manifest)
             .expect("Fighter manifest should be valid");
         let new_state =
-            state.check_collision_interrupt(&mut frame.collision_context(&stage_collision));
+            state.check_collision_interrupt(&mut frame.collision_context(&stage_collision, &game_settings));
         if let Some(new_state) = new_state {
             transition_state(
                 &mut state,
@@ -510,6 +533,7 @@ pub fn state_collision_interrupt_system(
                 &mut frame,
                 &manifest.attributes,
                 &attack_script_assets,
+                &game_settings,
             );
         }
     }

src/fighter/surface.rs

@@ -1,21 +1,38 @@
 use bevy::prelude::*;
 
-use crate::stage::line::StageLineID;
+use crate::{stage::line::StageLineID};
+
+#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)]
+pub enum EcbLockPolicy {
+    StartOnDetach,
+    Restart,
+    Preserve,
+    Clear,
+}
 
 /// The stage surface currently supporting a fighter.
 ///
 /// This is physics state rather than fighter-state-machine state. Keeping it
 /// separate means grounded, landing, and hitstun states all share one source
 /// of truth for stage contact.
-#[derive(Component, Clone, Copy, Debug, Default, Hash, PartialEq, Eq)]
+#[derive(Component, Clone, Copy, Debug, Hash, PartialEq, Eq)]
 pub enum FighterSurfaceState {
-    #[default]
-    Airborne,
+    Airborne {
+        ecb_lock_frames_remaining: u32
+    },
     Grounded {
         line_id: StageLineID,
     },
 }
 
+impl Default for FighterSurfaceState {
+    fn default() -> Self {
+        Self::Airborne {
+            ecb_lock_frames_remaining: 0
+        }
+    }
+}
+
 impl FighterSurfaceState {
     pub fn is_grounded(self) -> bool {
         matches!(self, Self::Grounded { .. })
@@ -23,7 +40,7 @@ impl FighterSurfaceState {
 
     pub fn line_id(self) -> Option<StageLineID> {
         match self {
-            Self::Airborne => None,
+            Self::Airborne { .. } => None,
             Self::Grounded { line_id } => Some(line_id),
         }
     }
@@ -32,8 +49,29 @@ impl FighterSurfaceState {
         *self = Self::Grounded { line_id };
     }
 
-    pub(crate) fn leave_ground(&mut self) {
-        *self = Self::Airborne;
+    pub(crate) fn apply_airborne_policy(
+        &mut self,
+        policy: EcbLockPolicy,
+        ecb_lock_duration: u32,
+    ) {
+        let current_lock = match *self {
+            Self::Airborne { ecb_lock_frames_remaining } => ecb_lock_frames_remaining,
+            Self::Grounded { .. } => 0,
+        };
+        let ecb_lock_frames_remaining = match policy {
+            EcbLockPolicy::StartOnDetach if self.is_grounded() => ecb_lock_duration,
+            EcbLockPolicy::StartOnDetach => current_lock,
+            EcbLockPolicy::Restart => ecb_lock_duration,
+            EcbLockPolicy::Preserve => current_lock,
+            EcbLockPolicy::Clear => 0,
+        };
+        *self = Self::Airborne { ecb_lock_frames_remaining };
+    }
+
+    pub(crate) fn tick_ecb_lock(&mut self) {
+        if let Self::Airborne { ecb_lock_frames_remaining } = self {
+            *ecb_lock_frames_remaining = ecb_lock_frames_remaining.saturating_sub(1);
+        }
     }
 }
 
@@ -55,8 +93,38 @@ mod tests {
         assert!(surface.is_grounded());
         assert_eq!(surface.line_id(), Some(line_id));
 
-        surface.leave_ground();
+        surface.apply_airborne_policy(EcbLockPolicy::Clear, 0);
         assert!(!surface.is_grounded());
         assert_eq!(surface.line_id(), None);
     }
+
+    #[test]
+    fn start_on_detach_does_not_reset_an_existing_lock() {
+        let mut surface = FighterSurfaceState::default();
+        surface.apply_airborne_policy(EcbLockPolicy::Restart, 5);
+        surface.tick_ecb_lock();
+        surface.apply_airborne_policy(EcbLockPolicy::StartOnDetach, 5);
+
+        assert_eq!(
+            surface,
+            FighterSurfaceState::Airborne {
+                ecb_lock_frames_remaining: 4,
+            }
+        );
+    }
+
+    #[test]
+    fn restart_retriggers_an_existing_lock() {
+        let mut surface = FighterSurfaceState::default();
+        surface.apply_airborne_policy(EcbLockPolicy::Restart, 5);
+        surface.tick_ecb_lock();
+        surface.apply_airborne_policy(EcbLockPolicy::Restart, 5);
+
+        assert_eq!(
+            surface,
+            FighterSurfaceState::Airborne {
+                ecb_lock_frames_remaining: 5,
+            }
+        );
+    }
 }

src/game_settings.rs

@@ -39,6 +39,7 @@ pub struct FighterSettingsCommon {
     
     /// Maximum angle changed caused by directional influence
     pub di_max_angle: FGi32,
+    pub leave_ground_ecb_frame_lock_duration: u32
 }
 #[derive(Reflect, Serialize, Deserialize, Clone)]
 #[reflect(opaque)]

src/match_loading.rs

@@ -336,6 +336,15 @@ pub fn prepare_match(
             );
             return;
         }
+
+        let ecb_bone_indices = baked.bone_names.iter().enumerate().filter_map(|(idx, name)| {
+            if manifest.ecb_bones.contains(name) {
+                Some(idx)
+            } else {
+                None
+            }
+        }).collect::<Vec<_>>();
+
         if let Err(error) = manifest.attributes.validate() {
             fail_match(
                 &mut next_state,
@@ -436,6 +445,7 @@ pub fn prepare_match(
             attack_scripts,
             manifest_handle,
             manifest.model_scale,
+            ecb_bone_indices,
         ));
     }
 
@@ -477,7 +487,7 @@ pub fn prepare_match(
     );
 
     let mut fighter_roster = Vec::with_capacity(config.players.len());
-    for (index, (player, (scene, animations, attack_scripts, manifest_handle, model_scale))) in
+    for (index, (player, (scene, animations, attack_scripts, manifest_handle, model_scale, ecb_bone_indices))) in
         config.players.iter().zip(prepared).enumerate()
     {
         let spawn_x = (index as i32 * 2 + 1 - config.players.len() as i32) * 5;
@@ -490,6 +500,7 @@ pub fn prepare_match(
             animations,
             attack_scripts,
             WorldAssetRoot(scene),
+            ecb_bone_indices
         ));
     }
 

src/math/vec.rs

@@ -2,7 +2,7 @@ use bevy::math::Vec2;
 use bevy::prelude::*;
 use fixed::types::I32F32;
 use serde::{Deserialize, Serialize};
-use std::ops::{Add, AddAssign, Div, Mul, MulAssign, Sub};
+use std::ops::{Add, AddAssign, Div, Mul, MulAssign, Sub, SubAssign};
 
 use super::int::{FGWide, FGi32};
 
@@ -227,6 +227,15 @@ impl AddAssign for FGVec2 {
     }
 }
 
+impl SubAssign for FGVec2 {
+    fn sub_assign(&mut self, rhs: Self) {
+        *self = Self {
+            x: self.x - rhs.x,
+            y: self.y - rhs.y,
+        }
+    }
+}
+
 impl MulAssign for FGVec2 {
     fn mul_assign(&mut self, rhs: Self) {
         *self = Self {

src/schedule.rs

@@ -19,10 +19,10 @@ pub enum GameplaySet {
     StateUpdate,
     /// Integrate velocities into positions.
     Physics,
-    /// Solve collision boxes
-    Animation,
     /// Resolve the integrated positions against the stage.
     Collision,
+    /// Solve collision boxes
+    Animation,
     /// Resolve attacks
     Attacks,
 }
@@ -40,8 +40,8 @@ impl Plugin for GameplaySchedulePlugin {
                 GameplaySet::Interrupt,
                 GameplaySet::StateUpdate,
                 GameplaySet::Physics,
-                GameplaySet::Collision,
                 GameplaySet::Animation,
+                GameplaySet::Collision,
                 GameplaySet::Attacks,
             )
                 .chain(),