Optimize 3D Scene

Optimise a 3D scene

Every page that carries a three.js scene pays the same tax: a phone renders the same fragments as a workstation, the first frame after a shader appears compiles mid-scroll, and the render loop keeps running behind three sections of copy nobody is looking at. This skill fixes those in a fixed order — cheapest and highest-impact first. It was rewritten from optimisation passes on ~50 production sites; each rule says whether it is a rule (held on ≥ 3 sites) or observed (1–2 — try it, measure it, don't assume it).

Every step applies to a raw WebGL scene as much as a three.js one; only §0's measurement primitives differ (three.js hands you renderer.info, a raw scene you instrument yourself — which you must do before you can begin).

Before you fix anything, read obsidian/knowledge/fix-catalog.md and obsidian/knowledge/pitfalls.md — the answer, and the trap next to it, may already be written down. iOS / real-phone behaviour (toolbar resizes, context loss, 120 Hz speed, gyroscope) is owned by mobile-device-qa; this skill links to it where they meet.

Modules this starter already ships — use them, don't write a sixth copy:

Architecture notes for these: obsidian/frontend/webgl-scenes.md, obsidian/frontend/robot-form.md.

0. Audit before you touch anything

Never optimise blind. Establish the baseline:

# what's actually in the scene
grep -rn "setPixelRatio\|requestAnimationFrame\|new THREE\..*Light\|UnrealBloom\|Points\|InstancedMesh\|transferControlToOffscreen\|1000 / 30\|frameloop" src/ --include=*.ts --include=*.tsx --include=*.js

Then in the running page's console:

renderer.info.render      // { calls, triangles, points } — per frame
renderer.info.programs.length   // shader programs; each one is a compile stall if it appears late
renderer.info.memory      // { geometries, textures }

Raw WebGL (no three.js). renderer.info only exists on THREE.WebGLRenderer. A hand-written scene has no equivalent — hook the context before app code runs and count it yourself, or you cannot start:

// page.evaluateOnNewDocument — counts passes, vertices, and *when* programs link
const gc = HTMLCanvasElement.prototype.getContext;
HTMLCanvasElement.prototype.getContext = function (kind, attrs) {
  const ctx = gc.call(this, kind, attrs);
  if (ctx && kind === "webgl") {
    window.__gl = ctx;
    window.__p = { draws: 0, verts: 0, frames: 0, links: [], attrs };
    const draw = ctx.drawArrays.bind(ctx);
    ctx.drawArrays = (m, f, c) => { window.__p.draws++; window.__p.verts += c; return draw(m, f, c); };
    const clear = ctx.clear.bind(ctx);          // one clear = one frame
    ctx.clear = (m) => { window.__p.frames++; return clear(m); };
    const link = ctx.linkProgram.bind(ctx);     // §3/§14: these must all precede the loader handoff
    ctx.linkProgram = (p) => { window.__p.links.push(Math.round(performance.now())); return link(p); };
  }
  return ctx;
};

draws/verts replace info.render, links.length replaces programs.length (and links timestamps are what §3 is actually measured against), gl.drawingBufferWidth/Height is the §6 check, and the captured attrs is the §7 renderer-flags check. Full harness in references/patterns.md.

The standing instruments (tools/qa/, see its README; yarn qa:setup once — they install into a cache outside the project). All take --url of a running yarn build && yarn start:

The measurement environment (get this wrong and every number below is a lie)

• Measure a production build, never the dev server. Dev invalidates §1 (the bundler serves chunks eagerly) and §4/§5 (React Strict Mode double-mounts, doubling listener counts and loops). yarn build && yarn start — and kill the old server by port before rebuilding (next start runs as next-server; pkill -f "next start" misses it), or it serves a stale manifest and you debug 404s that aren't yours. Gate the server start on the build's exit code — a failed build happily serves the previous .next and your A/B compares the old build with itself.
• Probes need a person's UA. The starter's proxy serves crawlers (and puppeteer's default UA) the robot form — no scene, no motion. A probe that "proves" a fix on the robot form proved nothing. The tools/qa tools set a plain Chrome/Safari UA; your own scripts must too.
• Use waitUntil: "load" plus a fixed settle. networkidle0 never fires against next start.
• SwiftShader is not a GPU. Absolute fps out of headless Chrome is meaningless. Only counted quantities transfer: draw calls, vertices, drawing-buffer pixels, listener counts, program-link timestamps, main-thread block duration. fps-probe runs headed for that reason.
• The scroll test's desktop is a 120 Hz panel, like every ProMotion Mac. A scene that redraws every tick there does twice a 60 Hz screen's GPU work — see §5.
• A shared machine moves numbers. Interleave A/B arms (old, new, old, new) so both see the same load; build the baseline from a git worktree of the base branch, never by copying .next/ or node_modules/.

Write the before/after numbers down. A change you cannot measure is a change you cannot defend, and every item below costs something in look.

1. Never ship the scene to a robot

A crawler or Lighthouse's robot run gets no scene at all — not a hidden canvas, not a lazily-idle module. The starter does this in the proxy, not in the page: src/proxy.ts rewrites a bot UA (src/utils/bot-ua.ts, which includes the AI crawlers) to the prerendered /robot-view route, where the view renders a still in place of the scene. Read optimize-load/references/robot-path.md before touching it.

• The scene component is a client leaf loaded with import() (or dynamic(..., { ssr: false })), so three lands in its own chunk and the robot form never fetches it. Never re-export it from a barrel next to lighter siblings — importing any sibling from the barrel pulls three.js into its chunk (observed).
• Never await isBot() in a page or layout. It reads headers() and makes the route dynamic for every visitor (no CDN cache). The UA belongs in the proxy (rule — the starter shipped that defect into most of the sites it seeded).
• Importing drei for one hook pulls three.js into the first bundle (observed: a loader importing useProgress). Import drei only inside the lazily loaded scene.
• A scene started at module evaluation (to beat hydration) can't read React context: gate its start on isRobotView() (the server's <meta name="x-robot-view">) once the document is parsed, and skip its model preloads on the robot form.

The still. It exists for (a) crawler and share-card screenshots, which otherwise capture an empty box, and (b) the no-WebGL / context-lost fallback. node tools/qa/capture-still.mjs --url … --save public/assets/scene-still captures the running canvas with text and chrome hidden. Its wait must cover the scene's own entrance, not just the loader. Look at it before wiring it. If the camera fits to the tighter axis, one landscape still re-crops the subject on portrait — export desktop and phone crops and pick with <picture>.

2. Tier the device at construction — and re-read it on a real change

One module decides what "mobile" means. Everything — DPR, particle counts, bloom, whether the pointer is even listened to — reads from it, so the values can never drift apart. Read it at construction and hold it in a mutable slot: never recompute it per frame, and never rebuild buffers on every resize event.

mobile = innerWidth < 768 || matchMedia("(hover: none) and (pointer: coarse)"). The coarse-pointer clause is what catches tablets and large phones.

"Once" does not mean "never again". The tier changes mid-session in real cases: a window dragged across a breakpoint, DevTools device mode switched on or off (which flips DPR, pointer and hover at once — the way most reviewers check a phone layout), a tablet rotated. A scene that read the tier into a const kept the 390-wide buffer, the parked pointer and the hidden desktop passes on a 2160-wide viewport and drew skewed until reload. So:

• Re-read the tier when the width changes or the pointer media query flips. Height-only changes on a coarse pointer are the iOS URL bar and are ignored (§13).
• When it changes, retune(tier): re-apply DPR (renderer and composer, §6), per-tier visibility flags, bind or unbind the pointer listener (§11).
• Retune touches uniforms, sizes, visibility and listeners only — never a define, a light count or material.transparent (§3.2), so no program is compiled. Allocate the largest tier's particle buffer at construction and vary the count with geometry.setDrawRange.
• Never decide layout from JS width on the server. A useIsMobile that reads width 0 during SSR makes phones hydrate the desktop composition, then rebuild the mobile one (observed: ~0.25 s of the longest task). Switch layout with CSS breakpoints; where JS must decide, render both and hide one with CSS.

Also expose, from the same module:

• prefersReducedMotion() — an accessibility promise, honoured on every tier.
• isEnergySaver() — navigator.connection.saveData or deviceMemory <= 2.
• sceneShouldSettle() — reduced motion, or a constrained phone: play the entrance, then stop advancing time. Do not stop drawing a visible canvas and trust the last frame — iOS drops it after a toolbar resize or a re-composite and the scene "disappears" (§4). A settled scene still redraws on resize, visibility return and context restore.

3. Precompute and prewarm everything during the loader

This is the rule that kills micro-freezes. After the loader hands off, the frame loop must allocate nothing, compile nothing and upload nothing. A stall on scroll — or a frozen loader — is always one of five things:

1. Shader compile / link. await renderer.compileAsync(scene, camera) while the loader is still on screen. Raw WebGL: never read COMPILE_STATUS / LINK_STATUS in the task that compiled — poll KHR_parallel_shader_compile's COMPLETION_STATUS_KHR once a frame first (observed: a gradient's mount 1,084 → 16 ms at 4× CPU). three.js reads every program's status and uniforms right after linking, so the main thread waits on the GPU compile (130–840 ms per scene build on a phone): set renderer.debug.checkShaderErrors = false in production.
2. Program variants. Three compiles a new program when a define changes — USE_INSTANCING, transparent, a different light count, fog, tone mapping, the render target's colour space. Never flip a define, a light count, material.transparent or blending at runtime. Set the final variant at construction and drive change through uniforms only.
3. Texture and buffer upload. The first render that samples a texture uploads it. renderer.initTexture(tex) for every texture during the loader. Big attribute buffers: upload one per frame, not all on the first draw (observed: seven ~17.7 MB grass buffers → one 84 ms mobile frame, gone when queued one per rAF).
4. Render-target and post-pass warmup. Each EffectComposer / WebGLRenderTarget allocates and compiles on its first use.
5. CPU decode / parse. Geometry decode, sampling, PCA fits, buffer building — pure work, the one most often missed because the other four are shader-shaped. On a throttled phone it blocks for seconds and lands while the loader animates. Move it to a Worker (rule, 6 sites): new Worker(new URL("./x.worker.ts", import.meta.url), { type: "module" }) (Turbopack bundles it), transfer buffers both ways, keep an inline fallback. Measured: 140k-point surface sampling in a useMemo, 2.6 s at 4× → worker: mobile TBT 4.3 s → 0.2 s, perf 52 → 85. Hold the reveal until the worker answers. Keep the new Worker(...) launcher in its own file — in the module the worker itself imports, next build hangs (observed). Build point clouds straight into Float32Arrays, not via SphereGeometry and a copy (observed: 7× faster, start-up task 290 → 180 ms).

How to prewarm so it actually covers the first frame (rule — the same family on 4+ sites):

• Against the real targets. With post-processing the scene renders into the composer's render target, whose program variants (MSAA, colour space) differ from the canvas's — a prewarm against the screen re-links every shader on frame one (measured: first frame 1,032 → 48 ms once warmed against the composer's targets). Bind the composer's targets while compiling and run the post passes once.
• Visible while compiling. three.js skips invisible objects. Make objects visible in the same step as the compile and the warming draw, hide them again before the frame is shown (observed: a recurring 69–116 ms frame gone).
• Small tasks, one step per frame. Read one program's uniforms per task, upload one object per task. Drive the warm-up from the render loop, one step per requestAnimationFrame: textures → scene shaders → extra materials → one frame each for every pass the first real frame uses (scene, bloom chain, composite). setTimeout(0) chains do not yield a frame — they ran back-to-back and the "split" work landed in one frame anyway (measured: first real frame 43–56 → 4–5 ms with per-rAF steps).
• Gated passes compile on first use. Skipping bloom at strength 0 moves its compile to the first scene where it turns on — mid-scroll. Run the pass once during warm-up regardless (observed: a 755 ms task gone).
• Every keyframe of the timeline. Render one frame at progress 0, 0.25, 0.5, 0.75, 1 into a scratch target, so no branch or finale texture is reached for the first time mid-scroll.
• Gated canvases. A canvas that starts hidden behind a scroll flag compiles on its first draw: prewarm it with one hidden frame at mount (observed).

Verify: renderer.info.programs.length must not grow after the handoff.

§1 and §3 pull against each other — check the gap, every time. Code-splitting the scene means it cannot compile until after hydration; on a slow connection that lands after the loader hands off. Measure it (linkProgram timestamps vs the handoff) and close it: start the scene's data fetch at first paint (not a <head> preload — that bills the bytes to the LCP, see optimize-load), and gate the loader on scene-ready rather than a fixed duration.

A scene far below the fold has no loader to hide behind — its construction lands inside the visitor's scroll. Mount it on idle after load, not on proximity (observed). Don't move the build (or even the module's evaluation) to well after load — that cured one site's scroll and cost mobile Lighthouse 8–9 points, because it fell in Lighthouse's window. Build one idle task per step at the mount — renderer; each environment material pre-compiled with compileAsync under PMREM's own state (NoToneMapping, a render target set — both are in the program key, and so is the light count); fromScene(new Scene(), sigma) once to build PMREM's private programs; the real fromScene; the model's compileAsync; first render. Measured: mobile worst frame 159 → 52 ms, Lighthouse mobile 71 → 75. Find the heavy step with tools/qa/profile.mjs --scroll-to "<selector>". Never defer preloads to "after the entrance" either — their decode then lands on the first scroll.

[!warning] The as="fetch" preload credentials trap An as="fetch" preload is only reused when its credentials mode matches the fetch() exactly. crossorigin="anonymous" + credentials: "omit" does not match; both silently download the asset twice. The pair that dedupes is crossorigin="use-credentials" + credentials: "include". Count network requests (page.on("request")), not fetch calls.

4. Render only when visible — and always when visible

Gate the loop on all three:

• document.hidden — a background tab paints nothing.
• The section is on (or near) screen — IntersectionObserver with a rootMargin of about one viewport so it is already warm when it arrives.
• The canvas is actually visible (not faded to 0 by a wrapper).

Subscribe to one app-wide rAF ticker rather than a loop per scene. Several forever-rAF scenes on one page were the documented cause of scroll jank on more than one site — and a duplicate loop (StrictMode double mount, a loop started on both mount and resize) also makes every per-frame increment run twice (§5).

The other half — never stop drawing a visible canvas (observed, iOS, on a real phone): a "freeze the hero after 10 % scroll" optimisation relied on the browser keeping the last frame; iOS drops it after a toolbar resize and the stopped scene never repainted — the hero "disappeared". Pause only when the canvas is off screen.

Survive a lost context. iOS drops WebGL contexts under memory pressure (decoding big stills while the hero is off screen was enough) and nothing rebuilds them — the scene is a permanent blank. Use keepSceneAlive from src/lib/scene/webgl-context.ts: preventDefault the webglcontextlost; when the scene nears the viewport, the tab returns or pageshow fires, check gl.isContextLost() and rebuild on a fresh context at rest (no intro replay; ≥ 1 s between rebuilds, 3 retries); forceContextLoss() on every teardown so a rebuild never holds two contexts; don't allocate desktop-only render targets on phones. Prove it with tools/qa/context-loss-probe.mjs (FAIL → PASS on the site that taught it). Details: mobile-device-qa.

r3f: <Canvas frameloop="never"> re-applies the prop on every re-render — with a later setFrameloop the scene went black after the second resize (observed). Own the loop in one place.

[!warning] Clamping DPR on a THREE.Points scene changes its look gl_PointSize is in framebuffer pixels: at a lower DPR every point draws bigger on screen. Pass uPixelScale = renderDpr / originalDpr and multiply the size (and any minimum) by it (observed: 2 → 1.5 with the scale, pixel diff vs live = the scene's motion only).

5. Frame rate: never a fixed phone cap; 60 on fast desktop panels

This section replaced an older rule ("30 fps on phones") after real-phone reviews. Rule (5+ sites): no fixed phone frame cap.

• A t - last <= 1000/30 throttle on a 60 Hz loop draws every 3rd frame (20 fps); on a 120 Hz iPhone every 5th (26 fps measured). A reviewer on an iPhone: "feels low FPS, looks really bad". Lifting the cap took scenes 26 → 120 fps at rest with the phone scroll test unchanged or better (1.19 → 0.58 % dropped on one site; ideal before and after on others).
• A cap trips the scene's own fps fallback. A scene with an adaptive-DPR monitor read the capped 26 fps as a weak device and dropped every phone to DPR 0.75 within ~2 s — the "noisy hero" seen on a real phone (observed, 2 sites). Any fps-driven DPR fallback must never sit under a frame cap.
• Pay for scroll smoothness with a cheaper frame (DPR, samples, particles, passes — §6, §7), and measure it with tools/qa/fps-probe.mjs: read the scene's draws/s against the page's raf/s; a budget throttle shows as draws ≈ raf/3 at 60 Hz.
• If a cap is truly unavoidable (the client accepts it), skip alternate frames (frame % 2) — never a budget throttle — and say so in the report.

Desktop: cap the draw at 60 fps on fast panels (rule, 6 sites). On a 120 Hz panel a GPU-bound scene + post chain redraws every 8.3 ms tick; the scroll test read 2–31 % dropped with the main thread idle. An accumulator that draws at most every frame of 60 Hz took those to 0–1.9 %. Details that matter:

• Threshold 12.5 ms (between a 120 Hz and a 60 Hz tick) — it never drops a frame on a 60 Hz screen to jitter.
• Gate only the draw. Keep per-tick easing (lerps written per frame) stepping every tick, or the cursor eases at half speed on 120 Hz.
• The shape is in references/patterns.md §16 (frameBudgetMs in §1 returns 12.5 on desktop, 0 elsewhere).

Speed must not follow the refresh rate. Per-frame increments not scaled by delta time run 2× at 120 Hz and 4× with a duplicate loop (observed: a phone scene "2–4× too fast and shaking"). Every += k becomes += k * dt * 60; every lerp(a, b, k) becomes lerp(a, b, perFrame(k, dt)); dt clamped (MAX_FRAME_DT). One clock, in seconds for three.js (createFrameClock). Simulate 120 Hz headless by replacing requestAnimationFrame with an 8 ms timer and compare pixel change per 1/60 s against 60 Hz (mobile-device-qa §120 Hz).