sable_core/

time.rs

//! Time tracking utilities.
//!
//! Provides types for tracking elapsed time, frame deltas, and timing operations.

use std::time;

/// Re-export of `std::time::Duration` for convenience.
pub type Duration = time::Duration;

/// Re-export of `std::time::Instant` for convenience.
pub type Instant = time::Instant;

/// Time state for tracking frame timing.
///
/// Tracks the current time, delta time since last frame, and accumulated time.
#[derive(Debug, Clone)]
pub struct Time {
    /// Time since the start of the application.
    elapsed: Duration,
    /// Time since the last frame.
    delta: Duration,
    /// Fixed timestep for physics updates.
    fixed_timestep: Duration,
    /// Accumulated time for fixed timestep updates.
    accumulator: Duration,
    /// The instant when the timer was started.
    start_instant: Instant,
    /// The instant of the last update.
    last_instant: Instant,
    /// Frame count since start.
    frame_count: u64,
    /// Time scale multiplier (1.0 = normal speed).
    time_scale: f64,
}

impl Default for Time {
    fn default() -> Self {
        Self::new()
    }
}

impl Time {
    /// Creates a new time tracker.
    #[must_use]
    pub fn new() -> Self {
        let now = Instant::now();
        Self {
            elapsed: Duration::ZERO,
            delta: Duration::ZERO,
            fixed_timestep: Duration::from_secs_f64(1.0 / 60.0), // 60 Hz default
            accumulator: Duration::ZERO,
            start_instant: now,
            last_instant: now,
            frame_count: 0,
            time_scale: 1.0,
        }
    }

    /// Creates a time tracker with a custom fixed timestep.
    #[must_use]
    pub fn with_fixed_timestep(fixed_hz: f64) -> Self {
        let mut time = Self::new();
        time.fixed_timestep = Duration::from_secs_f64(1.0 / fixed_hz);
        time
    }

    /// Updates the time state. Call once per frame.
    pub fn update(&mut self) {
        let now = Instant::now();
        let raw_delta = now.duration_since(self.last_instant);

        // Apply time scale
        let scaled_delta = Duration::from_secs_f64(raw_delta.as_secs_f64() * self.time_scale);

        self.delta = scaled_delta;
        self.elapsed += scaled_delta;
        self.accumulator += scaled_delta;
        self.last_instant = now;
        self.frame_count += 1;
    }

    /// Updates with a specific delta time (useful for testing or replays).
    pub fn update_with_delta(&mut self, delta: Duration) {
        let scaled_delta = Duration::from_secs_f64(delta.as_secs_f64() * self.time_scale);

        self.delta = scaled_delta;
        self.elapsed += scaled_delta;
        self.accumulator += scaled_delta;
        self.frame_count += 1;
    }

    /// Returns the time elapsed since the start.
    #[inline]
    #[must_use]
    pub fn elapsed(&self) -> Duration {
        self.elapsed
    }

    /// Returns the time elapsed in seconds.
    #[inline]
    #[must_use]
    pub fn elapsed_secs(&self) -> f32 {
        self.elapsed.as_secs_f32()
    }

    /// Returns the time elapsed in seconds (f64).
    #[inline]
    #[must_use]
    pub fn elapsed_secs_f64(&self) -> f64 {
        self.elapsed.as_secs_f64()
    }

    /// Returns the delta time since the last frame.
    #[inline]
    #[must_use]
    pub fn delta(&self) -> Duration {
        self.delta
    }

    /// Returns the delta time in seconds.
    #[inline]
    #[must_use]
    pub fn delta_secs(&self) -> f32 {
        self.delta.as_secs_f32()
    }

    /// Returns the delta time in seconds (f64).
    #[inline]
    #[must_use]
    pub fn delta_secs_f64(&self) -> f64 {
        self.delta.as_secs_f64()
    }

    /// Returns the fixed timestep duration.
    #[inline]
    #[must_use]
    pub fn fixed_timestep(&self) -> Duration {
        self.fixed_timestep
    }

    /// Returns the fixed timestep in seconds.
    #[inline]
    #[must_use]
    pub fn fixed_timestep_secs(&self) -> f32 {
        self.fixed_timestep.as_secs_f32()
    }

    /// Sets the fixed timestep.
    #[inline]
    pub fn set_fixed_timestep(&mut self, timestep: Duration) {
        self.fixed_timestep = timestep;
    }

    /// Sets the fixed timestep from a frequency in Hz.
    #[inline]
    pub fn set_fixed_timestep_hz(&mut self, hz: f64) {
        self.fixed_timestep = Duration::from_secs_f64(1.0 / hz);
    }

    /// Checks if a fixed timestep update should run.
    ///
    /// Call this in a loop to consume accumulated time:
    ///
    /// ```rust,ignore
    /// while time.should_do_fixed_update() {
    ///     physics_step(time.fixed_timestep_secs());
    /// }
    /// ```
    #[inline]
    pub fn should_do_fixed_update(&mut self) -> bool {
        if self.accumulator >= self.fixed_timestep {
            self.accumulator -= self.fixed_timestep;
            true
        } else {
            false
        }
    }

    /// Returns the interpolation factor for rendering between fixed updates.
    ///
    /// Use this to interpolate visual positions between physics states.
    #[inline]
    #[must_use]
    pub fn interpolation_factor(&self) -> f32 {
        (self.accumulator.as_secs_f64() / self.fixed_timestep.as_secs_f64()) as f32
    }

    /// Returns the current frame count.
    #[inline]
    #[must_use]
    pub fn frame_count(&self) -> u64 {
        self.frame_count
    }

    /// Returns the average frames per second.
    #[inline]
    #[must_use]
    pub fn fps(&self) -> f64 {
        if self.elapsed.is_zero() {
            0.0
        } else {
            self.frame_count as f64 / self.elapsed.as_secs_f64()
        }
    }

    /// Returns the time scale multiplier.
    #[inline]
    #[must_use]
    pub fn time_scale(&self) -> f64 {
        self.time_scale
    }

    /// Sets the time scale multiplier.
    ///
    /// - 1.0 = normal speed
    /// - 0.5 = half speed (slow motion)
    /// - 2.0 = double speed
    /// - 0.0 = paused
    #[inline]
    pub fn set_time_scale(&mut self, scale: f64) {
        self.time_scale = scale.max(0.0);
    }

    /// Pauses time (sets scale to 0).
    #[inline]
    pub fn pause(&mut self) {
        self.time_scale = 0.0;
    }

    /// Resumes time at normal speed.
    #[inline]
    pub fn resume(&mut self) {
        self.time_scale = 1.0;
    }

    /// Returns true if time is paused.
    #[inline]
    #[must_use]
    pub fn is_paused(&self) -> bool {
        self.time_scale == 0.0
    }

    /// Returns the instant when the timer was started.
    #[inline]
    #[must_use]
    pub fn start_instant(&self) -> Instant {
        self.start_instant
    }

    /// Resets all time tracking to initial state.
    pub fn reset(&mut self) {
        let now = Instant::now();
        self.elapsed = Duration::ZERO;
        self.delta = Duration::ZERO;
        self.accumulator = Duration::ZERO;
        self.start_instant = now;
        self.last_instant = now;
        self.frame_count = 0;
        // Keep time_scale and fixed_timestep
    }
}

/// A simple stopwatch for measuring elapsed time.
#[derive(Debug, Clone)]
pub struct Stopwatch {
    start: Option<Instant>,
    elapsed: Duration,
    running: bool,
}

impl Default for Stopwatch {
    fn default() -> Self {
        Self::new()
    }
}

impl Stopwatch {
    /// Creates a new stopped stopwatch.
    #[must_use]
    pub fn new() -> Self {
        Self {
            start: None,
            elapsed: Duration::ZERO,
            running: false,
        }
    }

    /// Creates and starts a new stopwatch.
    #[must_use]
    pub fn started() -> Self {
        let mut sw = Self::new();
        sw.start();
        sw
    }

    /// Starts or resumes the stopwatch.
    pub fn start(&mut self) {
        if !self.running {
            self.start = Some(Instant::now());
            self.running = true;
        }
    }

    /// Stops the stopwatch.
    pub fn stop(&mut self) {
        if self.running {
            if let Some(start) = self.start.take() {
                self.elapsed += start.elapsed();
            }
            self.running = false;
        }
    }

    /// Resets the stopwatch to zero.
    pub fn reset(&mut self) {
        self.start = None;
        self.elapsed = Duration::ZERO;
        self.running = false;
    }

    /// Resets and starts the stopwatch.
    pub fn restart(&mut self) {
        self.reset();
        self.start();
    }

    /// Returns the elapsed time.
    #[must_use]
    pub fn elapsed(&self) -> Duration {
        let mut total = self.elapsed;
        if let Some(start) = self.start {
            total += start.elapsed();
        }
        total
    }

    /// Returns the elapsed time in seconds.
    #[must_use]
    pub fn elapsed_secs(&self) -> f32 {
        self.elapsed().as_secs_f32()
    }

    /// Returns true if the stopwatch is running.
    #[must_use]
    pub fn is_running(&self) -> bool {
        self.running
    }
}

// ============================================================================
// Async Time Utilities (requires `async` feature)
// ============================================================================

/// Async timer utilities using tokio.
#[cfg(feature = "async")]
pub mod async_time {
    use super::Duration;

    /// Sleeps for the specified duration asynchronously.
    ///
    /// This is a thin wrapper around `tokio::time::sleep` for convenience.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// use sable_core::time::async_time::sleep;
    /// use std::time::Duration;
    ///
    /// async fn example() {
    ///     sleep(Duration::from_millis(100)).await;
    /// }
    /// ```
    pub async fn sleep(duration: Duration) {
        tokio::time::sleep(duration).await;
    }

    /// Sleeps for the specified number of seconds asynchronously.
    pub async fn sleep_secs(secs: f64) {
        tokio::time::sleep(Duration::from_secs_f64(secs)).await;
    }

    /// Sleeps for the specified number of milliseconds asynchronously.
    pub async fn sleep_millis(millis: u64) {
        tokio::time::sleep(Duration::from_millis(millis)).await;
    }

    /// An async interval timer that ticks at a fixed rate.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// use sable_core::time::async_time::Interval;
    /// use std::time::Duration;
    ///
    /// async fn game_loop() {
    ///     let mut interval = Interval::new(Duration::from_secs_f64(1.0 / 60.0));
    ///
    ///     loop {
    ///         interval.tick().await;
    ///         // Update game state at 60 Hz
    ///     }
    /// }
    /// ```
    pub struct Interval {
        inner: tokio::time::Interval,
    }

    impl Interval {
        /// Creates a new interval timer.
        #[must_use]
        pub fn new(period: Duration) -> Self {
            Self {
                inner: tokio::time::interval(period),
            }
        }

        /// Creates an interval timer from a frequency in Hz.
        #[must_use]
        pub fn from_hz(hz: f64) -> Self {
            Self::new(Duration::from_secs_f64(1.0 / hz))
        }

        /// Waits for the next tick.
        pub async fn tick(&mut self) -> tokio::time::Instant {
            self.inner.tick().await
        }

        /// Returns the period of this interval.
        #[must_use]
        pub fn period(&self) -> Duration {
            self.inner.period()
        }
    }

    /// A timeout wrapper for async operations.
    ///
    /// # Errors
    ///
    /// Returns [`TimeoutError`] if the future does not complete within the specified duration.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// use sable_core::time::async_time::timeout;
    /// use std::time::Duration;
    ///
    /// async fn example() {
    ///     match timeout(Duration::from_secs(5), some_async_operation()).await {
    ///         Ok(result) => println!("Got result: {:?}", result),
    ///         Err(_) => println!("Operation timed out"),
    ///     }
    /// }
    /// ```
    pub async fn timeout<F, T>(duration: Duration, future: F) -> Result<T, TimeoutError>
    where
        F: std::future::Future<Output = T>,
    {
        tokio::time::timeout(duration, future)
            .await
            .map_err(|_| TimeoutError)
    }

    /// Error returned when a timeout expires.
    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
    pub struct TimeoutError;

    impl std::fmt::Display for TimeoutError {
        fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
            write!(f, "operation timed out")
        }
    }

    impl std::error::Error for TimeoutError {}

    /// A debouncer that ensures an operation is not called more frequently than a given interval.
    ///
    /// Useful for rate-limiting operations like auto-save or network requests.
    pub struct Debouncer {
        last_triggered: Option<tokio::time::Instant>,
        interval: Duration,
    }

    impl Debouncer {
        /// Creates a new debouncer with the given minimum interval.
        #[must_use]
        pub fn new(interval: Duration) -> Self {
            Self {
                last_triggered: None,
                interval,
            }
        }

        /// Checks if enough time has passed since the last trigger.
        ///
        /// If true, updates the last triggered time.
        pub fn should_trigger(&mut self) -> bool {
            let now = tokio::time::Instant::now();
            match self.last_triggered {
                Some(last) if now.duration_since(last) < self.interval => false,
                _ => {
                    self.last_triggered = Some(now);
                    true
                }
            }
        }

        /// Returns the time until the next trigger is allowed.
        #[must_use]
        pub fn time_until_ready(&self) -> Duration {
            match self.last_triggered {
                Some(last) => {
                    let elapsed = tokio::time::Instant::now().duration_since(last);
                    self.interval.saturating_sub(elapsed)
                }
                None => Duration::ZERO,
            }
        }

        /// Waits until the debouncer is ready to trigger again.
        pub async fn wait_until_ready(&mut self) {
            let wait_time = self.time_until_ready();
            if !wait_time.is_zero() {
                tokio::time::sleep(wait_time).await;
            }
            self.last_triggered = Some(tokio::time::Instant::now());
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::thread::sleep;

    #[test]
    fn test_time_new() {
        let time = Time::new();
        assert_eq!(time.frame_count(), 0);
        assert_eq!(time.elapsed(), Duration::ZERO);
        assert_eq!(time.delta(), Duration::ZERO);
        assert!((time.time_scale() - 1.0).abs() < f64::EPSILON);
    }

    #[test]
    fn test_time_update_with_delta() {
        let mut time = Time::new();
        let delta = Duration::from_millis(16);

        time.update_with_delta(delta);

        assert_eq!(time.frame_count(), 1);
        assert_eq!(time.delta(), delta);
        assert_eq!(time.elapsed(), delta);
    }

    #[test]
    fn test_time_multiple_updates() {
        let mut time = Time::new();
        let delta = Duration::from_millis(16);

        time.update_with_delta(delta);
        time.update_with_delta(delta);
        time.update_with_delta(delta);

        assert_eq!(time.frame_count(), 3);
        assert_eq!(time.elapsed(), delta * 3);
    }

    #[test]
    fn test_time_scale() {
        let mut time = Time::new();
        time.set_time_scale(0.5);

        let delta = Duration::from_millis(100);
        time.update_with_delta(delta);

        // With 0.5 time scale, effective delta should be 50ms
        assert_eq!(time.delta(), Duration::from_millis(50));
    }

    #[test]
    fn test_time_pause_resume() {
        let mut time = Time::new();

        time.pause();
        assert!(time.is_paused());

        let delta = Duration::from_millis(100);
        time.update_with_delta(delta);

        // Paused, so no time should pass
        assert_eq!(time.elapsed(), Duration::ZERO);

        time.resume();
        assert!(!time.is_paused());

        time.update_with_delta(delta);
        assert_eq!(time.elapsed(), delta);
    }

    #[test]
    fn test_fixed_timestep() {
        let mut time = Time::with_fixed_timestep(60.0);

        // Simulate a 32ms frame (almost 2 fixed updates at 60Hz)
        time.update_with_delta(Duration::from_millis(32));

        let mut count = 0;
        while time.should_do_fixed_update() {
            count += 1;
        }

        // At 60Hz (16.67ms), 32ms should give us 1 update with some remainder
        assert_eq!(count, 1);

        // Do another frame
        time.update_with_delta(Duration::from_millis(32));

        let mut count = 0;
        while time.should_do_fixed_update() {
            count += 1;
        }

        // Should catch up with accumulated time
        assert!(count >= 1);
    }

    #[test]
    fn test_interpolation_factor() {
        let mut time = Time::with_fixed_timestep(60.0);

        // Exactly one fixed timestep
        time.update_with_delta(time.fixed_timestep());
        time.should_do_fixed_update();

        // Should be close to 0 after consuming the fixed update
        assert!(time.interpolation_factor() < 0.1);
    }

    #[test]
    fn test_time_reset() {
        let mut time = Time::new();
        time.update_with_delta(Duration::from_millis(100));
        time.update_with_delta(Duration::from_millis(100));

        time.reset();

        assert_eq!(time.frame_count(), 0);
        assert_eq!(time.elapsed(), Duration::ZERO);
    }

    #[test]
    fn test_stopwatch_new() {
        let sw = Stopwatch::new();
        assert!(!sw.is_running());
        assert_eq!(sw.elapsed(), Duration::ZERO);
    }

    #[test]
    fn test_stopwatch_started() {
        let sw = Stopwatch::started();
        assert!(sw.is_running());
    }

    #[test]
    fn test_stopwatch_start_stop() {
        let mut sw = Stopwatch::new();

        sw.start();
        assert!(sw.is_running());

        sleep(Duration::from_millis(10));

        sw.stop();
        assert!(!sw.is_running());
        assert!(sw.elapsed() >= Duration::from_millis(10));
    }

    #[test]
    fn test_stopwatch_accumulates() {
        let mut sw = Stopwatch::new();

        sw.start();
        sleep(Duration::from_millis(10));
        sw.stop();

        let first = sw.elapsed();

        sw.start();
        sleep(Duration::from_millis(10));
        sw.stop();

        // Should have accumulated both periods
        assert!(sw.elapsed() >= first + Duration::from_millis(10));
    }

    #[test]
    fn test_stopwatch_reset() {
        let mut sw = Stopwatch::started();
        sleep(Duration::from_millis(10));

        sw.reset();

        assert!(!sw.is_running());
        assert_eq!(sw.elapsed(), Duration::ZERO);
    }

    #[test]
    fn test_stopwatch_restart() {
        let mut sw = Stopwatch::started();
        sleep(Duration::from_millis(10));

        sw.restart();

        assert!(sw.is_running());
        // Elapsed should be very small after restart
        assert!(sw.elapsed() < Duration::from_millis(5));
    }

    #[test]
    fn test_fps() {
        let mut time = Time::new();

        // Simulate 60 frames at 16.67ms each
        for _ in 0..60 {
            time.update_with_delta(Duration::from_micros(16667));
        }

        // FPS should be approximately 60
        let fps = time.fps();
        assert!(fps > 59.0 && fps < 61.0, "FPS was {fps}");
    }
}