threejs

---
name: threejs
description: >-
  Assists with building interactive 3D experiences in the browser using Three.js. Use when
  creating 3D product configurators, data visualizations, games, or creative experiences
  with scenes, cameras, lighting, model loading, and performance optimization. Trigger words:
  threejs, three.js, 3d, webgl, react three fiber, r3f, glb, gltf.
license: Apache-2.0
compatibility: "No special requirements"
metadata:
  author: terminal-skills
  version: "1.0.0"
  category: design
  tags: ["threejs", "3d", "webgl", "react-three-fiber", "visualization"]
---

# Three.js

## Overview

Three.js is a JavaScript library for creating interactive 3D graphics in the browser using WebGL. It provides a scene graph, PBR materials, lighting systems, model loaders (glTF, FBX), and performance tools like instanced rendering. React Three Fiber offers a declarative React integration with automatic resource management and Suspense-based loading.

## Instructions

- When setting up a scene, create a `Scene`, `PerspectiveCamera` (or `OrthographicCamera`), and `WebGLRenderer`, adding `OrbitControls` for mouse/touch interaction and configuring anti-aliasing and tone mapping for production quality.
- When creating objects, combine geometries (box, sphere, plane, or custom `BufferGeometry`) with materials (`MeshStandardMaterial` for PBR, `MeshPhysicalMaterial` for advanced effects) and apply texture maps for diffuse, normal, roughness, and metalness.
- When loading 3D models, use `GLTFLoader` for glTF/GLB files (the preferred web format), enable Draco compression for models over 1MB, and use KTX2 textures for GPU-compressed formats.
- When building lighting, combine ambient, directional, point, and spot lights with environment maps (HDR) for image-based lighting, and enable shadow maps on lights and meshes that need them.
- When optimizing performance, use `InstancedMesh` for rendering 100+ identical objects, merge static geometries, implement LOD for distance-based detail levels, and dispose resources manually when removing objects.
- When using React, prefer React Three Fiber with `@react-three/drei` helpers (OrbitControls, Environment, useGLTF) and `@react-three/postprocessing` for effects like bloom and SSAO.

## Examples

### Example 1: Build a 3D product configurator

**User request:** "Create a 3D product viewer where users can change colors and rotate the model"

**Actions:**
1. Load the product model with `useGLTF()` in React Three Fiber with Draco compression
2. Set up `OrbitControls` for rotation and zoom, with camera animation on option change
3. Create material swapping logic that updates `MeshStandardMaterial` color and roughness
4. Add environment lighting with an HDR map and contact shadows for realism

**Output:** An interactive 3D product configurator with color options, smooth rotation, and realistic lighting.

### Example 2: Create an animated data globe

**User request:** "Visualize global data points on an interactive 3D globe"

**Actions:**
1. Create a sphere geometry with an earth texture and atmosphere shader
2. Plot data points using `InstancedMesh` with thousands of small spheres at geographic coordinates
3. Add arc connections between points using `TubeGeometry` with animated dash offsets
4. Implement auto-rotation with mouse-override orbit controls

**Output:** A 3D globe with data point markers, animated connection arcs, and interactive rotation.

## Guidelines

- Use glTF/GLB format for all 3D models since it is the most efficient and widely supported web format.
- Enable Draco compression for models over 1MB to reduce file size significantly.
- Use `InstancedMesh` when rendering more than 100 identical objects for massive performance gains.
- Set `antialias: true` and `toneMapping: ACESFilmicToneMapping` for production visual quality.
- Use React Three Fiber for React apps for declarative scene management and automatic disposal.
- Dispose resources manually when removing objects: `geometry.dispose()`, `material.dispose()`, `texture.dispose()`.
- Test on mobile devices and reduce shadow resolution, pixel ratio, and material complexity for low-end GPUs.