---

name: threejs description: Create 3D graphics, visualizations, and interactive experiences using Three.js. Use this skill when the user asks to build 3D scenes, WebGL/WebGPU applications, 3D data visualizations, interactive 3D components, games, or any browser-based 3D content. Covers scene setup, geometries, materials, lighting, cameras, animations, controls, shaders (TSL), and performance optimization.

Three.js Development

Create 3D browser experiences with Three.js. This skill covers scene construction, rendering pipelines, and interactive 3D applications.

Library Versions (2026)

• Three.js: r171+
• Uses WebGPU by default with WebGL2 fallback
• TSL (Three.js Shading Language) for custom shaders

Decision Frameworks

When to Use Which Renderer

CopyNeed WebGPU features (compute shaders, TSL, better performance)?
  → WebGPURenderer (recommended for 2026)

Need maximum browser compatibility (Safari < 18, older devices)?
  → WebGLRenderer

Unsure?
  → WebGPURenderer (automatically falls back to WebGL2)

When to Use Which Material

CopyIs it unlit (UI, wireframe, stylized, full bright)?
  → MeshBasicNodeMaterial

Is it realistic/PBR (default for most 3D)?
  ├─ Standard roughness/metalness → MeshStandardNodeMaterial
  ├─ Need glass/transmission/refraction? → MeshPhysicalNodeMaterial
  ├─ Need clearcoat (car paint, lacquer)? → MeshPhysicalNodeMaterial
  └─ Need subsurface scattering? → MeshPhysicalNodeMaterial

Is it custom/procedural?
  → TSL + NodeMaterial (see references/tsl-shaders.md)

Performance critical (thousands of objects)?
  → MeshLambertNodeMaterial (diffuse only, fast)

When to Use Which Camera

Copy3D scene with depth/perspective?
  → PerspectiveCamera (most common)

2D game, UI overlay, isometric view?
  → OrthographicCamera

VR/AR application?
  → WebXR handles cameras automatically

When to Use Which Controls

CopyInspect/view 3D model from all angles?
  → OrbitControls

First-person exploration/game?
  → PointerLockControls

Flight simulator, free camera?
  → FlyControls

Touch-friendly product viewer?
  → OrbitControls with touch enabled

Scroll-driven animation?
  → Custom (or use R3F ScrollControls)

Core Setup (2026 - WebGPU)

Copyimport * as THREE from 'three/webgpu'

// Scene
const scene = new THREE.Scene()

// Camera
const camera = new THREE.PerspectiveCamera(
  75,
  window.innerWidth / window.innerHeight,
  0.1,
  1000
)
camera.position.z = 5

// Renderer (WebGPU with automatic WebGL2 fallback)
const renderer = new THREE.WebGPURenderer({ antialias: true })
await renderer.init() // Required for WebGPU
renderer.setSize(window.innerWidth, window.innerHeight)
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2))
renderer.toneMapping = THREE.ACESFilmicToneMapping
renderer.outputColorSpace = THREE.SRGBColorSpace
document.body.appendChild(renderer.domElement)

// Animation loop (use setAnimationLoop for WebGPU/WebXR)
function animate() {
  renderer.render(scene, camera)
}
renderer.setAnimationLoop(animate)

// Resize handling
window.addEventListener('resize', () => {
  camera.aspect = window.innerWidth / window.innerHeight
  camera.updateProjectionMatrix()
  renderer.setSize(window.innerWidth, window.innerHeight)
})

Essential Components

Geometries

• Primitives: BoxGeometry, SphereGeometry, PlaneGeometry, CylinderGeometry, TorusGeometry, ConeGeometry
• Complex: TorusKnotGeometry, IcosahedronGeometry, OctahedronGeometry
• Custom: BufferGeometry with Float32Array attributes for vertices, normals, UVs
• Text: TextGeometry (requires FontLoader)

Materials (NodeMaterial for WebGPU compatibility)

Copy// Standard PBR material
const material = new THREE.MeshStandardNodeMaterial({
  color: 0x00ff00,
  roughness: 0.5,
  metalness: 0.5
})

// Physical material with transmission (glass)
const glass = new THREE.MeshPhysicalNodeMaterial({
  transmission: 1,
  roughness: 0,
  ior: 1.5,
  thickness: 0.5
})

Lights

• AmbientLight - uniform fill light, no shadows
• DirectionalLight - sun-like parallel rays, supports shadows
• PointLight - omnidirectional from a point
• SpotLight - cone-shaped with falloff
• HemisphereLight - sky/ground gradient
• RectAreaLight - rectangular area light

Copy// Typical lighting setup
scene.add(new THREE.AmbientLight(0xffffff, 0.4))

const sun = new THREE.DirectionalLight(0xffffff, 1)
sun.position.set(5, 10, 5)
sun.castShadow = true
sun.shadow.mapSize.setScalar(2048)
scene.add(sun)

Shadows

Copyrenderer.shadowMap.enabled = true
renderer.shadowMap.type = THREE.PCFSoftShadowMap

light.castShadow = true
light.shadow.mapSize.width = 2048
light.shadow.mapSize.height = 2048
light.shadow.camera.near = 0.5
light.shadow.camera.far = 50

mesh.castShadow = true
groundMesh.receiveShadow = true

Common Imports

Copy// Controls
import { OrbitControls } from 'three/addons/controls/OrbitControls.js'
import { PointerLockControls } from 'three/addons/controls/PointerLockControls.js'

// Loaders
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js'
import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js'
import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js'
import { RGBELoader } from 'three/addons/loaders/RGBELoader.js'

// Compression decoders
import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js'

// TSL for custom shaders
import { color, uniform, uv, sin, time, mix } from 'three/tsl'

Animation Patterns

Clock-based Animation

Copyconst clock = new THREE.Clock()

function animate() {
  const delta = clock.getDelta()
  const elapsed = clock.getElapsedTime()

  mesh.rotation.y += delta * 0.5
  mesh.position.y = Math.sin(elapsed) * 0.5

  renderer.render(scene, camera)
}
renderer.setAnimationLoop(animate)

GLTF Animation

Copylet mixer
const loader = new GLTFLoader()

loader.load('/character.glb', (gltf) => {
  scene.add(gltf.scene)
  mixer = new THREE.AnimationMixer(gltf.scene)

  // Play all animations
  gltf.animations.forEach((clip) => {
    mixer.clipAction(clip).play()
  })
})

// In animate loop
function animate() {
  const delta = clock.getDelta()
  if (mixer) mixer.update(delta)
  renderer.render(scene, camera)
}

Interaction & Raycasting

Copyconst raycaster = new THREE.Raycaster()
const pointer = new THREE.Vector2()

window.addEventListener('pointermove', (event) => {
  pointer.x = (event.clientX / window.innerWidth) * 2 - 1
  pointer.y = -(event.clientY / window.innerHeight) * 2 + 1
})

function checkIntersections() {
  raycaster.setFromCamera(pointer, camera)
  const intersects = raycaster.intersectObjects(scene.children, true)

  if (intersects.length > 0) {
    const hit = intersects[0]
    console.log('Hit:', hit.object.name, 'at', hit.point)
  }
}

Performance Guidelines

Copy// Instanced rendering (1 draw call for 1000 objects)
const count = 1000
const mesh = new THREE.InstancedMesh(geometry, material, count)

const dummy = new THREE.Object3D()
for (let i = 0; i < count; i++) {
  dummy.position.randomDirection().multiplyScalar(Math.random() * 50)
  dummy.updateMatrix()
  mesh.setMatrixAt(i, dummy.matrix)
}
scene.add(mesh)

CDN Usage (Browser)

For HTML artifacts or quick prototypes:

Copy<script type="importmap">
{
  "imports": {
    "three": "https://cdn.jsdelivr.net/npm/three@0.171.0/build/three.webgpu.min.js",
    "three/webgpu": "https://cdn.jsdelivr.net/npm/three@0.171.0/build/three.webgpu.min.js",
    "three/tsl": "https://cdn.jsdelivr.net/npm/three@0.171.0/build/three.tsl.min.js",
    "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.171.0/examples/jsm/"
  }
}
</script>
<script type="module">
import * as THREE from 'three'
import { OrbitControls } from 'three/addons/controls/OrbitControls.js'
</script>

Related Skills

Reference Files

• references/webgpu.md - WebGPU setup, feature detection, fallbacks
• references/tsl-shaders.md - TSL custom shaders (replaces GLSL)
• references/materials.md - NodeMaterial patterns and customization
• references/physics.md - Rapier physics integration
• references/advanced.md - Post-processing, VR/AR, optimization