Three.js 开源项目解读
项目信息
项目名称：Three.js
项目描述: three.js 是世界上最流行、最易用的 JavaScript 3D 渲染库，让开发者在浏览器中零插件创建 GPU 加速的 3D 内容。
官方文档：https://threejs.org
解决的核心痛点：
- WebGL/WebGPU 原生 API 复杂度过高：原生 WebGL 需要数百行代码绘制一个三角形，three.js 将其封装为声明式场景图
- 跨浏览器 3D 兼容性：统一 WebGL 1.0/2.0、WebGPU 的 API 差异，提供一致的渲染结果
- 缺少一站式 3D 解决方案：整合场景图、材质、光照、动画、加载器、后处理等完整 3D 管线
目标用户：Web 前端开发者、创意技术专家、游戏开发者、XR/VR 开发者、教育与科研人员
核心技术亮点：
- 双后端架构：同时支持 WebGL 2 和 WebGPU，通过统一 Backend 接口实现后端透明切换
- TSL 着色语言：自研节点化着色语言，编译到 GLSL/WGSL，实现着色器跨后端复用
- PBR 物理渲染：内置完整的 PBR 材质系统 (roughness/metalness 工作流)，支持 IBL 环境光照
- 丰富的扩展生态：50+ 加载器、30+ 后处理效果、10+ 交互控制器，全部可 Tree Shaking
1. 项目概览
1.1 项目定位与核心价值
一句话定位：three.js 是世界上最流行、最易用的 JavaScript 3D 渲染库，让开发者在浏览器中零插件创建 GPU 加速的 3D 内容。
解决的核心痛点：
- WebGL/WebGPU 原生 API 复杂度过高：原生 WebGL 需要数百行代码绘制一个三角形，three.js 将其封装为声明式场景图
- 跨浏览器 3D 兼容性：统一 WebGL 1.0/2.0、WebGPU 的 API 差异，提供一致的渲染结果
- 缺少一站式 3D 解决方案：整合场景图、材质、光照、动画、加载器、后处理等完整 3D 管线
目标用户：Web 前端开发者、创意技术专家、游戏开发者、XR/VR 开发者、教育与科研人员
1.2 核心技术亮点
- 双后端架构：同时支持 WebGL 2 和 WebGPU，通过统一 Backend 接口实现后端透明切换
- TSL 着色语言：自研节点化着色语言，编译到 GLSL/WGSL，实现着色器跨后端复用
- PBR 物理渲染：内置完整的 PBR 材质系统 (roughness/metalness 工作流)，支持 IBL 环境光照
- 丰富的扩展生态：50+ 加载器、30+ 后处理效果、10+ 交互控制器，全部可 Tree Shaking
1.3 技术栈与选型对比
| 维度 | 选型 | 替代方案 | 权衡 |
|---|---|---|---|
| 构建工具 | Rollup | Webpack/Vite | Tree Shaking 效果最优，适合库构建 |
| 着色语言 | TSL (自研) + GLSL + WGSL | 纯 GLSL/WGSL | 跨后端复用，一次编写多处运行 |
| 模块格式 | ES Module 为主 | CommonJS | 静态分析 + Tree Shaking |
| 几何体 | BufferGeometry (TypedArray) | 旧版 Geometry (对象) | GPU 友好，性能优先 |
| 默认材质 | PBR (MeshStandardMaterial) | Phong/Lambert | 工业标准，参数直观 |
2. 整体架构设计
2.1 架构概述
three.js 采用分层插件化架构，从上到下分为五层：
- 应用层 (Addons)：丰富的扩展生态，包括高级加载器、控制器、后处理效果等，用户按需引入
- 场景图层 (Scene Graph)：声明式 3D 对象模型，通过树形结构组织 3D 世界，节点支持变换层级继承
- 渲染抽象层 (Renderer Abstraction)：统一渲染接口，隔离后端差异。Renderer 管理渲染流程，Backend 封装底层 API
- 后端实现层 (Backend Implementation)：WebGL 2 和 WebGPU 两套具体实现，包含着色器管理、状态管理、纹理管理等
- 节点着色层 (TSL/Node System)：自研着色语言，通过节点图编译到 GLSL/WGSL，实现跨后端着色器复用
2.2 整体架构图
text
+===============================================================================+
| three.js 分层架构图 |
+===============================================================================+
| |
| +-----------------------------------------------------------------------+ |
| | 应用层 (Addons Layer) | |
| | [GLTFLoader] [OrbitControls] [PostProcessing] [CSS2DRenderer] ... | |
| | 扩展生态, 按需引入, 不打包进核心库 | |
| +-----------------------------------+-----------------------------------+ |
| | (依赖核心API) |
| v |
| +-----------------------------------------------------------------------+ |
| | 场景图层 (Scene Graph Layer) | |
| | +-------------+ +-----------+ +----------+ +------------------+ | |
| | | Scene | | Object3D | | Camera | | Light | | |
| | | (场景根节点) | | (基类) | | (相机) | | (光照) | | |
| | +------+------+ +-----+-----+ +----+-----+ +--------+---------+ | |
| | | | | | | |
| | v v v v | |
| | +-------------------------------------------------------------+ | |
| | | Mesh (可渲染对象) | | |
| | | [BufferGeometry] + [Material] = [Renderable Object] | | |
| | +-------------------------------------------------------------+ | |
| +-----------------------------------+-----------------------------------+ |
| | (render(scene, camera)) |
| v |
| +-----------------------------------------------------------------------+ |
| | 渲染抽象层 (Renderer Abstraction Layer) | |
| | +-----------------------------------------------------------------+ | |
| | | Renderer (基类) | | |
| | | - RenderList - RenderObjects - Pipelines | | |
| | | - Bindings - Geometries - Textures | | |
| | | - Attributes - Info - Background | | |
| | | - Lighting - XRManager - PostProcessing | | |
| | +---------------------------+-------------------------------------+ | |
| | | (委托) | |
| | +---------------------------v-------------------------------------+ | |
| | | Backend (抽象基类) | | |
| | | + draw() + compute() + copyFramebuffer() | | |
| | | + createTexture() + createBuffer() + createPipeline() | | |
| | +---------------------------+-------------------------------------+ | |
| +-----------------------------------+-----------------------------------+ |
| | (接口实现) |
| +--------------------------+----------------------+ |
| | | | |
| v v v |
| +-------------------+ +--------------------+ +--------------------+ |
| | WebGL Backend | | WebGPU Backend | | WebGL Fallback | |
| | +-------------+ | | +--------------+ | | (WebGL 2 兼容层) | |
| | | WebGLState | | | | Device (GPU) | | +----------------+ | |
| | | WebGLProgram| | | | Pipeline API | | | WebGL 2.0 API | | |
| | | WebGLTexture| | | | BindGroup | | | GLSL Compiler | | |
| | | WebGLUniform| | | | CommandEnc. | | | WebGLState | | |
| | | WebGLShadow | | | | WGSL Shader | | +----------------+ | |
| | +-------------+ | | +--------------+ | | |
| | GLSL | | WGSL | GLSL | |
| +-------------------+ +--------------------+ +--------------------+ |
| ^ ^ ^ |
| | | | |
| +--------------------------+----------------------+ |
| | (着色器代码生成) |
| | |
| +-----------------------------------------------------------------------+ |
| | 节点着色层 (TSL / Node System) | |
| | +-----------------------------------------------------------------+ | |
| | | Node (节点基类) | | |
| | | - nodeType - updateType - version | | |
| | | + setup() + analyze() + generate() | | |
| | +---------------------------+-------------------------------------+ | |
| | | | |
| | +---------------------------v-------------------------------------+ | |
| | | NodeBuilder (代码生成器) | | |
| | | + build() + getMethod() + getFormat() | | |
| | +---------------------------+-------------------------------------+ | |
| | | | |
| | +--------------------+--------------------+ | |
| | | | | | |
| | v v v | |
| | +------------+ +-----------------+ +----------------+ | |
| | |GLSLBuilder | | WGSLBuilder | | Function Nodes | | |
| | |(→ WebGL) | |(→ WebGPU) | | (BSDF/Lighting) | | |
| | +------------+ +-----------------+ +----------------+ | |
| +-----------------------------------------------------------------------+ |
| |
+===============================================================================+分层职责说明：
| 层级 | 核心职责 | 关键类 |
|---|---|---|
| 应用层 | 高级加载器、控制器、后处理、导出器等扩展功能 | GLTFLoader, OrbitControls, EffectComposer |
| 场景图层 | 声明式 3D 世界建模，对象层级管理，事件分发 | Scene, Object3D, Mesh, Light, Camera |
| 渲染抽象层 | 渲染流程编排，可见性裁剪，渲染队列管理 | Renderer, RenderList, Pipelines, Bindings |
| 后端实现层 | GPU API 封装，着色器编译，纹理/缓冲区管理 | WebGPUBackend, WebGLBackend, WebGLProgram |
| 节点着色层 | 着色器节点图构建与编译，跨后端代码生成 | Node, NodeBuilder, GLSLNodeBuilder, WGSLNodeBuilder |
2.3 目录结构
shell
three.js/
├── src/ # 【核心基建】核心库源代码 (~500KB)
│ ├── Three.js # 【核心基建】WebGL 完整入口 (Core + Renderer + Shader)
│ ├── Three.Core.js # 【核心基建】核心入口 (不含特定渲染器)
│ ├── Three.WebGPU.js # 【核心基建】WebGPU + TSL 完整入口
│ ├── Three.WebGPU.Nodes.js # 【核心基建】WebGPU + 内置 TSL 节点库入口
│ ├── Three.TSL.js # 【核心基建】纯 TSL 着色语言入口
│ ├── Three.Legacy.js # 【废弃】遗留兼容，为空文件
│ ├── constants.js # 【核心基建】全局常量 (CullFace, Blending, DepthMode 等)
│ ├── utils.js # 【工具集】内部工具函数 (日志, Canvas, 警告等)
│ ├── animation/ # 【业务模块】关键帧动画系统
│ │ ├── AnimationMixer.js # 动画混合器 (核心调度器)
│ │ ├── AnimationClip.js # 动画片段 (关键帧数据容器)
│ │ ├── AnimationAction.js # 动画动作 (播放控制)
│ │ ├── AnimationObjectGroup.js # 动画对象组 (批量控制)
│ │ ├── AnimationUtils.js # 动画工具 (数组转换)
│ │ ├── KeyframeTrack.js # 关键帧轨道基类
│ │ ├── PropertyBinding.js # 属性绑定 (路径解析)
│ │ ├── PropertyMixer.js # 属性混合 (值累积)
│ │ └── tracks/ # 各类型轨道 (Vector/Quaternion/String/Color/Number/Boolean)
│ ├── audio/ # 【业务模块】Web Audio 空间音频
│ │ ├── Audio.js # 3D 音频源
│ │ ├── AudioListener.js # 音频监听器 (代表人耳)
│ │ ├── AudioContext.js # AudioContext 单例封装
│ │ ├── AudioAnalyser.js # 频谱分析
│ │ └── PositionalAudio.js # 位置音频 (空间衰减)
│ ├── cameras/ # 【业务模块】相机与投影
│ │ ├── Camera.js # 相机基类 (projectionMatrix, matrixWorldInverse)
│ │ ├── PerspectiveCamera.js # 透视投影相机
│ │ ├── OrthographicCamera.js # 正交投影相机
│ │ ├── ArrayCamera.js # 多视口相机
│ │ ├── CubeCamera.js # 立方体环境映射相机
│ │ └── StereoCamera.js # 立体渲染相机 (VR)
│ ├── core/ # 【核心基建】核心数据模型与基础设施
│ │ ├── Object3D.js # 3D 对象基类 (场景图节点, 40KB)
│ │ ├── BufferGeometry.js # GPU 友好几何体 (34KB)
│ │ ├── BufferAttribute.js # GPU Buffer 属性 (24KB)
│ │ ├── InterleavedBuffer.js # 交错缓冲区
│ │ ├── InterleavedBufferAttribute.js # 交错属性访问器
│ │ ├── InstancedBufferGeometry.js# 实例化几何体
│ │ ├── InstancedBufferAttribute.js# 实例化属性
│ │ ├── InstancedInterleavedBuffer.js
│ │ ├── GLBufferAttribute.js # 原生 GL Buffer 属性
│ │ ├── Raycaster.js # 射线检测 (射线-三角形/包围盒)
│ │ ├── EventDispatcher.js # 事件系统基类 (观察者模式)
│ │ ├── Layers.js # 渲染层 (位掩码)
│ │ ├── Clock.js # 时间测量
│ │ ├── Timer.js # 高精度计时器
│ │ ├── RenderTarget.js # 渲染目标 (FBO)
│ │ ├── RenderTarget3D.js # 3D 渲染目标
│ │ ├── Uniform.js # 单个 Uniform 封装
│ │ └── UniformsGroup.js # Uniform 组 (UBO 管理)
│ ├── extras/ # 【工具集】扩展工具与曲线系统
│ │ ├── Controls.js # 控制器基类
│ │ ├── DataUtils.js # 数据处理 (GPU 相关)
│ │ ├── ImageUtils.js # 图像处理 (格式转换)
│ │ ├── ShapeUtils.js # 形状三角剖分
│ │ ├── TextureUtils.js # 纹理生成 (棋盘格等)
│ │ ├── PMREMGenerator.js # 预计算环境贴图 (30KB)
│ │ ├── core/ # 曲线核心 (Curve/CurvePath)
│ │ ├── curves/ # 各种曲线 (CatmullRom/Bezier/Spline等)
│ │ └── lib/ # 内嵌库 (Earcut三角剖分)
│ ├── geometries/ # 【业务模块】内置几何体 (18种)
│ │ ├── BoxGeometry.js # 立方体
│ │ ├── SphereGeometry.js # 球体
│ │ ├── CylinderGeometry.js # 圆柱体
│ │ ├── ExtrudeGeometry.js # 拉伸体 (21KB)
│ │ ├── EdgesGeometry.js # 边线几何体
│ │ └── ... # 其他 13 种几何体
│ ├── helpers/ # 【工具集】可视化辅助调试
│ │ ├── AxesHelper.js # 坐标轴
│ │ ├── GridHelper.js # 网格
│ │ ├── CameraHelper.js # 视锥体
│ │ └── ... # 其他 10 种辅助器
│ ├── lights/ # 【业务模块】光源系统
│ │ ├── Light.js # 光源基类
│ │ ├── AmbientLight.js # 环境光 (均匀照明)
│ │ ├── DirectionalLight.js # 平行光 (太阳光)
│ │ ├── PointLight.js # 点光源
│ │ ├── SpotLight.js # 聚光灯
│ │ ├── HemisphereLight.js # 半球光 (天空/地面)
│ │ ├── RectAreaLight.js # 矩形区域光
│ │ ├── LightProbe.js # 光照探针 (球谐)
│ │ ├── LightShadow.js # 阴影基础 (Shadow Map)
│ │ └── webgpu/ # WebGPU 特有光源 (IES/Projector)
│ ├── loaders/ # 【核心基建】资源加载框架
│ │ ├── Loader.js # 加载器基类
│ │ ├── FileLoader.js # HTTP 文件加载
│ │ ├── LoadingManager.js # 加载队列管理
│ │ ├── ImageLoader.js # 图片加载
│ │ ├── TextureLoader.js # 纹理加载
│ │ ├── ObjectLoader.js # 对象 JSON 加载 (31KB)
│ │ ├── MaterialLoader.js # 材质 JSON 加载
│ │ ├── BufferGeometryLoader.js # 几何体 JSON 加载
│ │ ├── Cache.js # 内存缓存
│ │ └── nodes/ # TSL 节点加载器
│ ├── materials/ # 【业务模块】材质体系 (15种材质 + TSL)
│ │ ├── Material.js # 材质基类 (31KB)
│ │ ├── ShaderMaterial.js # 原始着色器材质
│ │ ├── RawShaderMaterial.js # 未预处理着色器材质
│ │ ├── MeshStandardMaterial.js # PBR 标准 (roughness/metalness)
│ │ ├── MeshPhysicalMaterial.js # PBR 物理 (clearcoat/sheen/transmission)
│ │ ├── MeshPhongMaterial.js # Phong 光照模型
│ │ ├── MeshLambertMaterial.js # Lambert 漫反射
│ │ ├── MeshToonMaterial.js # 卡通渲染 (色阶)
│ │ ├── MeshNormalMaterial.js # 法线可视化
│ │ ├── MeshDepthMaterial.js # 深度缓冲区
│ │ ├── MeshDistanceMaterial.js # 距离场
│ │ ├── MeshMatcapMaterial.js # MatCap (烘焙光照)
│ │ ├── PointsMaterial.js # 粒子系统材质
│ │ ├── LineBasicMaterial.js # 线条材质
│ │ ├── LineDashedMaterial.js # 虚线材质
│ │ ├── SpriteMaterial.js # 精灵材质
│ │ ├── ShadowMaterial.js # 阴影接收
│ │ └── nodes/ # TSL 节点材质 (NodeMaterial系列)
│ ├── math/ # 【核心基建】3D 数学与线性代数
│ │ ├── Vector2.js # 2D 向量 (18KB)
│ │ ├── Vector3.js # 3D 向量 (28KB, 最常用)
│ │ ├── Vector4.js # 4D 向量 (22KB)
│ │ ├── Matrix2.js # 2×2 矩阵
│ │ ├── Matrix3.js # 3×3 矩阵 (13KB)
│ │ ├── Matrix4.js # 4×4 变换矩阵 (33KB)
│ │ ├── Quaternion.js # 四元数 (旋转, 20KB)
│ │ ├── Euler.js # 欧拉角 (9KB)
│ │ ├── Color.js # RGBA 颜色 (25KB)
│ │ ├── ColorManagement.js # 色彩空间转换 (sRGB, Linear, Display-P3)
│ │ ├── Box2.js # 2D 包围盒
│ │ ├── Box3.js # 3D 包围盒 (21KB)
│ │ ├── Sphere.js # 包围球
│ │ ├── Plane.js # 数学平面
│ │ ├── Frustum.js # 视锥体 (6面)
│ │ ├── FrustumArray.js # 视锥体数组
│ │ ├── Ray.js # 射线 (15KB)
│ │ ├── Line3.js # 3D 线段
│ │ ├── Triangle.js # 三角形 (15KB)
│ │ ├── Spherical.js # 球坐标
│ │ ├── Cylindrical.js # 柱坐标
│ │ ├── MathUtils.js # 数学工具 (插值、钳制等, 21KB)
│ │ ├── SphericalHarmonics3.js # 球谐函数 (IBL 光照探针)
│ │ ├── Interpolant.js # 插值器基类
│ │ └── interpolants/ # 插值实现 (Linear/Cubic/Quaternion/Discrete)
│ ├── nodes/ # 【核心基建】TSL 节点着色系统
│ │ ├── Nodes.js # 节点系统统一入口
│ │ ├── TSL.js # TSL DSL 入口 (声明式着色语言)
│ │ ├── accessors/ # 节点访问器 (44个文件)
│ │ │ ├── BufferAttributeNode.js# GPU Attribute 访问
│ │ │ ├── Camera.js # 相机矩阵 / 位置
│ │ │ ├── MaterialNode.js # 材质属性 (颜色/粗糙度等)
│ │ │ ├── ModelNode.js # 模型变换矩阵
│ │ │ ├── Lights.js # 光源数据访问
│ │ │ └── ... # 其他 38 个访问器
│ │ ├── code/ # 代码生成工具
│ │ ├── core/ # 核心节点 (43个文件)
│ │ │ ├── Node.js # 节点基类 (25KB)
│ │ │ ├── NodeBuilder.js # 编译引擎 (76KB, 最复杂)
│ │ │ ├── ContextNode.js # 上下文节点
│ │ │ └── ... # 40 个核心节点类型
│ │ ├── display/ # 显示相关 (色彩空间/法线贴图等)
│ │ ├── fog/ # 雾效
│ │ ├── functions/ # BSDF 函数 / 光照模型
│ │ │ ├── BSDF/ # 双向散射分布函数 (15种)
│ │ │ └── PhysicalLightingModel.js # PBR 完整光照 (27KB)
│ │ ├── geometry/ # 几何节点
│ │ ├── gpgpu/ # GPGPU 计算着色器
│ │ ├── lighting/ # 光照计算 (25个文件)
│ │ ├── materialx/ # MaterialX 标准支持
│ │ ├── math/ # 数学运算节点
│ │ ├── parsers/ # 解析器
│ │ ├── pmrem/ # PMREM 生成
│ │ ├── procedural/ # 程序化纹理
│ │ ├── shapes/ # 形状 SDF
│ │ ├── tsl/ # TSL 核心 DSL (语法糖)
│ │ └── utils/ # 节点工具 (33个文件)
│ ├── objects/ # 【业务模块】可渲染 3D 对象
│ │ ├── Mesh.js # 网格 (Geometry+Material 组合, 12KB)
│ │ ├── SkinnedMesh.js # 蒙皮/骨骼动画网格
│ │ ├── InstancedMesh.js # GPU 实例化渲染 (10KB)
│ │ ├── BatchedMesh.js # 批量合并渲染 (47KB, 复杂度最高)
│ │ ├── Line.js # 线条
│ │ ├── LineLoop.js # 闭合线条
│ │ ├── LineSegments.js # 线段
│ │ ├── Points.js # 粒子/点云
│ │ ├── Sprite.js # 精灵 (始终面朝相机)
│ │ ├── Group.js # 逻辑组 (无几何体)
│ │ ├── Bone.js # 骨骼节点
│ │ ├── Skeleton.js # 骨架 (骨骼集合)
│ │ ├── LOD.js # 细节层次 (距离切换)
│ │ └── ClippingGroup.js # 裁剪组
│ ├── renderers/ # 【核心基建】渲染器系统
│ │ ├── WebGLRenderer.js # WebGL 渲染器 (108KB, 传统兼容入口)
│ │ ├── WebGLRenderTarget.js # WebGL FBO
│ │ ├── WebGLCubeRenderTarget.js # WebGL Cubemap FBO
│ │ ├── common/ # 跨后端抽象层 (61个文件)
│ │ │ ├── Renderer.js # 渲染器基类 (99KB, 核心渲染逻辑)
│ │ │ ├── Backend.js # 后端抽象接口 (19KB)
│ │ │ ├── RenderList.js # 渲染队列 (10KB)
│ │ │ ├── RenderObject.js # 渲染对象 (20KB)
│ │ │ ├── RenderPipeline.js # 渲染管线
│ │ │ ├── Pipelines.js # 管线管理 (12KB)
│ │ │ ├── Bindings.js # 资源绑定
│ │ │ ├── Textures.js # 纹理管理 (15KB)
│ │ │ ├── Geometries.js # 几何体管理
│ │ │ ├── Attributes.js # 属性管理
│ │ │ ├── Info.js # 统计信息 (14KB)
│ │ │ ├── XRManager.js # WebXR 全功能管理 (51KB)
│ │ │ ├── PostProcessing.js # 后处理框架
│ │ │ ├── Background.js # 背景渲染 (天空盒/颜色)
│ │ │ ├── ClippingContext.js # 裁剪上下文
│ │ │ ├── Lighting.js # 光照管理器
│ │ │ ├── QuadMesh.js # 全屏四边形 (后处理用)
│ │ │ ├── BlendMode.js # 混合模式
│ │ │ ├── CanvasTarget.js # Canvas 输出目标
│ │ │ ├── CubeRenderTarget.js # 通用 Cubemap FBO
│ │ │ ├── StorageTexture.js # 存储纹理
│ │ │ ├── Uniform.js # 通用 Uniform
│ │ │ ├── UniformsGroup.js # Uniform 组
│ │ │ └── nodes/ # 节点管理器 (NodeManager/NodeLibrary)
│ │ ├── webgl/ # WebGL 后端 (32个文件)
│ │ │ ├── WebGLProgram.js # GL 着色器程序 (31KB)
│ │ │ ├── WebGLPrograms.js # 程序缓存 (22KB)
│ │ │ ├── WebGLState.js # GL 状态机 (27KB)
│ │ │ ├── WebGLTextures.js # GL 纹理 (71KB, 最大)
│ │ │ ├── WebGLUniforms.js # GL Uniform (21KB)
│ │ │ ├── WebGLShadowMap.js # 阴影贴图 (16KB)
│ │ │ ├── WebGLLights.js # 光照状态
│ │ │ ├── WebGLMaterials.js # 材质编译 (14KB)
│ │ │ └── ... # 其他 WebGL 模块
│ │ ├── webgpu/ # WebGPU 后端
│ │ │ ├── WebGPUBackend.js # WebGPU 实现 (79KB)
│ │ │ ├── WebGPURenderer.js # WebGPU 渲染器
│ │ │ ├── descriptors/ # GPU 资源描述符 (25个文件)
│ │ │ ├── nodes/ # WGSL 构建器
│ │ │ └── utils/ # WebGPU 工具
│ │ ├── webgl-fallback/ # WebGL 2 兼容实现
│ │ │ ├── WebGLBackend.js # WebGL 2 后端
│ │ │ └── ... # WebGL 2 适配层
│ │ ├── webxr/ # WebXR 设备集成
│ │ └── shaders/ # 内建着色器资源
│ │ ├── ShaderChunk/ # 着色器代码片段 (112个)
│ │ ├── ShaderLib/ # 内置着色器库 (20个)
│ │ ├── UniformsLib.js # 内置 Uniform 库
│ │ └── UniformsUtils.js # Uniform 克隆/合并
│ ├── scenes/ # 【核心基建】场景
│ │ ├── Scene.js # 场景根节点 (环境/雾/背景)
│ │ ├── Fog.js # 线性雾
│ │ └── FogExp2.js # 指数平方雾
│ └── textures/ # 【核心基建】纹理体系
│ ├── Texture.js # 纹理基类 (18KB)
│ ├── DataTexture.js # 原始数据纹理
│ ├── DataArrayTexture.js # 2D 数组纹理
│ ├── Data3DTexture.js # 3D 体纹理
│ ├── CubeTexture.js # 立方体贴图
│ ├── CanvasTexture.js # Canvas 纹理
│ ├── VideoTexture.js # 视频纹理
│ ├── DepthTexture.js # 深度纹理
│ ├── CompressedTexture.js # GPU 压缩纹理 (BC/ETC/ASTC)
│ ├── FramebufferTexture.js # 帧缓冲纹理
│ ├── ExternalTexture.js # 外部纹理 (WebGPU)
│ └── Source.js # 纹理数据源 (Image/Canvas/Video)
├── build/ # 【配置】Rollup 构建产物
│ ├── three.cjs # CommonJS 格式
│ ├── three.module.js # ES Module 格式
│ ├── three.webgpu.js # WebGPU 完整包
│ ├── three.tsl.js # TSL 独立包
│ └── ... # 其他构建变体
├── examples/ # 【业务模块】示例、资源和 Addons
│ ├── jsm/ # 【业务模块】Addons (ES Module)
│ │ ├── Addons.js # 统一入口 (12KB)
│ │ ├── controls/ # 【业务模块】交互控制器 (Orbit/Trackball/PointerLock等)
│ │ ├── loaders/ # 【业务模块】高级加载器 (GLTF/FBX/USD/DRACO等, 53个)
│ │ ├── postprocessing/ # 【业务模块】后处理Pass (32个)
│ │ ├── shaders/ # 【业务模块】高级着色器 (54个)
│ │ ├── exporters/ # 【业务模块】导出器 (GLTF/USDZ/OBJ等, 8个)
│ │ ├── objects/ # 【业务模块】高级3D对象 (天空/海洋/反射器等)
│ │ ├── renderers/ # 【业务模块】CSS2D/CSS3D/SVG 渲染器
│ │ ├── lines/ # 【业务模块】宽线条渲染
│ │ ├── math/ # 【工具集】高级数学 (八叉树/凸包等)
│ │ ├── modifiers/ # 【业务模块】几何体修改器 (Tessellation/Simplify)
│ │ ├── environments/ # 【业务模块】环境生成 (Room/Debug)
│ │ ├── effects/ # 【业务模块】立体效果 (Anaglyph/Stereo/Parallax)
│ │ ├── curves/ # 【业务模块】NURBS 高级曲线
│ │ ├── csm/ # 【业务模块】级联阴影
│ │ ├── physics/ # 【业务模块】物理集成 (Rapier)
│ │ ├── misc/ # 【业务模块】杂项 (卷云/变形目标等)
│ │ ├── interactive/ # 【业务模块】HTML 交互对象
│ │ ├── inspector/ # 【工具集】运行时调试面板
│ │ ├── libs/ # 【工具集】第三方依赖 (Draco/KTX2/Lottie等)
│ │ ├── transpiler/ # 【工具集】TSL ↔ GLSL 转译器
│ │ ├── tsl/ # 【业务模块】TSL 扩展
│ │ ├── utils/ # 【工具集】GPU/Worker/存储工具
│ │ ├── webxr/ # 【业务模块】WebXR 扩展 (手部跟踪/点击等)
│ │ ├── animation/ # 【业务模块】CCDIK 动画求解器
│ │ ├── capabilities/ # 【工具集】WebGL 2 能力检测
│ │ ├── lighting/ # 【业务模块】光照工具 (探针生成)
│ │ ├── lights/ # 【业务模块】光照扩展
│ │ ├── materials/ # 【业务模块】高级材质
│ │ ├── textures/ # 【工具集】纹理生成
│ │ ├── offscreen/ # 【业务模块】离屏渲染
│ │ └── gpgpu/ # 【业务模块】通用 GPU 计算
│ ├── models/ # 【配置】3D 模型资源 (glTF/FBX等)
│ ├── textures/ # 【配置】纹理资源
│ ├── fonts/ # 【配置】字体文件
│ ├── sounds/ # 【配置】音频资源
│ └── screenshots/ # 【配置】示例截图
├── editor/ # 【业务模块】基于浏览器的 3D 场景编辑器
│ ├── index.html # 编辑器入口
│ ├── js/ # 编辑器逻辑
│ │ ├── Editor.js # 编辑器核心
│ │ ├── Viewport.js # 视口渲染
│ │ ├── Sidebar.js # 属性面板
│ │ ├── Toolbar.js # 工具栏
│ │ ├── Menubar.js # 菜单栏
│ │ ├── commands/ # 编辑命令 (撤销/重做)
│ │ └── libs/ # 第三方编辑器库 (CodeMirror/Esprima/Tern)
│ ├── css/ # 编辑器样式
│ └── images/ # 编辑器图标
├── docs/ # 【配置】API 参考文档 (JSDoc)
├── manual/ # 【配置】使用手册
├── test/ # 【配置】自动化测试
│ ├── unit/ # 核心库单元测试 (QUnit + Puppeteer)
│ ├── e2e/ # 端到端渲染正确性测试
│ └── benchmarks/ # 性能基准测试
├── utils/ # 【工具集】构建工具链
│ ├── build/ # Rollup 构建配置
│ ├── docs/ # JSDoc 文档生成
│ ├── server.js # 开发用 HTTP 服务器
│ ├── changelog.js # Changelog 自动生成
│ ├── generateDFGLUT.js # DFG 查找表纹理生成
│ └── packLDrawModel.mjs # LDraw 模型打包
├── files/ # 【配置】静态文件 (工作线程/二进制)
├── .github/ # 【配置】CI/CD (GitHub Actions)
├── package.json # 【配置】NPM 包定义
├── README.md # 【配置】英文 README
├── LICENSE # 【配置】MIT 开源协议
├── SECURITY.md # 【配置】安全政策
└── eslint.config.js # 【配置】代码风格配置3. 模块依赖与调用关系
3.1 全局入口与核心路由
逻辑说明：three.js 提供多个入口文件以适应不同使用场景。Three.js 是 WebGL 完整入口，Three.WebGPU.js 是 WebGPU + TSL 的入口。所有入口都引用 Three.Core.js 获取场景图、数学库等核心模块。渲染器在构造时创建 Backend 实例，Renderer 负责渲染流程编排，Backend 执行底层 API 调用。
调用拓扑 (plainText)：
text
入口文件 (多种入口)
|
+-- Three.js (WebGL 完整入口)
| +--> Three.Core.js (核心导出)
| +--> WebGLRenderer (WebGL 渲染器)
| +--> PMREMGenerator (环境贴图生成)
| +--> ShaderLib/ShaderChunk (着色器库)
|
+-- Three.WebGPU.js (WebGPU + TSL 入口)
| +--> Three.Core.js (核心导出)
| +--> WebGPURenderer (WebGPU 渲染器)
| +--> NodeMaterials (TSL 材质)
| +--> Nodes/TSL (节点系统)
|
+-- Three.WebGPU.Nodes.js (WebGPU + 内置 TSL 库)
| +--> Three.Core.js + TSL + 内置节点库
|
+-- Three.TSL.js (纯 TSL 环境)
+--> TSL (着色语言 DSL)
+--> Nodes (节点核心)
+--> 无渲染器依赖
渲染流程调用链:
WebGPURenderer.render(scene, camera)
+--> Renderer (基类).render()
+--> RenderList (收集可渲染对象)
+--> RenderObjects (管理渲染对象状态)
+--> Pipelines (管理着色器管线)
+--> Bindings (管理资源绑定)
+--> Backend.draw() (执行GPU渲染)
+--> WebGPUBackend (WebGPU API 调用)
+--> WebGLBackend (WebGL 2 API 调用)
节点着色器编译链:
TSL Fn 定义
+--> Node.setup() (节点初始化)
+--> NodeBuilder.build() (触发代码生成)
+--> Node.analyze() (分析节点类型)
+--> Node.generate() (生成着色器代码)
+--> GLSLNodeBuilder (→ WebGL)
+--> WGSLNodeBuilder (→ WebGPU)3.2 核心业务实体与关联
实体定义：
- Object3D：3D 空间中的基础实体，表示场景图中的节点，拥有 position/rotation/scale 变换属性，支持父子层级
- BufferGeometry：几何数据容器，存储顶点位置、法线、UV、索引等 GPU Buffer 数据，是渲染的基本数据单元
- Material：材质描述实体，定义物体表面的光照响应、颜色、纹理等视觉属性，支持多种光照模型
- Texture：纹理数据实体，封装 GPU 纹理资源，支持 2D/Cube/3D/压缩等多种格式
- Light：光源实体，在光照计算中为场景提供照明，不同类型对应不同的光照模型
- Camera：相机实体，定义观察者的视点和投影方式，控制最终渲染的视锥体范围
- Node (TSL)：着色器节点实体，表示 GPU 着色器中的一个计算节点，组合成节点图后编译为着色器代码
实体引用拓扑 (plainText)：
text
[Scene] 1 ---> N [Object3D]
|
+-- 1 ---> 1 [position/rotation/scale (变换)]
|
+-- 1 ---> N [Object3D] (子节点，递归)
|
+-- 1 ---> 1 [BufferGeometry] (几何数据)
| |
| +-- 1 ---> N [BufferAttribute] (顶点属性)
| +-- 1 ---> 1 [IndexBuffer] (索引缓冲)
|
+-- 1 ---> 1 [Material] (材质)
| |
| +-- 1 ---> N [Texture] (纹理贴图)
| +-- 1 ---> 1 [ShaderNode] (TSL 着色节点)
|
+-- (可选继承)
|
+-- [Mesh] (可渲染网格)
+-- [SkinnedMesh] (蒙皮动画网格)
+-- [InstancedMesh] (GPU 实例化网格)
+-- [Line/Points/Sprite] (其他可渲染类型)
+-- [Light/Camera/Helper] (非渲染场景节点)
[Renderer] 1 ---> 1 [Backend] (渲染后端)
|
+-- 1 ---> N [RenderObject] (渲染对象, 对应一个 Mesh + Material)
|
+-- 1 ---> 1 [RenderList] (渲染队列)
|
+-- 1 ---> 1 [Pipelines] (着色器管线缓存)
[NodeBuilder] 1 ---> 1 [Node] (根节点)
|
+-- 1 ---> N [Node] (子节点，形成 DAG)
|
+-- → 生成 [ShaderCode (GLSL或WGSL)]4. 核心模块详解
模块一：渲染器系统 (Renderer System)
模块名称：Renderer + Backend 双核心架构
设计说明：Renderer 负责高层次的渲染流程编排，包括场景遍历、可见性裁剪、渲染队列构建、渲染状态管理等。Backend 是抽象接口，封装具体 GPU API（WebGL/WebGPU）。这种分离允许多个后端共享同一套渲染逻辑，新增 GPU API 支持时只需实现 Backend 接口。设计模式包括策略模式（Backend 可替换）、模板方法模式（Renderer 定义渲染流程骨架）、对象池模式（RenderObject/RenderContext 复用）。
内部结构图：
text
+--------------------------------------------------------------------+
| Renderer (基类) |
| 职责: 渲染流程编排, 场景遍历, 可见性裁剪, 渲染状态管理 |
+-----------------------------+--------------------------------------+
|
+-------------------+------------------+
| | |
v v v
+------------------+ +-----------------+ +-----------------+
| RenderList | | RenderObjects | | Pipelines |
| 可见对象收集 | | 渲染对象管理 | | 管线状态管理 |
| - opaque items | | - 对象状态缓存 | | - 管线创建/缓存 |
| - transparent | | - 可见性判断 | | - 管线状态切换 |
| - shadow casters| | - 属性更新 | | - 着色器绑定 |
+------------------+ +-----------------+ +-----------------+
| | |
v v v
+--------------------------------------------------------------------+
| Backend (抽象后端接口) |
| + begin() + draw() + compute() + copyFramebuffer() |
| + end() + hasFeature() + get() + set() |
+-----------------------------+--------------------------------------+
| |
v v
+------------------+ +-------------------------+
| WebGLBackend | | WebGPUBackend |
| (WebGL 2.0) | | (WebGPU API) |
| + GLSL shaders | | + WGSL shaders |
| + WebGL context | | + GPUDevice |
| + Extensions | | + CommandEncoder |
| + GL State | | + PipelineLayout |
+------------------+ +-------------------------+模块二：场景图系统 (Scene Graph / Object3D)
模块名称：Object3D 层次化场景图 设计说明：Object3D 是所有 3D 对象的基类，采用组合模式（Composite Pattern）构建树形场景图。每个节点维护局部变换矩阵 (matrix) 和世界变换矩阵 (matrixWorld)，支持变换的层级继承（子节点变换 = 父节点变换 × 子节点局部变换）。Object3D 继承 EventDispatcher，支持事件驱动的对象生命周期管理。Raycaster 通过遍历场景树进行射线检测，利用包围盒/包围球加速裁剪。
内部结构图：
text
+------------------------------------------------------------------+
| EventDispatcher |
| + addEventListener() + removeEventListener() + dispatchEvent() |
+------------------------------+-----------------------------------+
| (继承)
+------------------------------v-----------------------------------+
| Object3D |
| + position(Vector3) + rotation(Euler) + quaternion(Quaternion) |
| + scale(Vector3) + matrix(Matrix4) + matrixWorld(Matrix4) |
| + visible(bool) + frustumCulled(bool) |
| + parent(Object3D) + children(Object3D[]) |
| |
| + add(obj) + remove(obj) + traverse(callback) |
| + updateMatrix() + updateMatrixWorld() + lookAt(target) |
| + getWorldPosition() + getWorldQuaternion() + getWorldScale() |
+------------------------------+-----------------------------------+
| (继承)
+--------------------+--------------------+
| | |
v v v
+------------------+ +------------------+ +------------------+
| Mesh | | Light | | Camera |
| + geometry | | + color | | + fov/zoom |
| + material | | + intensity | | + near/far |
| + morphTarget... | | + shadow | | + projectionMatrix|
+------------------+ +------------------+ +------------------+
|
+-----> SkinnedMesh (蒙皮动画)
+-----> InstancedMesh (GPU 实例化)
+-----> BatchedMesh (批量合并渲染)模块三：TSL 节点着色系统 (Three.js Shading Language)
模块名称：TSL (Three.js Shading Language) / Node System 设计说明：TSL 是 three.js 自研的着色语言 DSL，通过 JavaScript 函数组合构建可跨后端编译的着色器。核心设计模式是节点图 (Node Graph) + 多阶段编译管道。每个 Node 代表一个着色器计算单元（如加法、纹理采样、光照计算），节点之间通过引用形成有向无环图 (DAG)。NodeBuilder 遍历节点图，分 setup/analyze/generate 三阶段编译：setup 初始化节点，analyze 推断类型和需求，generate 根据目标后端（GLSL/WGSL）生成代码。
内部结构图：
text
+-------------------------------------------------------------------+
| TSL DSL Layer (用户接口) |
| Fn() | uniform() | attribute() | varying() | textureSample() |
| If() | Loop() | vec3() | float() | mix() |
| TSL 提供声明式 API, 自动将函数调用转换为节点图 |
+-------------------------------+-----------------------------------+
| (创建)
v
+-------------------------------------------------------------------+
| Node Graph (节点图) |
| |
| [UniformNode] ---> [OperatorNode] ---> [OutputNode] |
| (time uniform) (sin(time)) (最终颜色) |
| |
| Node (基类): |
| + nodeType + updateType + version |
| + setup(builder) + analyze(builder) + generate(builder, output)|
+-------------------------------+-----------------------------------+
| (驱动)
v
+-------------------------------------------------------------------+
| NodeBuilder (编译引擎) |
| Stage 1: setup() - 初始化节点, 收集依赖 |
| Stage 2: analyze() - 类型推导, 优化节点图 |
| Stage 3: generate() - 生成目标着色器代码 |
+-------------------------------+-----------------------------------+
| |
v v
+----------------------------+ +----------------------------+
| GLSLNodeBuilder | | WGSLNodeBuilder |
| → WebGL GLSL 代码 | | → WebGPU WGSL 代码 |
+----------------------------+ +----------------------------+模块四：材质系统 (Material System)
模块名称：Material + ShaderMaterial 双层材质体系
设计说明：Material 是材质基类，定义通用属性（颜色、透明度、混合模式、深度测试等）。各种具体材质（MeshStandardMaterial 等）描述光照模型参数。在 WebGL 后端，材质被编译为着色器程序（通过 ShaderLib/ShaderChunk 拼装着色器代码）；在 WebGPU/TSL 后端，材质属性被转换为节点图。新架构中 NodeMaterial 允许直接用 TSL 定义材质着色器而不依赖内置着色器库。
内部结构图 (plainText)：
text
+--------------------------------------------------------------------+
| Material (基类) |
| + color + opacity + transparent + blending + depthTest |
| + side (FrontSide/BackSide/DoubleSide) + alphaTest |
| + onBeforeCompile() + onBeforeRender() + needsUpdate |
+-------------------------------+------------------------------------+
| (继承/组合)
+-----------------------+--------------------------+
| | |
v v v
+-------------------+ +--------------------+ +---------------------+
| ShaderMaterial | | MeshStandardMaterial| | MeshPhysicalMaterial|
| (原始 GLSL 着色器) | | (PBR 标准材质) | | (PBR 物理材质) |
| + vertexShader | | + roughness | | + clearcoat |
| + fragmentShader | | + metalness | | + sheen |
| + uniforms | | + envMap | | + transmission |
| | | + normalMap | | + thickness |
+-------------------+ +--------------------+ +---------------------+
| | |
v v (WebGPU/TSL 后端) v
+-------------------+ +------------------------------------------+
| 编译为 WebGL 着色器 | | NodeMaterial (TSL 材质) |
| (ShaderChunk拼接) | | + vertexShaderNode (TSL Fn) |
+-------------------+ | + fragmentShaderNode (TSL Fn) |
| + 直接编译为 GLSL/WGSL, 不依赖ShaderChunk|
+------------------------------------------+模块五：动画系统 (Animation System)
模块名称：AnimationMixer + AnimationClip 关键帧动画系统
设计说明：动画系统采用关键帧插值架构。AnimationClip 存储关键帧数据（时间-值对），KeyframeTrack 管理单一属性随时间的变化曲线，AnimationMixer 是播放调度核心，管理多个 AnimationAction 的并发播放、混合和过渡。PropertyBinding 负责将动画数据绑定到具体对象属性，支持嵌套路径（如 "position.x"）。
内部结构图 (plainText)：
text
+------------------------------------------------------------------+
| AnimationMixer (动画调度器) |
| + time + timeScale |
| + clipAction() + existingAction() |
| + update(delta) + stopAllAction() |
| |
| 管理多个 AnimationAction, 每帧调用 update() 更新所有活跃动画 |
+------------------------------+-----------------------------------+
| (1:N)
v
+------------------------------------------------------------------+
| AnimationAction (动画动作) |
| + play() + stop() + crossFadeFrom() |
| + weight + time + timeScale |
| + loop (once/repeat/pingpong) + paused |
+------------------------------+-----------------------------------+
| (1:1)
v
+------------------------------------------------------------------+
| AnimationClip (动画片段) |
| + name + duration + tracks[] |
| + optimize() + trim() + toJSON() |
+------------------------------+-----------------------------------+
| (1:N)
v
+------------------------------------------------------------------+
| KeyframeTrack (关键帧轨道) |
| + name + times[] + values[] |
| + interpolant (插值器: Linear/Cubic/Quaternion) |
+------------------------------+-----------------------------------+
| (1:1)
v
+------------------------------------------------------------------+
| PropertyBinding (属性绑定) |
| + path + node + parsedPath |
| + getValue() + setValue() + bind() |
| 解析属性路径如 position.x, material.color 等 |
+------------------------------------------------------------------+5. 关键数据流程
场景一：WebGPU 渲染帧的完整生命周期
场景说明：从用户调用
renderer.render(scene, camera)到最终像素呈现在 Canvas 上，描述基于 WebGPU 后端的完整渲染管线流程。这是 three.js 中最核心的数据流，涵盖了场景图更新、可见性判断、渲染队列构建、着色器编译、GPU 绘制等关键步骤。流转时序图 (Mermaid)：
场景二：TSL 着色器编译流程
场景说明：描述开发者使用 TSL 编写自定义着色器节点的完整编译流程。NodeBuilder 分三阶段（setup/analyze/generate）将节点图转换为目标后端着色器代码。
流转时序图 (Mermaid)：
6. 接口与契约规范
6.1 核心内部模块契约 (TypeScript Interfaces)
typescript
// ============================================================
// 渲染后端契约 (Backend Interface)
// ============================================================
interface IBackend {
/** 后端初始化 */
init(renderer: Renderer): Promise<void>;
/** 开始一个新帧 */
begin(renderContext: RenderContext): void;
/** 执行绘制命令 */
draw(renderObject: RenderObject, info: Info): void;
/** 执行计算着色器 */
compute(computeNodes: ComputeNode[]): void;
/** 帧缓冲拷贝 */
copyFramebufferToFramebuffer(
src: FramebufferTexture,
dst: FramebufferTexture
): void;
/** 结束当前帧 */
end(): void;
/** 功能查询 */
hasFeature(name: string): boolean;
/** 获取后端特定数据 */
get(object: any): any;
/** 设置后端特定数据 */
set(object: any, value: any): void;
/** 创建 GPU 纹理 */
createTexture(texture: Texture): GPUTextureHandle;
/** 创建 GPU Buffer */
createBuffer(attribute: BufferAttribute): GPUBufferHandle;
/** 创建渲染管线 */
createRenderPipeline(renderObject: RenderObject): PipelineHandle;
/** 创建计算管线 */
createComputePipeline(
computeNode: ComputeNode,
pipeline: ComputePipeline
): PipelineHandle;
}
// ============================================================
// 场景图节点契约 (Object3D Interface)
// ============================================================
interface IObject3D {
/** 唯一标识 */
readonly id: number;
readonly uuid: string;
name: string;
/** 空间变换 */
position: Vector3;
rotation: Euler;
quaternion: Quaternion;
scale: Vector3;
/** 变换矩阵 */
matrix: Matrix4;
matrixWorld: Matrix4;
matrixAutoUpdate: boolean;
matrixWorldNeedsUpdate: boolean;
/** 场景图 */
parent: Object3D | null;
children: Object3D[];
/** 可见性与渲染 */
visible: boolean;
frustumCulled: boolean;
renderOrder: number;
layers: Layers;
/** 场景图操作 */
add(...objects: Object3D[]): this;
remove(...objects: Object3D[]): this;
removeFromParent(): this;
clear(): this;
/** 变换操作 */
updateMatrix(): void;
updateMatrixWorld(force?: boolean): void;
updateWorldMatrix(updateParents: boolean, updateChildren: boolean): void;
/** 空间计算 */
getWorldPosition(target: Vector3): Vector3;
getWorldQuaternion(target: Quaternion): Quaternion;
getWorldScale(target: Vector3): Vector3;
localToWorld(vector: Vector3): Vector3;
worldToLocal(vector: Vector3): Vector3;
/** 遍历 */
traverse(callback: (object: Object3D) => void): void;
traverseVisible(callback: (object: Object3D) => void): void;
traverseAncestors(callback: (object: Object3D) => void): void;
/** 射线检测 (由子类重写) */
raycast(raycaster: Raycaster, intersects: Intersection[]): void;
}
// ============================================================
// 材质契约 (Material Interface)
// ============================================================
interface IMaterial {
/** 基础属性 */
name: string;
type: string;
uuid: string;
/** 视觉属性 */
color: Color;
opacity: number;
transparent: boolean;
visible: boolean;
/** 渲染状态 */
side: FrontSide | BackSide | DoubleSide;
blending: Blending;
blendSrc: BlendingSrcFactor;
blendDst: BlendingDstFactor;
depthTest: boolean;
depthWrite: boolean;
alphaTest: number;
/** 多边形偏移 */
polygonOffset: boolean;
polygonOffsetFactor: number;
polygonOffsetUnits: number;
/** 裁剪 */
clippingPlanes: Plane[] | null;
clipShadows: boolean;
clipIntersection: boolean;
/** 模板测试 */
stencilWrite: boolean;
stencilFunc: StencilFunc;
stencilRef: number;
stencilWriteMask: number;
stencilFuncMask: number;
stencilFail: StencilOp;
stencilZFail: StencilOp;
stencilZPass: StencilOp;
/** 生命周期回调 */
onBeforeCompile(shader: Shader, renderer: WebGLRenderer): void;
onBeforeRender(
renderer: Renderer,
scene: Scene,
camera: Camera,
geometry: BufferGeometry,
object: Object3D,
group: Group
): void;
/** 更新标记 */
needsUpdate: boolean;
/** 序列化/反序列化 */
toJSON(meta?: any): any;
clone(): this;
copy(source: Material): this;
dispose(): void;
}
// ============================================================
// TSL 节点契约 (Node Interface)
// ============================================================
interface INode {
/** 节点类型 (结果类型, 如 'float', 'vec3', 'color') */
nodeType: string | null;
/** 更新类型 */
updateType: NodeUpdateType;
updateBeforeType: NodeUpdateType;
updateAfterType: NodeUpdateType;
/** 版本号, 自动递增 */
readonly version: number;
/** 更新标记 */
needsUpdate: boolean;
/** 节点标识 */
readonly id: number;
readonly uuid: string;
/** 编译阶段 */
setup(builder: NodeBuilder): void;
analyze(builder: NodeBuilder): void;
generate(builder: NodeBuilder, output?: string): string;
/** 更新回调 */
update(frame?: NodeFrame): void;
updateBefore(frame?: NodeFrame): void;
updateAfter(frame?: NodeFrame): void;
}
// ============================================================
// 渲染器契约 (Renderer Interface)
// ============================================================
interface IRenderer {
/** Canvas 元素 */
domElement: HTMLCanvasElement | OffscreenCanvas;
/** 渲染一帧 */
render(scene: Scene, camera: Camera): void;
/** 设置渲染循环 */
setAnimationLoop(callback: ((time: number) => void) | null): void;
/** 设置视口大小 */
setSize(width: number, height: number, updateStyle?: boolean): void;
/** 渲染目标 */
setRenderTarget(
renderTarget: RenderTarget | null,
activeCubeFace?: number,
activeMipmapLevel?: number
): void;
getRenderTarget(): RenderTarget | null;
/** 清除 */
clear(color?: boolean, depth?: boolean, stencil?: boolean): void;
setClearColor(color: Color, alpha?: number): void;
/** 信息统计 */
info: {
render: { calls: number; triangles: number; points: number; lines: number };
memory: { geometries: number; textures: number };
programs: number;
};
/** 资源管理 */
dispose(): void;
}对外 API 契约 (OpenSpec 格式 — 公共类 API)
yaml
# three.js 公共 API 关键类型定义
components:
schemas:
PerspectiveCamera:
type: object
description: 透视投影相机
properties:
fov:
type: number
description: 垂直视野角度 (度)
default: 50
aspect:
type: number
description: 宽高比 (width/height)
near:
type: number
description: 近裁剪面距离
default: 0.1
far:
type: number
description: 远裁剪面距离
default: 2000
position:
$ref: '#/components/schemas/Vector3'
rotation:
$ref: '#/components/schemas/Euler'
MeshStandardMaterial:
type: object
description: PBR 标准材质 (金属/粗糙度工作流)
properties:
color:
$ref: '#/components/schemas/Color'
description: 基础颜色
roughness:
type: number
description: 粗糙度 (0.0 - 1.0)
minimum: 0
maximum: 1
default: 1.0
metalness:
type: number
description: 金属度 (0.0 - 1.0)
minimum: 0
maximum: 1
default: 0.0
map:
$ref: '#/components/schemas/Texture'
description: 基础颜色贴图
roughnessMap:
$ref: '#/components/schemas/Texture'
description: 粗糙度贴图
metalnessMap:
$ref: '#/components/schemas/Texture'
description: 金属度贴图
normalMap:
$ref: '#/components/schemas/Texture'
description: 法线贴图
envMap:
$ref: '#/components/schemas/Texture'
description: 环境贴图 (IBL)
envMapIntensity:
type: number
default: 1.0
WebGPURenderer:
type: object
description: WebGPU 渲染器 (自动回退到 WebGL 2)
properties:
domElement:
type: HTMLCanvasElement | OffscreenCanvas
description: 渲染输出目标
info:
type: object
description: 渲染统计信息
methods:
render:
parameters:
- name: scene
type: Scene
- name: camera
type: Camera
description: 渲染一帧
setAnimationLoop:
parameters:
- name: callback
type: function | null
description: 设置动画渲染循环8. 快速开始
8.1 环境配置
bash
# 需要 Node.js 18+
node --version
# 克隆仓库
git clone --depth=1 https://github.com/mrdoob/three.js.git
cd three.js
# 安装依赖
npm install8.2 安装与运行
bash
# 开发模式 (启动构建监听 + HTTP 服务器)
npm start
# 构建
npm run build
# 运行测试
npm test
# 构建文档
npm run build-docs8.3 典型用例
javascript
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();
renderer.setSize(window.innerWidth, window.innerHeight);
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);
// 添加光照
const light = new THREE.DirectionalLight(0xffffff, 1);
light.position.set(1, 1, 1);
scene.add(light);
camera.position.z = 5;
// 渲染循环
renderer.setAnimationLoop(() => {
cube.rotation.x += 0.01;
cube.rotation.y += 0.01;
renderer.render(scene, camera);
});