webgl-and-threejs-3d-experiences

WebGL & Three.js 3D Experiences Architecture Guide

Core Architectural Principles

1. Scene Graph Architecture & Render Lifecycle

• Unified Engine Class Pattern: Enforce OOP or functional composition encapsulating WebGLRenderer, Scene, PerspectiveCamera, and RAF loop into a self-contained renderer manager.
• Render Loop Delta Capping: Always cap clock.getDelta() (e.g., Math.min(delta, 0.1)) to avoid physics explosion/teleportation during window unfocus or frame drops.
• Pixel Ratio Guardrails: Cap renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)) to prevent mobile GPUs from rendering native 4K/8K viewports at unusable framerates.

2. GPU Memory Management & Resource Lifecycle

• Explicit Garbage Collection: JavaScript GC does not manage VRAM allocated to WebGL buffers, textures, geometries, or render targets.
• Disposal Traversal: Recursively traverse scenes and call .dispose() on geometries, materials, textures, and render targets upon component unmount or scene switching.
• Resource Pooling & Material Sharing: Instantiation of geometries and materials must happen outside animation loops. Share materials across meshes wherever possible.

3. High-Performance WebGL Techniques

• InstancedMesh: Use InstancedMesh for rendering thousands of repetitive objects (particles, trees, debris) using single draw calls.
• BVH (Bounding Volume Hierarchy): Integrate three-mesh-bvh for sub-millisecond raycasting against high-poly meshes instead of brute-force triangle intersection checks.
• Compressed Assets: Standardize on KTX2/Basis for textures and DRACO/Meshopt compression for GLTF/GLB models.

---

Production Code Examples

Example 1: Full Production Three.js Engine Lifecycle with Automatic GPU Disposal

Location: src/3d/Engine.ts

import * as THREE from 'three'
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js'

export class Engine {
  private container: HTMLElement
  private scene: THREE.Scene
  private camera: THREE.PerspectiveCamera
  private renderer: THREE.WebGLRenderer
  private controls: OrbitControls
  private clock: THREE.Clock
  private animationFrameId: number | null = null
  private isDisposed = false

  constructor(container: HTMLElement) {
    this.container = container

    // 1. Scene Initialization
    this.scene = new THREE.Scene()
    this.scene.background = new THREE.Color('#0a0a0c')

    // 2. Camera Setup
    const aspect = container.clientWidth / container.clientHeight
    this.camera = new THREE.PerspectiveCamera(60, aspect, 0.1, 1000)
    this.camera.position.set(0, 5, 10)

    // 3. WebGL Renderer Setup with Pixel Ratio Capping
    this.renderer = new THREE.WebGLRenderer({
      antialias: true,
      alpha: false,
      powerPreference: 'high-performance'
    })
    this.renderer.setSize(container.clientWidth, container.clientHeight)
    this.renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2))
    this.renderer.shadowMap.enabled = true
    this.renderer.shadowMap.type = THREE.PCFSoftShadowMap
    this.renderer.outputColorSpace = THREE.SRGBColorSpace

    container.appendChild(this.renderer.domElement)

    // 4. Controls & Time Tracking
    this.controls = new OrbitControls(this.camera, this.renderer.domElement)
    this.controls.enableDamping = true
    this.controls.dampingFactor = 0.05

    this.clock = new THREE.Clock()

    // 5. Setup Listeners & Start Loop
    window.addEventListener('resize', this.onResize)
    this.start()
  }

  private onResize = () => {
    if (this.isDisposed) return
    const width = this.container.clientWidth
    const height = this.container.clientHeight

    this.camera.aspect = width / height
    this.camera.updateProjectionMatrix()

    this.renderer.setSize(width, height)
    this.renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2))
  }

  private start() {
    const tick = () => {
      if (this.isDisposed) return

      // Delta capping to prevent un-focused window physics explosions
      const delta = Math.min(this.clock.getDelta(), 0.1)

      this.controls.update()
      this.renderer.render(this.scene, this.camera)

      this.animationFrameId = requestAnimationFrame(tick)
    }

    tick()
  }

  public getScene(): THREE.Scene {
    return this.scene
  }

  // Comprehensive GPU Memory Cleanup Pipeline
  public dispose() {
    this.isDisposed = true

    if (this.animationFrameId !== null) {
      cancelAnimationFrame(this.animationFrameId)
    }

    window.removeEventListener('resize', this.onResize)
    this.controls.dispose()

    // Recursive traversal and disposal of all geometries, materials, and textures
    this.scene.traverse((object: THREE.Object3D) => {
      if (!(object instanceof THREE.Mesh)) return

      // Dispose geometry
      object.geometry.dispose()

      // Dispose material(s)
      if (Array.isArray(object.material)) {
        object.material.forEach((mat) => this.disposeMaterial(mat))
      } else if (object.material) {
        this.disposeMaterial(object.material)
      }
    })

    this.renderer.dispose()
    if (this.renderer.domElement && this.renderer.domElement.parentElement) {
      this.renderer.domElement.parentElement.removeChild(this.renderer.domElement)
    }
  }

  private disposeMaterial(material: THREE.Material) {
    material.dispose()

    // Dispose all potential texture maps on the material
    for (const key of Object.keys(material)) {
      const value = (material as any)[key]
      if (value && value instanceof THREE.Texture) {
        value.dispose()
      }
    }
  }
}