gaussian-splats-3d: 'Cannot start viewer unless it is in self driven mode.' after viewer.start() with selfDrivenMode: false
Symptom: a three.js page using @mkkellogg/gaussian-splats-3d 0.4.7 builds a viewer with new Viewer({ cameraUp: [0, 1, 0], initialCameraPosition: [0, 2, 5], initialCameraLookAt: [0, 0, 0], selfDrivenMode: false, rootElement: container, sharedMemoryForWorkers: false }), then await viewer.addSplatScene(url, {...}) and viewer.start(). The PLY downloads and parses, but the call throws Error: Cannot start viewer unless it is in self driven mode. and nothing renders. Copying an options block from the README's 'custom renderer/camera' example is an easy way to end up with selfDrivenMode: false.
Cause: selfDrivenMode decides who owns the render loop. With true (the default when you omit it), viewer.start() schedules its own requestAnimationFrame loop (or renderer.setAnimationLoop in WebXR mode). With false the library expects you to drive it, and start() is defined to throw exactly that error: in the 0.4.7 build start() is if (this.selfDrivenMode) { ... } else { throw new Error('Cannot start viewer unless it is in self driven mode.'); }.
Fix, pick one model and stick to it:
// A) let the viewer run itself
const viewer = new Viewer({ selfDrivenMode: true, rootElement: container, cameraUp: [0, 1, 0] });
await viewer.addSplatScene('/api/splat/1ErEvp9NR7U.ply', { progressiveLoad: true });
viewer.start();
// B) own the loop (e.g. you already have a three.js renderer/camera)
const viewer = new Viewer({ selfDrivenMode: false, renderer, camera, useBuiltInControls: false });
await viewer.addSplatScene(url);
renderer.setAnimationLoop(() => { viewer.update(); viewer.render(); });Don't call start() in mode B. Also note that in DropInViewer mode the library forces self-driven off internally, so start() isn't the API there either.
Verify: after switching to selfDrivenMode: true, the same page logged the scene as loaded and rendered the 5M-Gaussian aerial splat (HackPrinceton 2026 model 1ErEvp9NR7U, served through a same-origin proxy). If you swap models by disposing and recreating the viewer, call viewer.dispose() first so the old rAF loop stops.