Timeline模块

The timeline module provides a complete timeline-control system for animations, including playback, time computation, and state management. It implements a layered architecture with clear separation of concerns: state management, time calculation, and update strategies.

Overview

Core Capabilities:

• Unified Timeline Control Interface – TimelineController implements ITimelineTarget for consistent API
• Multiple Time-Update Modes – Fixed delta (deterministic) and variable delta (smooth playback)
• Animation State Management – Play, pause, resume, stop with state machine
• Time Math Utilities – Time scaling, offsets, and delta computation
• Event System – Observer pattern for reacting to time/state changes
• Fallback Preview Mode – Detection for preview scenarios
• Performance Tracking – Frame counting and statistics

Quick Start

Basic Usage

import { TimelineController } from './timeline';

const timeline = new TimelineController({
  timeScale: 1.0,
  animationSpeed: 1.0,
  timeUpdateMode: 'fixed_delta',
  fixedDeltaTime: 0.016, // ~60 FPS
  maxDeltaTime: 0.05
});

// Playback control
timeline.start(1.0); // Start at 1x speed
timeline.pause();
timeline.resume();
timeline.stop();

// Time control
timeline.setTime(5.0);
timeline.setSpeed(2.0); // 2x speed
timeline.setTimeScale(0.5); // Half speed

// Update loop
function animate() {
  requestAnimationFrame(animate);
  const currentTime = timeline.update(performance.now());
  // Use currentTime for animations
}

Event Listeners

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

Compatibility Methods

The TimelineController also provides compatibility methods for existing code:

timeline.startAnimation(1.0);
timeline.pauseAnimation();
timeline.resumeAnimation();
timeline.stopAnimation();
timeline.setAnimationTime(5.0);
timeline.setAnimationSpeed(2.0);

Features

Time Update Modes

• Fixed Delta (fixed_delta) – Deterministic time steps for consistent animation playback
• Variable Delta (variable_delta) – Frame-rate dependent time steps for smooth playback

Animation States

• Play – Start animation with optional speed multiplier
• Pause – Pause animation (preserves current time)
• Resume – Resume from paused state
• Stop – Stop animation and reset frame count

Time Control

• Time Scaling – Adjust playback speed (1.0 = normal, 2.0 = 2x, 0.5 = 0.5x)
• Time Offset – Shift timeline origin
• Animation Speed – Per-animation speed multiplier
• Direct Time Setting – Jump to specific time value

Events

• State Change Events – play, pause, resume, stop
• Time Change Events – timeChange when time is set directly
• Speed Change Events – speedChange when speed is modified

Advanced Features

• Fallback Preview Mode – Detection for preview scenarios (when frameTime < -0.5)
• Performance Statistics – Frame count, average frame time, playback state
• Event System – Observer pattern with error handling
• State Machine – Clean state transitions with validation

Architecture

The timeline module uses a layered architecture with clear separation of concerns:

1. TimelineController – High-level façade that orchestrates all timeline functionality
2. AnimationState – State machine for playback state (playing/paused/stopped) and speed
3. TimeCalculator – Time computation engine (scaling, offsets, delta calculation)
4. TimeUpdateMode – Strategy pattern for delta computation (fixed vs variable)
5. Event System – Observer pattern for time/state change notifications

Component Relationships

TimelineController (Facade)
├── AnimationState (State Machine)
│   └── Event Listeners
├── TimeCalculator (Time Math)
│   └── TimeUpdateModeHelper (Strategy)
└── Event System (Observer)

See Architecture Guide for detailed design decisions.

Dependencies

• Pure TypeScript – No external dependencies
• No Runtime Requirements – Works in any JavaScript environment
• Decoupled Design – Independent from Three.js/WebGPU systems
• Performance API – Uses performance.now() for high-precision timing

Integration

The timeline module integrates with:

• AnimationManager – Uses timeline for dynamic model updates
• RenderLoop – Can be integrated for frame-based time updates
• Export Media – Used for video recording and frame export
• Dynamic Point Clouds – Provides time values for ONNX-driven animations

Related Docs

• Architecture – State machine diagrams, time calculator strategies, and event flow.
• API Reference – Public controller methods, update modes, and helper types.
• ONNX Module – Shows how dynamic generators consume timeline timecodes.
• Manager Module – Details how AnimationManager wires the timeline into the render loop.