SuperAPI AI Directory
Partner中文AI newsFavorites
SkillsGeek-skills-threejs-performance

Geek-skills-threejs-performance

General & other

View repository

Updated 10-16 06:52

About this skill

Three.js Performance Optimization Guide (2026)

Core Principles

Golden Rule: Draw Calls < 100 per frame

  • Triangle count matters less than draw call count
  • Use renderer.info.render.calls monitoring
  • Over 500 draw calls, even a powerful GPU will struggle

Quick Diagnostic Checklist

// 性能监控必备
setInterval(() => {
  console.log('调用:', renderer.info.render.calls);
  console.log('三角形:', renderer.info.render.triangles);
  console.log('几何体:', renderer.info.memory.geometries);
  console.log('纹理:', renderer.info.memory.textures);
}, 1000);

If the value keeps growing, there is a memory leak.

WebGPU Renderer

When to Migrate

Migrate to WebGPU in the following cases:

  • Frame drops in draw-call-intensive scenes
  • Need compute shaders for physics/particle simulation
  • Complex post-processing chains causing stuttering

Basic Setup

import { WebGPURenderer } from 'three/webgpu';

const renderer = new WebGPURenderer();
await renderer.init(); // 必需！

function animate() {
  renderer.render(scene, camera);
  requestAnimationFrame(animate);
}

Browser support: Chrome/Edge v113+, Firefox v141+, Safari v26+

TSL (Three Shading Language)

Write once, automatically compiled to WGSL (WebGPU) or GLSL (WebGL):

import { color, positionLocal, sin, time, Fn, float } from 'three/tsl';

// 基础用法
material.colorNode = color(1, 0, 0).mul(sin(time).mul(0.5).add(0.5));

// 可复用函数
const fresnel = Fn(([normal, viewDir, power]) => {
  const dotNV = normal.dot(viewDir).saturate();
  return float(1).sub(dotNV).pow(power);
});

Compute Shader Particle System

CPU particles hit a bottleneck at around 50,000, GPU compute shaders can reach millions:

import { instancedArray, storage, compute } from 'three/tsl';

const positions = instancedArray(particleCount, 'vec3');
const velocities = instancedArray(particleCount, 'vec3');

const physicsCompute = compute(() => {
  const pos = positions.element(instanceIndex);
  const vel = velocities.element(instanceIndex);
  positions.element(instanceIndex).assign(pos.add(vel.mul(deltaTime)));
});

renderer.compute(physicsCompute);

Draw Call Optimization

InstancedMesh (Repeated Objects)

1,000 trees → from 1,000 draw calls down to 1:

const mesh = new InstancedMesh(geometry, material, 1000);
for (let i = 0; i < 1000; i++) {
  matrix.setPosition(positions[i]);
  mesh.setMatrixAt(i, matrix);
}

BatchedMesh (Different Geometries)

Multiple different geometries sharing a material merged into a single draw:

const batchedMesh = new BatchedMesh(maxGeometries, maxVertices, maxIndices, material);

Shared Materials

// ❌ 每个网格新材质
meshes.forEach(m => m.material = new MeshStandardMaterial({ color: 'red' }));

// ✅ 共享材质
const sharedMaterial = new MeshStandardMaterial({ color: 'red' });
meshes.forEach(m => m.material = sharedMaterial);

Merge Static Geometry

import { mergeGeometries } from 'three/addons/utils/BufferGeometryUtils.js';
const merged = mergeGeometries([geo1, geo2, geo3]);

Asset Optimization

Compression Commands

# Draco 几何体压缩 (减少 90-95%)
gltf-transform draco model.glb compressed.glb --method edgebreaker

# KTX2 纹理压缩 (GPU 内存减少约 10 倍)
gltf-transform uastc model.glb optimized.glb  # 高质量
gltf-transform etc1s model.glb optimized.glb  # 小体积

# 完整优化管线
gltf-transform optimize model.glb output.glb \
  --texture-compress ktx2 \
  --compress draco

Decoder Configuration

import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';

const dracoLoader = new DRACOLoader();
dracoLoader.setDecoderPath('/draco/');

const ktx2Loader = new KTX2Loader();
ktx2Loader.setTranscoderPath('/basis/');

Memory Management

Key: Three.js does not automatically garbage collect GPU resources!

Complete Disposal Pattern

function cleanupMesh(mesh) {
  mesh.geometry.dispose();
  
  if (Array.isArray(mesh.material)) {
    mesh.material.forEach(mat => {
      Object.values(mat).forEach(prop => {
        if (prop?.isTexture) prop.dispose();
      });
      mat.dispose();
    });
  } else {
    Object.values(mesh.material).forEach(prop => {
      if (prop?.isTexture) prop.dispose();
    });
    mesh.material.dispose();
  }
  
  scene.remove(mesh);
}

// GLTF ImageBitmap 特殊处理
texture.source.data.close?.();
texture.dispose();

Object Pooling Pattern

class ObjectPool {
  constructor(factory, reset, initialSize = 20) {
    this.factory = factory;
    this.reset = reset;
    this.pool = Array.from({ length: initialSize }, () => {
      const obj = factory();
      obj.visible = false;
      return obj;
    });
  }
  
  acquire() {
    const obj = this.pool.pop() || this.factory();
    obj.visible = true;
    return obj;
  }
  
  release(obj) {
    this.reset(obj);
    obj.visible = false;
    this.pool.push(obj);
  }
}

Shader Optimization

Mobile First

precision mediump float;  // 比 highp 快约 2 倍

Branchless Alternatives

// ❌ 分支破坏 GPU 并行性
if (value > 0.5) color = colorA; else color = colorB;

// ✅ 无分支
color = mix(colorB, colorA, step(0.5, value));

Data Packing

vec4 data = texture2D(dataTex, uv);
// 4 个值只需 1 次纹理获取
float v1 = data.r, v2 = data.g, v3 = data.b, v4 = data.a;

Lighting and Shadows

  • Active lights ≤ 3
  • PointLight shadows = 6 shadow map renders per light
  • Shadow map size: mobile 512-1024, desktop 1024-2048
  • Bake lightmaps for static scenes
// 静态场景禁用阴影自动更新
renderer.shadowMap.autoUpdate = false;
renderer.shadowMap.needsUpdate = true; // 需要时手动触发

React Three Fiber

Core Rules

// ❌ 触发 React 重新渲染
const [rotation, setRotation] = useState(0);
useFrame(() => setRotation(r => r + 0.01));

// ✅ 直接修改
const meshRef = useRef();
useFrame((state, delta) => {
  meshRef.current.rotation.x += delta * speed; // 帧率无关
});

Render on Demand

<Canvas frameloop="demand">
  <Scene />
</Canvas>

// 需要时触发
const invalidate = useThree(state => state.invalidate);
invalidate();

Toggle Visibility Instead of Remounting

// ❌ 卸载/挂载重建资源
{showModel && <Model />}

// ✅ 可见性切换
<Model visible={showModel} />

Post-Processing

Use pmndrs/postprocessing for WebGL

import { EffectComposer, Bloom, Vignette } from 'postprocessing';

const composer = new EffectComposer(renderer);
composer.addPass(new RenderPass(scene, camera));
composer.addPass(new EffectPass(camera, new Bloom(), new Vignette()));

Use native TSL post-processing for WebGPU

import { pass, bloom, fxaa } from 'three/tsl';

const postProcessing = new PostProcessing(renderer);
const scenePass = pass(scene, camera);
postProcessing.outputNode = scenePass.pipe(bloom()).pipe(fxaa());

Debugging Tools

  • stats-gl: FPS/CPU/GPU monitoring
  • lil-gui: Real-time parameter adjustment
  • Spector.js: WebGL frame capture
  • three-mesh-bvh: Fast raycasting (80,000+ polygons @ 60fps)
  • r3f-perf: React Three Fiber performance monitoring

Detailed Reference