TimeController

The TimeController class is the animation clock: a wall-clock × speed rAF loop that layers subscribe to for synchronized animation. It deliberately knows nothing about data loading — in any networked app, drive it through a PlaybackGovernor, which gates play/resume/seek on the buffered runway so the clock never advances into unloaded time.

New integrations: SttPlayer is the recommended single entry point — it wires a TimeController and PlaybackGovernor together for you. Both remain the underlying pieces and are fully usable standalone as documented here.

Installation#

import { TimeController } from '@poopdeck.gl/playback';

Usage#

import { TimeController, PlaybackGovernor } from '@poopdeck.gl/playback';
import { AnimatedPointLayer } from '@poopdeck.gl/layers';

const timeController = new TimeController({
  initialTime: Date.parse('2020-01-01'),
  speed: 86400000 / 1000, // 1 day per second
  loop: true,
  timeRange: {
    start: Date.parse('2020-01-01'),
    end: Date.parse('2020-12-31'),
  },
  tickThrottleMs: 16,
});

// Recommended: gate playback on data readiness.
const governor = new PlaybackGovernor(timeController);

const layer = new AnimatedPointLayer({
  id: 'earthquakes',
  data: 'https://example.com/earthquakes/manifest.json',
  timeController, // layer subscribes automatically
  timeWindow: 86400000,
  onTilesetReady: (tileset) => governor.setSource(tileset),
  onBufferChange: (runway) => governor.notifyBufferChange(runway),
});

// Drive playback through the governor…
governor.requestPlay();
governor.requestPause();
governor.seekTo(Date.parse('2020-06-15'));

// …or, for offline/test scenarios, the controller directly:
timeController.play();
timeController.pause();
timeController.seek(Date.parse('2020-06-15'));

Constructor Options#

Playback boundary behavior#

With a timeRange, hitting a boundary does one of three things:

1. bounce: true — reflect and reverse direction; fires a playState notification (the speed's sign flipped) so tile loaders re-aim their prefetch immediately.
2. loop: true — teleport to the other end; fires the wrap event. The wrap is a teleport-seek the clock performed on its own; the PlaybackGovernor subscribes to wrap and routes it through seek semantics (flush stale prefetch, startup-sized gate) instead of letting playback run ungated into possibly-unloaded time.
3. Neither — clamp to the boundary, pause(), and fire the ended event with the clamped time. Distinct from a user pause: the clock ran out of range (media-element 'ended' semantics) — UIs show a replay affordance, and the PlaybackGovernor restarts from the range start on the next play.

Frame-delta clamp and tab refocus#

Browsers suspend requestAnimationFrame in background tabs, so without protection the first frame after a refocus would advance time by the ENTIRE background duration — a playhead teleport. Two defenses are built in:

• every frame's wall-clock delta is clamped to 250 ms (any real frame longer than that is dropped-frames jank where advancing by the full gap would only compound the stutter), and
• a visibilitychange handler re-anchors the frame clock when the tab becomes visible while playing, removing even the clamped jump. The handler is registered in play() and removed in pause() / destroy(), so idle controllers add no document listeners.

Methods#

Playback Control#

External clock (host-driven frames)#

The advance is coalesced per animation frame on document.timeline.currentTime, which the browser holds constant for every task between two rendering opportunities, so every draw in one frame reads the same token regardless of callback ORDER (an rAF-callback counter cannot promise that — whether the host schedules its next frame before or after drawing would decide it). The coalesce is load-bearing: deck.gl's React wrapper redraws SYNCHRONOUSLY from a dependency-less layout effect, so onBeforeRender fires once per React commit, not once per frame; without it the clock ticks per render and any playback state a tick produces (a stall freezing the clock, a gate opening it) re-enters React from inside its own commit → render → draw → tick chain — which React reports as "Maximum update depth exceeded". No sim-time is lost by skipping a draw: the step integrates performance.now() - lastUpdateTime, so the next accepted advance covers the whole elapsed span. Where no document timeline exists (workers, Node, headless hosts) every call advances.

The deck.gl wiring is packaged as useDeckClock.

State Access#

Event Handling#

on() returns an unsubscribe function, so cleanup doesn't have to retain the callback:

const unsubscribe = timeController.on('tick', (time) => render(time));
// later (e.g. effect cleanup):
unsubscribe(); // equivalent to timeController.off('tick', callback)

Types#

interface TimeControllerOptions {
  initialTime?: number;
  speed?: number;
  loop?: boolean;
  bounce?: boolean;
  timeRange?: { start: number; end: number };
  tickThrottleMs?: number;
}

interface TimeControllerState {
  currentTime: number;
  playing: boolean;
  speed: number; // signed effective rate: direction × magnitude
  direction: 1 | -1; // travel direction, kept separate from the rate (bounce flips only this)
  loop: boolean;
}

Both are exported from @poopdeck.gl/playback. The tick/wrap/ended callbacks receive (time: number); playState receives (playing: boolean, speed: number) — see the events table.

Integration with Layers#

When you pass a TimeController to a layer via the timeController prop, the layer automatically:

1. Subscribes to tick events for time updates (read via a getTime getter in the shader extension's draw() — no React re-render per frame)
2. Subscribes to playState events to drive prefetch sizing and direction
3. Unsubscribes when the layer is finalized

Source#

packages/playback/src/time-controller.ts