Add playback controls to Timer

[waynemwashuma]

Objective

Changes the Timer class to enable playback control, cycle detection, and progress tracking.It replaces the previous static methods with instance methods. The changes also update dependent systems to use the new API.It also changes the constructor of Timer to pass a configuration object.

Solution

The new implementation provides:

• Instance-based API for all timer operations, no static methods.
• Playback Control with methods like play(), pause(), start(), stop(), seek() and reset()
• Cycle Detection through cycleStarted() and cycleEnded() methods which detect when timer cycles begin and end respectively.
• Progress tracking of the timer using progress() method which returns normalized progress (0.0 to 1.0) and elapsed which returns the time in seconds the timer has moved forward.
• Change detection through playbackChanged() method detects when playback state is modified and requestPlayback which marks a playback is required by the timer.

Showcase

Basic Timer Usage:

// Create a 1-second repeating timer
const timer = new Timer({
  duration: 1,
  mode: TimerMode.Repeat
})

// Control playback
timer.play()    // resume
timer.pause()   // Pause
timer.start()   // Restart from beginning
timer.stop()    // Stop and reset to 0
timer.reset()   // Restart from beginning
timer.seek(0.5) // Jump to 0.5s

// Update each frame
timer.update(deltaTime)

// Check state
if (timer.cycleStarted()) {
  // A new cycle just began
}

if (timer.cycleEnded()) {
  // A cycle just completed
}

const progress = timer.progress() // 0.0 to 1.0

Migration Guide

• Replace static methods with instance methods.

const timer = new Timer()
const dt = 0.016667

// before
Timer.update(timer,dt)
Timer.reset(timer)
// after
timer.update(dt)
timer.reset()

• Replace new Timer(duration, mode) with new Timer({duration, mode})

// Before
const timer = new Timer(1,TimerMode.Repeat)

// after
const timer = new Timer({duration:1,mode:TimerMode.Repeat})

• Replace timer.finished checks with timer.cycleStarted() or timer.cycleEnded() if checking for cycle or completed to check if timer has completed

Checklist

• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my changes