Should a Three.js animation use Clock.getDelta() or wall-clock timestamps for long-running scenes?

Direct Answer

Use THREE.Clock.getDelta() (which internally relies on performance.now()) for all frame‑driven motion such as rotations, shader time uniforms, and physics steps. Use Date.now() (or a stored UTC epoch captured at start) for any event that must fire at a specific real‑world moment, e.g. a scheduled API timestamp.

Why the Two Sources Are Different

• Clock.getDelta() returns the monotonic, high‑resolution time between consecutive requestAnimationFrame callbacks. Accumulating these deltas over hours or days adds only microseconds of floating‑point drift, which is negligible for visual animation.
• Date.now() provides an absolute UTC timestamp tied to the system clock. It is the only reliable way to match a calendar‑based deadline, but it can jump forward or backward due to NTP adjustments or user changes.

Recommended Synchronization Pattern

// One‑time setup
const startPerf = performance.now();
const startUtc  = Date.now();
const clock = new THREE.Clock();

function animate() {
  const delta = clock.getDelta();               // frame‑rate independent motion
  const nowUtc = Date.now();
  const elapsedReal = nowUtc - startUtc;        // real‑world elapsed ms

  // Example frame‑driven update
  mesh.rotation.y += rotationSpeed * delta;

  // Example scheduled event
  if (elapsedReal >= deadlineMs) {
    triggerScheduledEvent();
  }

  renderer.render(scene, camera);
  requestAnimationFrame(animate);
}
requestAnimationFrame(animate);

Handling Background Tab Throttling

When a tab is backgrounded, browsers throttle or pause requestAnimationFrame. During the pause clock.getDelta() returns zero, so animation time stops advancing — this keeps visual state consistent with the frames that actually ran. Meanwhile Date.now() continues ticking, so elapsedReal will jump ahead.

If the gap matters (e.g., a deadline must fire exactly at the wall‑clock moment), detect a long pause and decide whether to catch up the animation or simply let the deadline trigger on resume:

let lastPerf = performance.now();
const PAUSE_THRESHOLD_MS = 10_000; // 10 s

function animate() {
  const currentPerf = performance.now();
  const pauseMs = currentPerf - lastPerf;
  lastPerf = currentPerf;

  if (pauseMs > PAUSE_THRESHOLD_MS) {
    // Tab was suspended – choose a policy:
    // 1) Let animation stay paused (default Clock behavior)
    // 2) Fast‑forward animation by pauseMs / 1000 seconds
    // clock.start(); // resets internal startTime to now
  }

  const delta = clock.getDelta();
  const nowUtc = Date.now();
  const elapsedReal = nowUtc - startUtc;
  // … rest of loop
}

Verification Steps

1. Record startPerf and startUtc at load. In each frame log clock.getElapsedTime() and (Date.now() - startUtc) / 1000. After an hour the difference should be < 5 ms.
2. Open the page, move the tab to background for 5 minutes, then return. Confirm that clock.getDelta() was near zero during the pause and that elapsedReal advanced by ~5 minutes.
3. Run the same test in Chrome, Firefox, Safari, and Edge to ensure consistent throttling behavior.

Assumptions & Uncertainty

• Floating‑point drift of performance.now() over days is well below 1 ms; sub‑millisecond precision needs (rare for visual work) may require periodic re‑sync.
• Browser throttling policies can change; the 10 s pause threshold is a pragmatic default, not a spec guarantee.
• If external deadlines come from an API, ensure they are converted to UTC milliseconds before comparison.

One Diagnostic Detail That Could Change the Recommendation

Does your scheduled event need to fire *exactly* at the wall‑clock moment even if the tab was suspended, or is it acceptable for the event to fire on the next frame after resume? The answer determines whether you must fast‑forward animation state on resume.