threejs-perf-loading

Three.js Performance & Loading Patterns

Patterns drawn from studying modern Three.js/WebGPU production sites built by top-notch studios and developers, each solving a different piece of "make a heavy real-time scene feel instant and never stutter." This file distills the transferable patterns, organized by what problem they solve.

Don't treat any of this as an au-courant checklist to apply wholesale — each technique below traded something (code complexity, a stubbed physical behavior, a hard cutoff) for its win. Read the "cost" note on each one before copying it.

1. Loading & warmup — hide compile/decode cost behind the spinner

The classic symptom this section solves: loading bar hits 100%, then a 1-2 second freeze before the scene appears. That freeze is (almost always) the GPU driver compiling shader pipelines on first use — WebGL/WebGPU compile lazily, per unique material/uniform combination, the first time it's drawn. If your loading screen only waits for asset fetch, you've hidden network latency but not compile latency.

Fix: force every pipeline to compile while the loading UI is still up, by actually rendering through it once. (Source: ivress-brand-site-teardown.md)

// Simplified from the ivress renderer's warmup phase.
class WarmupRenderer {
  async runWarmupFrame(camera) {
    // 1. Activate the section/state whose materials you're about to warm.
    this._activateSection(this.warmupSectionIndex);

    // 2. Disable frustum culling for this pass — you need EVERY mesh to
    //    actually draw, including ones off-screen from this camera, or its
    //    pipeline never compiles.
    const culled = [];
    scene.traverse((o) => {
      if (o.isMesh && o.frustumCulled) { o.frustumCulled = false; culled.push(o); }
    });

    // 3. Render a handful of real frames through the FULL post-processing
    //    chain (bloom, grade, everything) — not a stripped-down warm pass.
    //    Uncompiled post nodes will still stall on first real use otherwise.
    this.scenePass.camera = camera;
    await this.postProcessing.render();

    culled.forEach((o) => { o.frustumCulled = true; });

    // 4. Advance to the next section/state and repeat until every
    //    section's material set has drawn at least once.
  }

  completeWarmup() {
    this._restoreOriginalState();
    // Wait 2 RAFs + a microtask — let the compositor fully settle —
    // THEN fire the event your loading UI listens for to fade out.
    requestAnimationFrame(() => requestAnimationFrame(() => queueMicrotask(() => {
      emit('compileEnd');   // safe to also start loading non-critical assets now
      emit('reveal', { isIn: true });
    })));
  }
}