threejs-scene-composition

Three.js 场景合成

当深度、相机、灯光、材质响应、几何体或空间动画承载了媒体创意，且浏览器渲染的场景适合作为制作载体时，请使用 Three.js。本技能从已明确资产需求和创意意图后开始，到生成可复现的渲染场景包为止。

本技能不讲解网格建模、重拓扑、绑定制作、物理模拟、WebXR 产品设计或游戏逻辑。它可以使用由其他流程制作并获批的 glTF 资产、动画片段、纹理、环境贴图、字体、数据和音频提示。

证据标准

• 文档事实是指由 Three.js、Khronos、WebGL 或 W3C 官方资料明确规定的行为。
• 制作经验法则是指实用的起点，必须在实际场景和交付硬件上进行测试。
• 实测结果是指从场景、帧输出、浏览器、GPU 或编码后的交付物中测得的结果。

Three.js 经常发布新版本，示例和附加组件的路径或 API 也可能变化。事实和链接已于 2026-07-12 核验。请固定并记录已安装的版本，查看迁移说明，并在交付前测试目标浏览器和渲染器。WebGPU 支持和渲染器一致性尤其容易变化。

判断 Three.js 是否适合作为渲染器

在交付内容需要以下能力时，请使用 Three.js：

• 真实的 3D 相机、视差、深度、遮挡或空间连续性；
• 使用浏览器 PBR 材质渲染 glTF 场景或产品资产；
• 骨骼、形态目标、关键帧或程序化 3D 动画；
• 自定义着色器、粒子、实例化或后期处理；
• 从基于浏览器的合成系统中确定性地捕获帧；
• 将同一场景适配到多种宽高比或相机取景。

在以下情况下，优先考虑其他方案：

• 2D 合成器可以更清晰、更经济地呈现效果；
• 工作内容是为下游引擎准备网格，而非合成镜头；
• 需要精确的离线路径追踪、电影级模拟或原生 DCC 交接；
• 已有静态产品渲染，且不再需要 3D 修改；
• 目标依赖浏览器交互，而非渲染后的媒体交付物。

不要仅仅为了让合成看起来更昂贵而添加 3D 场景。相机和维度必须服务于传达的信息。

明确场景规范

开始实施前，请定义：

• 输出尺寸、宽高比、帧率、时长、是否需要 Alpha，以及色彩/HDR 要求；
• 镜头列表，包括每个节拍的相机、镜头/FOV、主体、动作、灯光变化和转场；
• 获批资产及其比例、轴向、枢轴、动画片段、形态目标、材质和使用权；
• 材质参考和色彩关键要求；
• 环境、灯光、阴影、反射、背景、雾效和后期处理；
• 确定性输入：种子、数据、动画时间、模拟缓存和资产版本；
• 性能范围：浏览器、GPU/软件路径、内存、帧尺寸、渲染工作进程和交付期限；
• 无障碍要求，尤其是闪烁、快速相机运动和减少动态效果的替代版本；
• 审核关卡：灰盒、视觉开发、动画、压力测试帧、编码样片和最终版本。

创建场景清单，将稳定 ID 映射到文件、校验和、变换、许可证及场景用途。最终渲染前，请将远程资产冻结到本地。

场景、相机和渲染器架构

文档事实： Three.js 会将 Object3D 层级组合到 Scene 中，通过相机查看，并由渲染器绘制。子级变换会继承父级变换。透视相机和正交相机适用于不同的空间观感。

请按制作职责组织场景：

scene
+- world
|  +- environment
|  +- set
|  `- practical-lights
+- subject-root
|  +- approved-model
|  `- subject-controls
+- fx-root
+- camera-rig
|  +- camera-target
|  `- camera
`- review-guides

使用稳定的名称，并将相机支架、主体变换、导入的动画和程序化特效分开。避免通过数组索引修改嵌套较深的导入节点；应一次性解析具名节点，并验证其确实存在。

摄像机方向

• 需要类似镜头的纵深感时选择透视投影，制作图解式或等距场景时选择正交投影。
• 合理设置近裁剪面和远裁剪面，在保证有效深度精度的同时避免裁切获准的运动范围。
• 动画应使用摄像机支架或目标，不要混用彼此无关的摄像机直接变换。
• 按实际宽高比测试构图。居中裁剪不能替代竖屏构图方案。
• 摄像机的速度、加速度和地平线变化应符合受众需求和减少动态效果的要求。

导入并验证 glTF 素材

文档事实： glTF 2.0 描述场景、节点、网格、蒙皮、动画、摄像机、PBR 材质、纹理和二进制资源。Three.js 的 GLTFLoader 会返回已加载的场景和动画剪辑，并支持一组有文档说明的 glTF 扩展。glTF 核心材质采用金属度-粗糙度 PBR。

对于每个导入的素材：

1. 使用 Khronos glTF Validator 验证源文件。
2. 记录必需/使用的扩展，并确认加载器支持这些扩展。
3. 检查场景比例、朝向、边界、枢轴、摄像机、灯光、蒙皮、变形目标、动画和材质数量。
4. 检查纹理的色彩空间标注以及 UV/切线行为。
5. 在参考查看器和生产场景中对比素材。
6. 保留源文件包；记录任何转换、压缩或材质覆盖。

只有在检查解码器部署、目标支持、视觉变化和启动成本后，才使用 Draco 或网格压缩以及 KTX2/Basis 纹理路径。压缩是交付决策，并不会自动提升质量。

色彩、材质和灯光

文档事实： Three.js 使用色彩管理工作流，并以 Linear-sRGB 作为工作色彩空间。底色和自发光贴图等色彩纹理需要标注为 sRGB 色彩空间；法线、粗糙度和金属度贴图等非色彩数据纹理不应按色彩处理。输出转换和色调映射属于渲染器职责。

色彩关键工作流：

• 将每种纹理识别为色彩纹理或数据纹理；
• 有意识地设置渲染器的输出色彩空间；
• 选择并记录色调映射和曝光；
• 通过完整的渲染和编码链，对比中性参考值和已批准的产品色彩；
• 不要只在一种风格化灯光下判断材质色彩；
• 不要重复烘焙显示转换。

在需要关注灯光响应时使用基于物理的材质。保留电介质与金属之间预期的区别；只有在素材和目标平台支持时，才评估粗糙度、法线、清漆、透射、体积、光泽、虹彩和其他扩展。

灯光方案：

• 将环境/反射光与直射灯光分开设置；
• 仅在符合视觉意图时使用主光/补光/轮廓光，或有场景依据的实用光源系统；
• 明确指定投射阴影的对象和接收阴影的对象；
• 将每个阴影摄像机/视锥体适配到有效区域；
• 针对阴影痤疮和悬浮现象调整偏差和法线偏差；
• 在最终分辨率和压缩条件下测试接触阴影和轮廓。

生产经验法则：先用最少的灯光和阴影贴图塑造预期形态。只有出现明显缺陷时才增加复杂度，不要仅仅因为更多灯光听起来更有电影感就增加灯光。

动画系统

Three.js 可以组合导入的动画剪辑、脚本化变换、变形目标、摄像机和着色器统一变量。为每个属性明确指定唯一的控制者。

导入的片段和骨骼动画

已记录的事实：AnimationMixer 控制由 AnimationClip 数据创建的 AnimationAction 实例。片段包含关键帧轨道。动作可以循环、交叉淡化、改变权重，并使用常规或加法混合。

• 验证片段名称、时长、循环意图、根运动、绑定姿势和缩放。
• 测试极端变形和过渡，而不只是片段中段。
• 有意决定是规范化还是保留根运动。
• 只有在姿势和接触约束允许时，才使用交叉淡化来保持性能连续性。
• 在混合前后逐帧检查脚、手、道具、面部变形和阴影。

变形目标

使用变形来实现经批准的形状变化、面部姿势或修正变形。验证拓扑和目标顺序是否匹配。对影响值进行钳制或有意组合；检查中间状态是否存在体积损失、自相交和纹理拉伸。

程序化运动

尽可能将程序化状态写成合成时间的纯函数：

function applyFrameState(frame, fps) {
  const time = frame / fps;
  subject.rotation.y = baseRotation + time * radiansPerSecond;
  material.uniforms.uTime.value = time;
  cameraRig.position.copy(cameraPath.getPointAt(clamp01(time / shotDuration)));
}

此示例假设 clamp01(value) 返回 Math.max(0, Math.min(1, value))，且 cameraPath 是已配置的 Three.js 曲线，例如 Curve3 实现。请分别验证实际曲线和相机目标。

为粒子分布和噪声输入设置种子。导出帧时，不要通过 position.x += ... 累积状态，因为向后查找或按乱序渲染帧会产生错误结果。

确定性帧渲染

实时预览通常使用 requestAnimationFrame 和增量时间差。固定媒体采集则应根据请求的帧推导整个场景状态。

对于每一帧：

1. 根据合成约定计算 time = frame / fps。
2. 使用已安装版本所支持的混合器／动作策略，将导入的动画设置到该绝对时间；不要依赖未知次数的先前 update(delta) 调用。
3. 根据绝对时间或缓存的确定性状态，设置相机支架、程序化变换、粒子、着色器、变形和可见性。
4. 更新所需的世界矩阵、骨架和渲染目标。
5. 渲染场景和后期处理链一次。
6. 通过宿主渲染器读取或采集已完成的帧。

适配器示例结构：

export function renderAtFrame(frame, fps) {
  const time = frame / fps;
  mixer.setTime(time);
  applyFrameState(frame, fps);
  scene.updateMatrixWorld(true);
  composer.render();
}

使用非单位混合器时间缩放调用 setTime() 前，请检查当前 AnimationMixer 的语义。核心原则是按绝对时间求值，而非拘泥于某个 API 调用。

最终采集期间，不要使用墙上时钟时间、无种子随机数、实时网络响应、隐藏标签页计时、设备方向或不受约束的物理模拟。若模拟不可或缺，请将其烘焙，或定义可复现的固定步长缓存。

在两次干净运行中渲染相同的压力测试帧并进行比较。不同后端或硬件上的 GPU 像素可能存在差异；如需精确复现，请定义容差并锁定渲染环境。

着色器和后期处理

如果内置材质能满足视觉要求，请优先使用。自定义 ShaderMaterial、原始着色器、基于节点的着色以及后期处理会扩大创作空间，也会增加可移植性风险。

对于自定义着色器：

• 记录 uniforms、坐标空间、精度假设和所需扩展；
• 使用合成时间驱动时间；
• 对不稳定的数学运算进行钳制，并测试边界值；
• 在第一帧之前编译／预热所有生产变体；
• 捕获着色器错误和渲染器信息；
• 如果目标后端无法运行该效果，请提供回退方案。

对于后期处理：

• 指定处理通道的顺序，因为效果通常不可交换；
• 按完整交付分辨率预算渲染目标内存；
• 压缩后检查辉光、模糊、景深、颗粒和色差效果；
• 避免使用掩盖资产或材质缺陷的效果；
• 检查最终处理流程中的 alpha 和预乘状态。

性能与资源管理

已记录的事实： 从场景中移除网格不会自动释放其几何体、材质、纹理或渲染目标 GPU 资源。可释放的资源提供 dispose() 方法。Three.js 提供渲染器内存信息，可用于诊断。

生产方案：

• 在对象标识允许时，重复使用几何体和材质；
• 对重复对象使用实例化或批处理；
• 在牺牲主体轮廓之前，先减少绘制调用、材质变体、过度绘制、透明图层和投射阴影的对象；
• 仅在摄像机距离足以让替换效果不可见时，才使用细节层次；
• 按纹理在屏幕上最大有效覆盖范围确定纹理尺寸；
• 释放已替换的几何体、材质、纹理、渲染目标、控制器和后期处理资源；
• 在拆除时移除事件监听器并停止动画循环。

测量具有代表性的序列，而非空场景。记录加载时间、首帧着色器编译时间、峰值内存、每帧渲染时间、读取／捕获开销，以及编码后的输出质量。

无障碍与观看安全

已记录的事实： WCAG 2.2 SC 2.3.1 限制内容在任意 1 秒内闪烁不超过 3 次，除非其低于一般闪光和红色闪光阈值。应在循环播放时评估循环内容，并以预期的最大呈现尺寸进行测试。

还应检查：

• 快速的全视野摄像机移动、旋转、缩放、视差和地平线滚转；
• 闪烁的阴影、深度冲突、发光脉冲、闪电、粒子和后期效果；
• 仅通过颜色、深度或运动传达的信息；
• 叠加在变化的 3D 背景上的字幕和必要文本；
• 在受众或发布目的需要时，提供减少动态效果的渲染版本。

对于交互式发布，应提供动态效果控制，并在适用时尊重用户偏好。对于预录视频，应单独制作较为平缓的输出，因为媒体查询无法改变已经渲染的像素。

权利与来源记录

Three.js 采用 MIT 许可证，但场景依赖项仍各自遵循其许可条款。记录模型、纹理、HDRI、字体、着色器、动态片段、动作捕捉、插件、徽标和参考媒体的许可证与使用权限。对于生成的素材，在信息可用时，应记录提供方、模型、版本、提示词和随机种子等元数据。

不要假设从公开演示中下载的素材已获得商业再利用许可。保留必要的声明。如果模型描绘了真人、品牌产品、私人场所、艺术作品或受保护角色，应在渲染前核实适用的同意与权利。

渲染质量检查与交付

检查以下关卡：

• 结构： 所有素材均可从本地加载；记录 glTF 验证结果和扩展支持情况。
• 构图： 摄像机、裁剪、安全区域、近远裁剪面和各宽高比变体均通过检查。
• 外观： 色彩空间、色调映射、曝光、材质、反射、灯光和阴影均符合审批结果。
• 动态效果： 片段、混合、变形、程序化状态、摄像机路径、接触效果和循环，在逐帧检查与正常播放时均通过检查。
• 确定性： 重复的压力测试帧和向后跳转的结果均符合声明的容差。
• 性能： 峰值内存和渲染时间符合生产资源范围；拆除时会释放可释放的资源。
• 安全： 闪烁和大视野动态效果检查通过，或已交付更安全的版本。
• 输出： 帧数、帧率、尺寸、透明度、编解码器、音频同步和压缩均通过检查。

交付内容应包括源代码、固定版本的依赖项／锁文件、本地素材、场景清单、渲染设置、确切的命令或宿主入口、代表性帧检查结果、性能说明、来源记录、许可证声明、质量检查报告，以及已知的后端限制。

示例 1：对色彩要求严格的产品环绕镜头

这是一个完整示例，并非必须遵循的公式。

**目标：**为新品发布制作一段 12 秒、4K 的已批准跑鞋环绕视频。材质和色彩还原比戏剧性效果更重要。

**输入和约束：**经过验证的 GLB；已批准的基色样本；两套 4K 纹理；已获授权的摄影棚 HDRI；3840x2160、30 fps；用于审核的 H.264 视频，以及高质量母版帧；不得虚构徽标或几何形状。

工作流：

1. 加载并盘点 GLB，确认以米为单位的比例、边界、命名材质、UV 和所需扩展。
2. 将基色纹理标注为 sRGB，并将法线／粗糙度／金属度贴图保留为非颜色数据。
3. 搭建中性环境，加上一盏宽光源主光和克制的轮廓光；让柔和的接触阴影贴合转台。
4. 以已批准的色样和中性参考卡为基准，锁定色调映射和曝光。
5. 保持鞋子静止，让摄像机装置沿一条经过缓动处理的 210 度环绕路径运动；最后两秒停留在主打的四分之三视角。
6. 根据绝对帧时间计算摄像机和转台状态。
7. 在完整导出前，将第 0、1、90、180、299、300 和 359 帧各渲染两次。
8. 将编码后的审核视频与母版帧进行对比，检查细网格、徽标、阴影和色彩变化。

**预期结果：**几何形状和徽标稳定，摄像机帧可重复，材质响应中性，接触效果清晰，最终编码的色彩符合批准结果。

**可能的问题：**重复进行色彩转换、粗糙度贴图被标记为 sRGB、环境光压过已批准的色彩、近裁剪面裁切、首帧出现着色器编译卡顿，以及压缩损坏针织纹理。

**变体：**对于 9:16 画幅，应设计更近的摄像机路径和不同的最终停留画面，而不是裁剪 16:9 环绕镜头。

示例 2：程序化标题世界

这是一个完整示例，并非必须遵循的公式。

**目标：**制作一段 8 秒的标题序列，其中 2,000 根实例化柱体升起，形成城市风格的文字轮廓，同时摄像机穿过其中。

**输入和约束：**1920x1080、30 fps；一个已批准标题；无外部 3D 资产；确定性种子；克制的辉光；减少动态效果的替代版本；无闪烁。

工作流：

1. 使用已存储的种子和带版本号的生成设置，将已批准的标题蒙版转换为冻结的逐实例目标高度表。
2. 使用一种实例化几何体／材质和逐实例变换来渲染柱体。
3. 根据绝对时间、目标高度和确定性的空间延迟驱动每根柱体的高度；不要累积修改高度。
4. 使用已设定位置和注视目标的摄像机样条曲线；限制地平线倾斜。
5. 在主渲染后应用轻微的泛光处理，并验证处理顺序和渲染目标内存。
6. 让清晰可读的标题轮廓停留 1.5 秒。
7. 减少动态效果的版本使用固定摄像机，并缩短柱体运动距离。
8. 进行全屏闪烁审核，并对压力测试帧进行重复对比。

**预期结果：**不同渲染中的实例布局完全一致，无单帧跳变，标题清晰可读，摄像机稳定，GPU 内存用量有界。

**可能的问题：**实例放置未使用种子、累积变换导致向后跳转失效、密集柱体产生摩尔纹、泛光过强、摄像机裁切，以及缺少清晰可读的停留画面。

**变体：**如果 GPU 或渲染工作进程的资源限制较严，可预渲染带 Alpha 的 3D 图层，并在 2D 运行时中合成，同时保留场景清单和来源信息。

来源

已于 2026-07-12 核查的官方和权威来源：

• Three.js 文档和手册：https://threejs.org/docs/ 和 https://threejs.org/manual/
• Three.js 动画系统：https://threejs.org/manual/en/animation-system.html
• Three.js 色彩管理：https://threejs.org/manual/en/color-management.html
• Three.js 清理指南：https://threejs.org/manual/en/cleanup.html
• Three.js GLTFLoader：https://threejs.org/docs/#examples/en/loaders/GLTFLoader
• Khronos glTF 2.0 规范：https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html
• Khronos glTF 验证器：https://github.com/KhronosGroup/glTF-Validator
• WebGL 2.0 规范：https://registry.khronos.org/webgl/specs/latest/2.0/
• Three.js 许可证：https://github.com/mrdoob/three.js/blob/dev/LICENSE
• W3C WCAG 2.2，“三次闪烁或低于阈值”：https://www.w3.org/WAI/WCAG22/Understanding/three-flashes-or-below-threshold.html