Cookbook — Three.js · cb-threejs

Owner directive (2026-07-10), canonical. "The folder with the .md files, the components pure, the pristine usage of the languages and technologies is not a request, is an order, just execute what is being said in official doc." [src: wiki/development/prompts-archive/by-topic/knowledge-management-and-concept-modeling.md:610]

Official docs

Our proven patterns

1. One renderer, one scene, one camera, one loop. createRenderer(wrapper) builds the quartet once and fans the frame out to subscribers before a single renderer.render(scene, camera). No second canvas, ever. [src: HOS-Instance/packages/engine/src/engine/renderer.ts:36]
2. antialias: false + DPR governor instead. MSAA is off; perceived sharpness is bought with a higher device-pixel-ratio step and paid back adaptively when fps drops (see cb-patterns-royal-orbit). [src: HOS-Instance/packages/engine/src/engine/renderer.ts:37]
3. setAnimationLoop, never a hand-rolled rAF. Start/stop via renderer.setAnimationLoop(loop|null); dt is clamped to MAX_DT = 0.1 so a background-tab return cannot explode simulations. [src: HOS-Instance/packages/engine/src/engine/renderer.ts:30]
4. Viewport fallback chain (rAF-starvation / 0×0 boot guard). Poll size every frame through innerWidth → documentElement.clientWidth → wrapper.clientWidth → constant, resizing only on change — preview/headless environments report 0×0 at boot. [src: HOS-Instance/packages/engine/src/engine/renderer.ts:49]
5. Scratch Color objects, zero per-frame allocation. Module-level THREE.Color scratches are reused for theme lerps; fresh allocation only on the explicit sampling API. [src: HOS-Instance/packages/engine/src/engine/theme.ts:25]
6. Tight frustum. near 0.1 / far 600 / fov 55 — the far plane hugs the chapter-slab depth so fog-dissolved splats cull early. [src: HOS-Instance/packages/engine/src/engine/renderer.ts:27]
7. scene.background as the fog. The clear color IS the atmosphere: lerp it along the theme arc and keep the DOM --bg identical (the dissolve trick, detailed in cb-patterns-royal-orbit). [src: HOS-Instance/packages/engine/src/engine/theme.ts:60]

Gotchas

• After setPixelRatio, force a re-apply of setSize (reset cached w/h) or the backbuffer keeps the old ratio. [src: HOS-Instance/packages/engine/src/engine/renderer.ts:96]
• sRGB-space color lerp is acceptable for this warm arc; do not add color-management conversions per frame. [src: HOS-Instance/packages/engine/src/engine/theme.ts:44]

Budgets

Frame-time and DPR thresholds are owned by bm-001-web-perf; splat ceilings by bm-002-splat-budget.

Composition

• uses: spark-renderer (renders through the same WebGL context)
• used-by: cb-spark · cb-patterns-royal-orbit · pb-001-spatial-site-loop (steps 1, 6)

See also

• gaussian-splatting · spatial-site