@web-engine-dev/timeline

Seven-track cinematic sequencer for cutscenes, trailers, and in-game cinematics. Provides a declarative, keyframe-based timeline that drives animations, audio, camera, events, particles, dialogue, and post-processing over time.

Layer 7 · Gameplay

Features

• 7 Track Types: Animation, Audio, Camera, Events, Particles, Dialogue, Post-Processing
• Keyframe Curves: Per-property animation with configurable easing (linear, ease-in/out, cubic, custom)
• Nested Timelines: Sub-timelines for reusable cinematic sequences
• Scrubbing: Seek to any point — all tracks resolve correctly (no delta-time dependency)
• Looping & Ping-Pong: Per-track and per-timeline loop modes
• Blending: Smooth transitions between timeline control and gameplay control
• Events Track: Fire callbacks at specific timestamps
• Speed Control: Playback speed multiplier, reverse, and variable time-scale

Installation

npm install @web-engine-dev/timeline
# or
pnpm add @web-engine-dev/timeline

Quick Start

import { Timeline, AnimationTrack, CameraTrack, AudioTrack } from '@web-engine-dev/timeline';

const cutscene = new Timeline({ duration: 10.0 });

// Camera dolly
cutscene.addTrack(
  new CameraTrack({
    keyframes: [
      { time: 0, position: [0, 5, 10], lookAt: [0, 0, 0] },
      { time: 5, position: [5, 3, 8], lookAt: [2, 1, 0], easing: 'ease-in-out' },
      { time: 10, position: [10, 2, 5], lookAt: [5, 0, 0] },
    ],
  })
);

// Character animation
cutscene.addTrack(
  new AnimationTrack({
    target: heroEntity,
    clip: 'wave',
    startTime: 2.0,
    duration: 3.0,
  })
);

// Background music
cutscene.addTrack(
  new AudioTrack({
    asset: 'music/dramatic.ogg',
    startTime: 0,
    fadeIn: 1.0,
  })
);

// Play
cutscene.play();

// Scrub to a specific time
cutscene.seek(7.5);

Track Types

Track	Controls	Key Features
Animation	Entity animations	Blend with gameplay, cross-fade clips
Audio	Sound effects, music	Fade in/out, spatial audio, volume curves
Camera	Camera position/rotation	Dolly, orbit, shake, depth of field
Events	Callbacks/triggers	Spawn entities, UI prompts, state changes
Particles	Particle systems	Start/stop emitters, burst triggers
Dialogue	Subtitle/VO playback	Text display, audio sync, choices
Post-Processing	Screen effects	Bloom, vignette, color grading transitions

Dependencies

• @web-engine-dev/time — Clock and time management
• @web-engine-dev/animation — Animation clip playback
• @web-engine-dev/audio — Audio system
• @web-engine-dev/camera — Camera control