subtr_actor/stats/calculators/

half_flip.rs

use super::*;

const HALF_FLIP_EVALUATION_SECONDS: f32 = 0.65;
const HALF_FLIP_MAX_CANDIDATE_SECONDS: f32 = 1.0;
const HALF_FLIP_MIN_FORWARD_REVERSAL: f32 = 0.75;
const HALF_FLIP_MIN_POST_REVERSAL_RETAINED_REVERSAL: f32 = 0.45;
const HALF_FLIP_MIN_FINAL_FORWARD_HORIZONTAL: f32 = 0.55;
const HALF_FLIP_MIN_FORWARD_VERTICAL: f32 = 0.55;
const HALF_FLIP_MIN_CONFIDENCE: f32 = 0.55;
/// Pre-dodge angular speed above which the car was already spinning hard before
/// the dodge byte fired. Replay angular velocity is stored in hundredths of
/// rad/s (RL saturates around 550, i.e. 5.5 rad/s), so 250 is ~2.5 rad/s.
const HALF_FLIP_PRE_DODGE_TUMBLE_ANGULAR_SPEED: f32 = 250.0;
/// Pre-dodge nose verticality (|forward.z|) above which the car was already
/// pitched well off flat before the dodge byte fired.
const HALF_FLIP_PRE_DODGE_TUMBLE_FORWARD_VERTICAL: f32 = 0.5;
/// Minimum backward-entry alignment (velocity opposing facing) below which a
/// dodge is not a deliberate half-flip entry. Real half-flips reverse the car
/// (positive alignment) or at worst travel forward with a controlled body; an
/// air-hit tumble is knocked forward into the spin (strongly negative).
const HALF_FLIP_PRE_DODGE_MIN_BACKWARD_ENTRY: f32 = 0.0;

/// A dodge sequence that cancels a flip into an opposite facing direction.
#[derive(Debug, Clone, PartialEq, Serialize, ts_rs::TS)]
#[ts(export)]
pub struct HalfFlipEvent {
    pub time: f32,
    pub frame: usize,
    #[ts(as = "crate::interop::ts_bindings::RemoteIdTs")]
    pub player: PlayerId,
    pub is_team_0: bool,
    pub start_position: [f32; 3],
    pub end_position: [f32; 3],
    pub start_speed: f32,
    pub end_speed: f32,
    pub start_backward_alignment: f32,
    pub best_reorientation_alignment: f32,
    pub best_forward_reversal: f32,
    pub max_forward_vertical: f32,
    pub confidence: f32,
}

#[derive(Debug, Clone, PartialEq)]
struct ActiveHalfFlipCandidate {
    is_team_0: bool,
    start_time: f32,
    start_frame: usize,
    latest_time: f32,
    latest_frame: usize,
    start_position: [f32; 3],
    end_position: [f32; 3],
    start_speed: f32,
    end_speed: f32,
    start_forward_xy: glam::Vec2,
    start_backward_alignment: f32,
    best_reorientation_alignment: f32,
    best_forward_reversal: f32,
    latest_forward_reversal: f32,
    min_forward_reversal_after_reaching_opposite: f32,
    latest_forward_horizontal: f32,
    max_forward_vertical: f32,
    pre_dodge_angular_speed: f32,
    pre_dodge_forward_vertical: f32,
}

#[derive(Debug, Clone, Copy, PartialEq)]
struct PreDodgeSnapshot {
    angular_speed: f32,
    forward_vertical: f32,
}

/// Detects half-flips from player frame state.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct HalfFlipCalculator {
    events: EventStream<HalfFlipEvent>,
    active_candidates: HashMap<PlayerId, ActiveHalfFlipCandidate>,
    previous_dodge_active: HashMap<PlayerId, bool>,
    pre_dodge_snapshot: HashMap<PlayerId, PreDodgeSnapshot>,
}

impl HalfFlipCalculator {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn events(&self) -> &[HalfFlipEvent] {
        self.events.all()
    }

    pub fn new_events(&self) -> &[HalfFlipEvent] {
        self.events.new_events()
    }

    fn normalize_score(value: f32, min_value: f32, max_value: f32) -> f32 {
        if max_value <= min_value {
            return 0.0;
        }

        ((value - min_value) / (max_value - min_value)).clamp(0.0, 1.0)
    }

    fn horizontal_velocity(player: &PlayerSample) -> Option<glam::Vec2> {
        let velocity = player.velocity()?.truncate();
        if velocity.length_squared() <= f32::EPSILON {
            return None;
        }
        Some(velocity)
    }

    fn forward_vector(player: &PlayerSample) -> Option<glam::Vec3> {
        let rigid_body = player.rigid_body.as_ref()?;
        Some(quat_to_glam(&rigid_body.rotation) * glam::Vec3::X)
    }

    fn forward_xy(player: &PlayerSample) -> Option<glam::Vec2> {
        let forward_xy = Self::forward_vector(player)?.truncate().normalize_or_zero();
        if forward_xy.length_squared() <= f32::EPSILON {
            return None;
        }
        Some(forward_xy)
    }

    fn angular_speed(player: &PlayerSample) -> f32 {
        player
            .rigid_body
            .as_ref()
            .and_then(|rb| rb.angular_velocity.as_ref())
            .map_or(0.0, |angular| vec_to_glam(angular).length())
    }

    fn maybe_start_candidate(&mut self, frame: &FrameInfo, player: &PlayerSample) {
        let was_dodge_active = self
            .previous_dodge_active
            .insert(player.player_id.clone(), player.dodge_active)
            .unwrap_or(false);
        if !player.dodge_active || was_dodge_active {
            return;
        }

        let Some(position) = player.position() else {
            return;
        };

        let velocity_xy = Self::horizontal_velocity(player).unwrap_or(glam::Vec2::ZERO);
        let start_speed = velocity_xy.length();

        let Some(start_forward_xy) = Self::forward_xy(player) else {
            return;
        };
        let velocity_direction = velocity_xy.normalize_or_zero();
        let start_backward_alignment = -start_forward_xy.dot(velocity_direction);

        let max_forward_vertical =
            Self::forward_vector(player).map_or(0.0, |forward| forward.z.abs());

        let pre_dodge = self
            .pre_dodge_snapshot
            .get(&player.player_id)
            .copied()
            .unwrap_or(PreDodgeSnapshot {
                angular_speed: 0.0,
                forward_vertical: 0.0,
            });

        self.active_candidates.insert(
            player.player_id.clone(),
            ActiveHalfFlipCandidate {
                is_team_0: player.is_team_0,
                start_time: frame.time,
                start_frame: frame.frame_number,
                latest_time: frame.time,
                latest_frame: frame.frame_number,
                start_position: position.to_array(),
                end_position: position.to_array(),
                start_speed,
                end_speed: start_speed,
                start_forward_xy,
                start_backward_alignment,
                best_reorientation_alignment: 0.0,
                best_forward_reversal: 0.0,
                latest_forward_reversal: 0.0,
                min_forward_reversal_after_reaching_opposite: 1.0,
                latest_forward_horizontal: start_forward_xy.length(),
                max_forward_vertical,
                pre_dodge_angular_speed: pre_dodge.angular_speed,
                pre_dodge_forward_vertical: pre_dodge.forward_vertical,
            },
        );
    }

    fn update_candidate(
        candidate: &mut ActiveHalfFlipCandidate,
        frame: &FrameInfo,
        player: &PlayerSample,
    ) {
        if let Some(position) = player.position() {
            candidate.end_position = position.to_array();
        }

        let velocity_xy = Self::horizontal_velocity(player).unwrap_or(glam::Vec2::ZERO);
        candidate.end_speed = velocity_xy.length();
        let velocity_direction = velocity_xy.normalize_or_zero();

        if let Some(forward) = Self::forward_vector(player) {
            candidate.max_forward_vertical = candidate.max_forward_vertical.max(forward.z.abs());
            let forward_xy_raw = forward.truncate();
            candidate.latest_forward_horizontal = forward_xy_raw.length();
            if candidate.latest_forward_horizontal >= HALF_FLIP_MIN_FINAL_FORWARD_HORIZONTAL {
                let forward_xy = forward_xy_raw.normalize_or_zero();
                candidate.latest_forward_reversal =
                    (-candidate.start_forward_xy.dot(forward_xy)).clamp(-1.0, 1.0);
                candidate.best_forward_reversal = candidate
                    .best_forward_reversal
                    .max(candidate.latest_forward_reversal);
                if candidate.best_forward_reversal >= HALF_FLIP_MIN_FORWARD_REVERSAL {
                    candidate.min_forward_reversal_after_reaching_opposite = candidate
                        .min_forward_reversal_after_reaching_opposite
                        .min(candidate.latest_forward_reversal);
                }
                if velocity_direction.length_squared() > f32::EPSILON {
                    candidate.best_reorientation_alignment = candidate
                        .best_reorientation_alignment
                        .max(forward_xy.dot(velocity_direction));
                }
            }
        }

        candidate.latest_time = frame.time;
        candidate.latest_frame = frame.frame_number;
    }

    fn candidate_event(
        player_id: &PlayerId,
        candidate: ActiveHalfFlipCandidate,
    ) -> Option<HalfFlipEvent> {
        if candidate.latest_forward_reversal < HALF_FLIP_MIN_FORWARD_REVERSAL
            || candidate.min_forward_reversal_after_reaching_opposite
                < HALF_FLIP_MIN_POST_REVERSAL_RETAINED_REVERSAL
            || candidate.latest_forward_horizontal < HALF_FLIP_MIN_FINAL_FORWARD_HORIZONTAL
            || candidate.max_forward_vertical < HALF_FLIP_MIN_FORWARD_VERTICAL
        {
            return None;
        }

        let reversal_score = Self::normalize_score(
            candidate.latest_forward_reversal,
            HALF_FLIP_MIN_FORWARD_REVERSAL,
            0.98,
        );
        let flip_score = Self::normalize_score(
            candidate.max_forward_vertical,
            HALF_FLIP_MIN_FORWARD_VERTICAL,
            0.85,
        );
        let confidence = 0.75 * reversal_score + 0.25 * flip_score;

        if confidence < HALF_FLIP_MIN_CONFIDENCE {
            return None;
        }

        // Reject dodges where the facing reversal was not produced by the dodge:
        // if the car was already tumbling (high pre-dodge spin or an
        // already-pitched nose) when the dodge byte fired *and* it was not a
        // deliberate backward half-flip entry, this is an air-hit tumble / failed
        // wave dash that happens to flip around through vertical, not a half-flip.
        let was_already_tumbling = candidate.pre_dodge_angular_speed
            >= HALF_FLIP_PRE_DODGE_TUMBLE_ANGULAR_SPEED
            || candidate.pre_dodge_forward_vertical >= HALF_FLIP_PRE_DODGE_TUMBLE_FORWARD_VERTICAL;
        if was_already_tumbling
            && candidate.start_backward_alignment < HALF_FLIP_PRE_DODGE_MIN_BACKWARD_ENTRY
        {
            return None;
        }

        Some(HalfFlipEvent {
            time: candidate.latest_time,
            frame: candidate.latest_frame,
            player: player_id.clone(),
            is_team_0: candidate.is_team_0,
            start_position: candidate.start_position,
            end_position: candidate.end_position,
            start_speed: candidate.start_speed,
            end_speed: candidate.end_speed,
            start_backward_alignment: candidate.start_backward_alignment,
            best_reorientation_alignment: candidate.best_reorientation_alignment,
            best_forward_reversal: candidate.best_forward_reversal,
            max_forward_vertical: candidate.max_forward_vertical,
            confidence,
        })
    }

    fn apply_event(&mut self, event: HalfFlipEvent) {
        self.events.push(event);
    }

    fn finalize_candidates(&mut self, frame: &FrameInfo, force_all: bool) {
        let mut finished_candidates = Vec::new();

        for (player_id, candidate) in &self.active_candidates {
            let duration = frame.time - candidate.start_time;
            if force_all || duration >= HALF_FLIP_EVALUATION_SECONDS {
                finished_candidates.push((
                    candidate.start_time,
                    candidate.start_frame,
                    format!("{player_id:?}"),
                    player_id.clone(),
                ));
            }
        }

        finished_candidates.sort_by(|left, right| {
            left.0
                .total_cmp(&right.0)
                .then_with(|| left.1.cmp(&right.1))
                .then_with(|| left.2.cmp(&right.2))
        });

        for (_, _, _, player_id) in finished_candidates {
            let Some(candidate) = self.active_candidates.remove(&player_id) else {
                continue;
            };
            if let Some(event) = Self::candidate_event(&player_id, candidate) {
                self.apply_event(event);
            }
        }
    }

    pub fn update(
        &mut self,
        frame: &FrameInfo,
        players: &PlayerFrameState,
        live_play_state: &LivePlayState,
    ) -> SubtrActorResult<()> {
        self.events.begin_update();
        if !live_play_state.is_live_play {
            self.active_candidates.clear();
            return Ok(());
        }

        for player in &players.players {
            self.maybe_start_candidate(frame, player);
        }

        let mut visible_players = HashSet::new();
        for player in &players.players {
            visible_players.insert(player.player_id.clone());
            if let Some(candidate) = self.active_candidates.get_mut(&player.player_id) {
                Self::update_candidate(candidate, frame, player);
            }
            // Remember the most recent non-dodging orientation so a freshly
            // started candidate can tell whether the car was already tumbling
            // (e.g. knocked into an air spin) *before* the dodge began. A real
            // half-flip starts from a controlled, roughly-flat car and the
            // dodge initiates the rotation; an air-hit tumble is already
            // spinning hard when the dodge byte appears.
            if !player.dodge_active {
                self.pre_dodge_snapshot.insert(
                    player.player_id.clone(),
                    PreDodgeSnapshot {
                        angular_speed: Self::angular_speed(player),
                        forward_vertical: Self::forward_vector(player)
                            .map_or(0.0, |forward| forward.z.abs()),
                    },
                );
            }
        }

        self.finalize_candidates(frame, false);
        self.active_candidates.retain(|player_id, candidate| {
            visible_players.contains(player_id)
                && frame.time - candidate.start_time <= HALF_FLIP_MAX_CANDIDATE_SECONDS
        });

        Ok(())
    }

    pub fn finalize(&mut self, frame: &FrameInfo) {
        self.finalize_candidates(frame, true);
    }
}

#[cfg(test)]
#[path = "half_flip_tests.rs"]
mod tests;