Timeline Module API Reference

Complete API documentation for the timeline classes and interfaces.

TimelineController

Primary controller that orchestrates all timeline functionality. Implements ITimelineTarget interface.

constructor(config?: Partial)

Creates a new timeline controller with optional configuration. Defaults: - timeScale: 1.0 - timeOffset: 0.0 - timeUpdateMode: 'fixed_delta' - animationSpeed: 1.0 - fixedDeltaTime: 0.016 * 1.10 (~60 FPS) - maxDeltaTime: 0.05 (50ms)

Playback Controls

start(speed?: number): void – Start playback with optional speed multiplier
pause(): void – Pause playback (preserves current time)
resume(): void – Resume from paused state
stop(): void – Stop playback and reset frame count

Compatibility Methods: - startAnimation(speed?: number): void – Alias for start() - pauseAnimation(): void – Alias for pause() - resumeAnimation(): void – Alias for resume() - stopAnimation(): void – Alias for stop()

Time Controls

setTime(time: number): void – Set current time directly (seconds)
setSpeed(speed: number): void – Set animation speed multiplier
setTimeScale(scale: number): void – Set time scaling factor
setTimeOffset(offset: number): void – Set time offset (seconds)
setTimeUpdateMode(mode: 'fixed_delta' | 'variable_delta'): void – Set update mode

Compatibility Methods: - setAnimationTime(time: number): void – Alias for setTime() - setAnimationSpeed(speed: number): void – Alias for setSpeed()

Update

update(rafNow?: number): number – Update timeline (call each frame). Returns adjusted time. If rafNow not provided, uses performance.now()

Queries

Time: - getCurrentTime(): number – Get current adjusted time - getFrameTime(): number – Get raw frame time (before adjustment) - getAdjustedTime(): number – Alias for getCurrentTime()

State: - getPlaybackState(): AnimationPlaybackState – Get current playback state - isPlaying(): boolean – Check if playing - isPaused(): boolean – Check if paused - isStopped(): boolean – Check if stopped - supportsAnimation(): boolean – Always returns true

Configuration: - getAnimationSpeed(): number – Get current animation speed - getTimeScale(): number – Get current time scale - getTimeOffset(): number – Get current time offset - getTimeUpdateMode(): 'fixed_delta' | 'variable_delta' – Get current update mode

Advanced: - isFallbackPreviewMode(): boolean – Check if in fallback preview mode (frameTime < -0.5) - getStats(): TimelineStats – Get comprehensive statistics

Events

addEventListener(listener: TimelineEventListener): void – Register event listener
removeEventListener(listener: TimelineEventListener): void – Remove event listener
clearEventListeners(): void – Clear all event listeners

Static Properties

TimelineController.FALLBACK_PREVIEW_THRESHOLD – Constant: -0.5 (threshold for fallback preview mode)

AnimationState

Tracks playback state and manages state transitions with validation.

constructor()

Creates a new animation state manager. Initial state: STOPPED, speed: 1.0.

Playback Control

play(speed?: number = 1.0): void – Start playing. Speed is clamped to minimum 0.1x.
pause(): void – Pause (only if currently playing)
resume(): void – Resume (only if currently paused)
stop(): void – Stop and reset to stopped state
reset(): void – Reset to stopped state with speed 1.0

Speed Control

setSpeed(speed: number): void – Set animation speed (clamped to minimum 0.1x). Emits speedChange event if changed.
getSpeed(): number – Get current animation speed

State Queries

Properties (read-only): - playbackState: AnimationPlaybackState – Current playback state - animationSpeed: number – Current animation speed - isPlaying: boolean – True if playing - isPaused: boolean – True if paused - isStopped: boolean – True if stopped

Methods: - getState(): AnimationPlaybackState – Get current state - getStateInfo(): object – Get comprehensive state information

Events

addEventListener(listener: TimelineEventListener): void – Register event listener
removeEventListener(listener: TimelineEventListener): void – Remove event listener
clearEventListeners(): void – Clear all event listeners

Event Types: - play – Emitted when playback starts - pause – Emitted when playback pauses - resume – Emitted when playback resumes - stop – Emitted when playback stops - speedChange – Emitted when speed changes (includes oldSpeed and newSpeed in data)

TimeCalculator

Performs time scaling, offset calculations, and delta time computation.

constructor(config?: Partial)

Creates a new time calculator with optional configuration. Uses defaults if not provided.

Time Control

setTime(time: number): void – Set frame time directly (resets last update time for variable mode)
resetTime(): void – Reset frame time to 0
setTimeScale(scale: number): void – Set time scaling factor (clamped to minimum 0.01)
getTimeScale(): number – Get current time scale
setTimeOffset(offset: number): void – Set time offset (seconds)
getTimeOffset(): number – Get current time offset

Update Mode

setTimeUpdateMode(mode: 'fixed_delta' | 'variable_delta'): void – Set update mode (resets last update time for variable mode)
getTimeUpdateMode(): 'fixed_delta' | 'variable_delta' – Get current update mode

Animation Speed

setAnimationSpeed(speed: number): void – Set animation speed (clamped to minimum 0.1x)
getAnimationSpeed(): number – Get current animation speed

Time Calculation

calculateTime(rafNow?: number, isPlaying?: boolean, isPaused?: boolean): TimeCalculationResult – Calculate time delta and update frame time. Returns:
deltaTime: number – Calculated time delta
frameTime: number – Accumulated frame time
adjustedTime: number – Time with scaling and offset applied
shouldUpdate: boolean – Whether time was updated

Queries

Properties (read-only): - frameTime: number – Current frame time (before adjustment) - config: Readonly<TimelineConfig> – Current configuration

Methods: - getAdjustedTime(): number – Get adjusted time (with scaling and offset) - getStats(): object – Get comprehensive statistics

Configuration

updateConfig(newConfig: Partial<TimelineConfig>): void – Update configuration
clone(): TimeCalculator – Clone calculator with current state

TimeUpdateMode

Enum and helper utilities for time update modes.

TimeUpdateMode Enum

enum TimeUpdateMode {
  FIXED_DELTA = 'fixed_delta',      // Deterministic fixed steps
  VARIABLE_DELTA = 'variable_delta'  // Frame-rate dependent
}

TimeUpdateModeHelper

Static helper class for time update mode operations.

Delta Calculation: - calculateDeltaTime(params): number – Calculates time delta based on mode:

params: {
  mode: TimeUpdateMode;
  currentTime: number;        // performance.now()
  lastUpdateTime: number;      // Previous update time
  fixedDeltaTime: number;      // Fixed delta value
  maxDeltaTime: number;        // Max delta clamp
}

- Fixed Delta: Returns fixedDeltaTime directly - Variable Delta: Calculates from time difference, clamped to maxDeltaTime

Validation: - isValidMode(mode: string): mode is TimeUpdateMode – Type guard to check if mode is valid - fromString(modeString: string): TimeUpdateMode – Converts string to enum (defaults to FIXED_DELTA if invalid)

Defaults: - getDefaultFixedDeltaTime(): number – Returns 0.016 * 1.10 (~60 FPS) - getDefaultMaxDeltaTime(): number – Returns 0.05 (50ms)

Descriptions: - getModeDescription(mode: TimeUpdateMode): string – Returns human-readable description

Types and Interfaces

TimelineConfig

interface TimelineConfig {
  /** Time scaling factor (1.0 = normal, 2.0 = 2x, 0.5 = 0.5x) */
  timeScale: number;
  /** Time offset in seconds */
  timeOffset: number;
  /** Time update mode */
  timeUpdateMode: 'fixed_delta' | 'variable_delta';
  /** Animation speed multiplier */
  animationSpeed: number;
  /** Fixed delta time in seconds (for fixed_delta mode) */
  fixedDeltaTime: number;
  /** Maximum delta time in seconds (clamp for variable_delta mode) */
  maxDeltaTime: number;
}

TimelineStats

interface TimelineStats {
  /** Current frame time */
  currentTime: number;
  /** Adjusted time (with scaling and offset) */
  adjustedTime: number;
  /** Time scaling factor */
  timeScale: number;
  /** Time offset */
  timeOffset: number;
  /** Time update mode */
  timeUpdateMode: string;
  /** Animation speed */
  animationSpeed: number;
  /** Playback state */
  playbackState: AnimationPlaybackState;
  /** Whether currently playing */
  isPlaying: boolean;
  /** Whether currently paused */
  isPaused: boolean;
  /** Whether currently stopped */
  isStopped: boolean;
  /** Last update timestamp */
  lastUpdateTime: number;
  /** Accumulated frame count */
  frameCount: number;
}

AnimationPlaybackState

enum AnimationPlaybackState {
  STOPPED = 'stopped',
  PLAYING = 'playing',
  PAUSED = 'paused'
}

TimeCalculationResult

interface TimeCalculationResult {
  /** Calculated time delta */
  deltaTime: number;
  /** Accumulated frame time */
  frameTime: number;
  /** Adjusted time (with scaling and offset) */
  adjustedTime: number;
  /** Whether time was updated */
  shouldUpdate: boolean;
}

TimeCalculationParams

interface TimeCalculationParams {
  /** Current timestamp (performance.now()) */
  currentTime: number;
  /** Last update timestamp */
  lastUpdateTime: number;
  /** Time scaling factor */
  timeScale: number;
  /** Animation speed multiplier */
  animationSpeed: number;
  /** Time update mode */
  timeUpdateMode: 'fixed_delta' | 'variable_delta';
  /** Fixed delta time */
  fixedDeltaTime: number;
  /** Maximum delta time */
  maxDeltaTime: number;
}

AnimationStateChangeEvent

interface AnimationStateChangeEvent {
  /** Event type */
  type: 'play' | 'pause' | 'resume' | 'stop' | 'timeChange' | 'speedChange';
  /** Event timestamp */
  timestamp: number;
  /** Event data (varies by type) */
  data?: any;
}

TimelineEventListener

type TimelineEventListener = (event: AnimationStateChangeEvent) => void;

ITimelineTarget

Interface implemented by TimelineController for consistent API:

interface ITimelineTarget {
  // Playback control
  startAnimation(speed?: number): void;
  pauseAnimation(): void;
  resumeAnimation(): void;
  stopAnimation(): void;

  // Time control
  setAnimationTime(time: number): void;
  setAnimationSpeed(speed: number): void;
  getAnimationSpeed(): number;

  // Time scaling
  setTimeScale(scale: number): void;
  getTimeScale(): number;
  setTimeOffset(offset: number): void;
  getTimeOffset(): number;

  // Update mode
  setTimeUpdateMode(mode: 'fixed_delta' | 'variable_delta'): void;
  getTimeUpdateMode(): 'fixed_delta' | 'variable_delta';

  // Queries
  getCurrentTime(): number;
  supportsAnimation(): boolean;
}

Usage Examples

Basic Timeline Usage

import { TimelineController } from './timeline';

const timeline = new TimelineController({
  timeScale: 1.0,
  animationSpeed: 1.0,
  timeUpdateMode: 'fixed_delta',
  fixedDeltaTime: 0.016,
});

timeline.addEventListener(event => {
  console.log('Timeline event:', event);
});

timeline.start();

function animate() {
  requestAnimationFrame(animate);
  const currentTime = timeline.update(performance.now());
  updateAnimations(currentTime);
}

Variable Delta Mode

const timeline = new TimelineController({
  timeScale: 2.0,
  timeOffset: 5.0,
  animationSpeed: 1.5,
  timeUpdateMode: 'variable_delta',
  maxDeltaTime: 0.05,
});

timeline.setTimeScale(0.5);
timeline.setTimeOffset(10.0);

const stats = timeline.getStats();
console.log('Timeline stats:', stats);

State Management

if (timeline.isPlaying()) {
  console.log('Animation is playing');
}

timeline.pause();
// ... custom logic
timeline.resume();

timeline.stop();
timeline.setTime(0);

Event Handling

timeline.addEventListener((event) => {
  switch (event.type) {
    case 'play':
      console.log('Animation started at speed:', event.data.speed);
      break;
    case 'pause':
      console.log('Animation paused');
      break;
    case 'timeChange':
      console.log('Time changed to:', event.data.time);
      break;
    case 'speedChange':
      console.log('Speed changed:', event.data.oldSpeed, '→', event.data.newSpeed);
      break;
  }
});

Fallback Preview Mode

if (timeline.isFallbackPreviewMode()) {
  console.log('In fallback preview mode');
  // Handle preview/export scenario
}

Integration with AnimationManager

// In render loop
const time = timeline.update(performance.now());
animationManager.setDynamicAnimationTime(time);

Notes

Update Modes:
fixed_delta – Use for deterministic steps (physics, deterministic animations)
variable_delta – Use for smooth playback (frame-rate dependent animations)
Performance:
Avoid calling setTime() every frame; prefer event listeners over polling
Use update() method in render loop for automatic time progression
Event listeners are batched and error-handled
Precision:
Uses performance.now() for high-precision timing
Microsecond precision is supported
Time values are in seconds
State Synchronization:
State changes automatically trigger events
Events include timestamp and relevant data
Listeners are called synchronously
Validation:
Invalid config values are clamped to safe ranges:
- timeScale: minimum 0.01
- animationSpeed: minimum 0.1x
- maxDeltaTime: clamps variable delta to prevent extreme values
State transitions are validated (e.g., can't pause if not playing)
Fallback Preview Mode:
Detected when frameTime < -0.5
Useful for export/recording scenarios
Access via isFallbackPreviewMode() or TimelineController.FALLBACK_PREVIEW_THRESHOLD
Compatibility:
TimelineController provides compatibility methods for legacy code
Both new API (start(), pause()) and legacy API (startAnimation(), pauseAnimation()) are supported

Timeline Module API Reference

Table of Contents

TimelineController

constructor(config?: Partial)

Playback Controls

Time Controls

Update

Queries

Events

Static Properties

AnimationState

constructor()

Playback Control

Speed Control

State Queries

Events

TimeCalculator

constructor(config?: Partial)

Time Control

Update Mode

Animation Speed

Time Calculation

Queries

Configuration

TimeUpdateMode

TimeUpdateMode Enum

TimeUpdateModeHelper

Types and Interfaces

TimelineConfig

TimelineStats

AnimationPlaybackState

TimeCalculationResult

TimeCalculationParams

AnimationStateChangeEvent

TimelineEventListener

ITimelineTarget

Usage Examples

Basic Timeline Usage

Variable Delta Mode

State Management

Event Handling

Fallback Preview Mode

Integration with AnimationManager

Notes