three-js

Three.js 完整参考（原生版）

React Three Fiber 用户：本参考适用于原生 Three.js。有关 R3F/Drei 模式， 请使用 r3f-best-practices 技能。不过，了解这里的 Three.js 概念 有助于使用 R3F，因为 R3F 是 Three.js 的 React 渲染器。

快速入门

import * as THREE from 'three';

const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer({ antialias: true });

renderer.setSize(window.innerWidth, window.innerHeight);
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
document.body.appendChild(renderer.domElement);

const geometry = new THREE.BoxGeometry(1, 1, 1);
const material = new THREE.MeshStandardMaterial({ color: 0x00ff00 });
const cube = new THREE.Mesh(geometry, material);
scene.add(cube);

scene.add(new THREE.AmbientLight(0xffffff, 0.5));
const light = new THREE.DirectionalLight(0xffffff, 1);
light.position.set(5, 5, 5);
scene.add(light);

camera.position.z = 5;

function animate() {
  requestAnimationFrame(animate);
  cube.rotation.x += 0.01;
  cube.rotation.y += 0.01;
  renderer.render(scene, camera);
}
animate();

参考索引

根据任务加载相应的参考文件：

核心基础

参考	适用场景
references/01-fundamentals.md	场景设置、渲染器配置、Object3D 层级结构、坐标系
references/02-geometry.md	创建形状、BufferGeometry、实例化、点、线
references/06-cameras.md	相机类型、视锥体、视口、投影
references/13-math.md	Vector3、Matrix4、Quaternion、Euler、Color、MathUtils

视觉效果

参考	适用场景
references/03-materials.md	PBR 材质、着色器材质、所有材质类型
references/04-textures.md	纹理加载、UV 映射、渲染目标、环境贴图
references/05-lighting.md	光源类型、阴影、IBL、光照探针
references/11-shaders.md	自定义 GLSL 着色器、uniform、varying、着色器模式

动画与交互

参考	适用场景
references/08-animation.md	关键帧动画、骨骼动画、变形目标、程序化运动
references/09-interaction.md	射线投射、选择、拖动、坐标转换
references/10-controls.md	OrbitControls、FlyControls、PointerLockControls 等

资源

参考	适用场景
references/07-loaders.md	GLTF、FBX、纹理、HDR、Draco 压缩、异步模式

效果

参考	适用场景
references/12-postprocessing.md	泛光、景深、SSAO、自定义效果、EffectComposer

进阶

参考	适用场景
references/14-performance.md	优化、性能分析、LOD、剔除、批处理
references/15-node-materials.md	TSL（Three Shading Language）、基于节点的材质
references/16-physics-vr.md	物理引擎、WebXR、VR/AR 集成
references/17-webgpu.md	WebGPU 渲染器、计算着色器、WGSL
references/18-patterns.md	架构模式、资源管理、清理、状态

常见模式速查

调整大小处理器

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

清理/释放资源

function dispose(obj) {
  obj.traverse(child => {
    if (child.geometry) child.geometry.dispose();
    if (child.material) {
      if (Array.isArray(child.material)) {
        child.material.forEach(m => m.dispose());
      } else {
        child.material.dispose();
      }
    }
  });
}

使用时钟的动画循环

const clock = new THREE.Clock();

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

  // Use delta for frame-rate independent animation
  mixer?.update(delta);

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

导入模式

// Core
import * as THREE from 'three';

// Addons (controls, loaders, effects)
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { RGBELoader } from 'three/addons/loaders/RGBELoader.js';
import { EffectComposer } from 'three/addons/postprocessing/EffectComposer.js';

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

版本说明

本参考面向 Three.js r150+，并涵盖以下内容：

• WebGPU 支持（r150+）
• 节点材质 / TSL
• 现代 ES 模块导入

有关特定版本的 API，请查看 Three.js 迁移指南。