web3d-runtime

web3d-runtime——场景在每块 GPU 上都能运行，而且你可以证明它有多快

three.js 的 WebGPU 发展很快：r186 会抛出异常，而 r180 只会发出警告；后处理入口点已重命名，Clock 已弃用，而且同一 API 下仍提供 WebGL2 后端。 这里的大多数错误都悄无声息——场景会渲染，只是渲染错了。因此，这项技能先介绍故障，再介绍模式。

第一步——检查，然后报告

1. 版本。 从 package.json 中查看 three、@react-three/fiber、@react-three/drei。这里的事实以 r186 为准；若使用其他版本，在相信某个名称前，先查看 references/renderer-and-loop.md → 版本说明。
2. 渲染器。 使用的是 three/webgpu 中的 WebGPURenderer，还是经典的 WebGLRenderer？是否有自定义的 ShaderMaterial、RawShaderMaterial 或 onBeforeCompile？这些在 WebGPU 上都无法运行（注意事项）。
3. 循环。 由谁负责每一帧：setAnimationLoop、R3F 的 useFrame，还是多个 requestAnimationFrame（这是个错误——每个场景只能有一个时钟）。
4. 速度证据。 是否有任何测量数据（Inspector、时间戳、在性能最弱的目标设备上负载运行时的 fps），还是只有主观感受？

以表格形式报告——领域 · 当前情况 · 问题 · 修复方案——并且只给出一个下一步行动。

能力阶梯

按场景从上到下选择合适的阶梯；每一阶都必须仍然是可运行的页面。

1. WebGPU——new WebGPURenderer()，然后执行 await renderer.init()。
2. 同一渲染器的 WebGL2 后端——WebGPU 不可用时自动启用（会记录 running under WebGL2 backend）；使用 forceWebGL: true 强制启用。此处需要为计算密集型功能提供更轻量的路径：在 init() 后通过 renderer.backend.isWebGPUBackend 进行检测。
3. 静态降级——完全不使用 WebGL、减少动态效果，或设备丢失且无法恢复时，使用静态图片或 CSS/SVG 静态画面，并确保内容清晰易读。这是将 sheleg-design 的平静降级规则应用到 3D 场景。

注意事项 — r186，每一项都可能静默发生或出人意料

• render() 会在 await renderer.init() 之前抛出异常（因此 clear()、hasFeature()、 initTexture() 也会如此）；setAnimationLoop 会自行等待初始化。自 r181 起，renderAsync 及相关方法已弃用。
• positionNode 会在蒙皮、变形和实例化之后替换位置。 positionLocal.add(offset) 会保留它们；单独使用 positionGeometry.add(...) 或 buffer.element(instanceIndex) 会让每个实例都坍缩到一个点。粒子请使用官方模式：在精灵或点材质上设置 positionNode = buffer.toAttribute()。
• JS 重新赋值并不会写入着色器存储。 在 Fn 中，a = a.add(1) 会重新绑定 JS 名称， 不会生成任何内容；请先使用 .toVar()，再调用 .assign()／.addAssign()。对节点使用 JS if 或三元表达式 也会导致同样的问题——请使用 If／select。
• 原子操作需要在 atomicAdd 之前调用 storage(buf, 'uint', n).toAtomic()。
• computeAsync() 不会等待 GPU 完成。 只有 renderer.getArrayBufferAsync() 会将结果读回 CPU（r186 中可复用 THREE.ReadbackBuffer）。
• ShaderMaterial、RawShaderMaterial 和 onBeforeCompile 没有 WebGPU 映射——该对象会作为普通节点材质渲染，并报出「不兼容」错误。请移植到 TSL。大约 20 个 drei 组件基于这些功能构建，因此也会以同样方式失败。
• 适配器会以兼容模式请求；如果设备只提供这种模式，MSAA 会被静默禁用。
• WebGPURenderer 中的 alpha 默认值为 true（WebGLRenderer 中为 false）：依赖不透明画布的移植代码会透出页面内容。
• PostProcessing 现已更名为 RenderPipeline；Clock 已弃用——请使用 Timer（core）； WebGPU 上已移除 PCFSoftShadowMap（自 r183 起，PCFShadowMap 为软阴影）； renderer.dispose() 是异步的。
• **设备丢失：**使用 renderer.onDeviceLost（验证错误和内存不足错误则使用 renderer.onError）。两个后端都支持它；直接挂接 WebGPU 设备会在 WebGL2 回退时失效。
• **R3F 9.8.1 的默认值与 three.js 不同：**启用 ACES 色调映射，shadows={true} 会选择已移除的软阴影贴图（请使用 shadows="percentage"），且 useFrame 的 delta 不会被钳制。

操作流程

1. 渲染器和循环——一个渲染器、await init()、一个 setAnimationLoop、一个 Timer （references/renderer-and-loop.md）。
2. 使用 TSL 编写材质和着色器；对任何逐粒子或逐实例的计算使用 compute （references/tsl-and-compute.md）。
3. **预热：**在首个可见帧之前调用 await renderer.compileAsync(scene, camera)（compute 则调用 compileComputeAsync），避免首次交互时卡顿。
4. 在性能最弱的目标设备上测量，使用 Inspector 或时间戳查询，然后分配性能预算 （references/performance-and-r3f.md）。
5. **降级：**减少动态效果、不支持 WebGPU、设备丢失和标签页隐藏，都要有明确的代码分支——并且每个分支都经过实际验证。
6. **清理：**释放几何体、材质、纹理和渲染目标； await renderer.dispose()。

缺少条件时的处理

• 此环境中完全没有工具 → 写出命令和代码，绝不伪造执行结果。未经测量的大小、通过结果、帧时间或「已完成」都属于伪造证据；将每项此类检查标记为 NOT_RUN，并说明需要由人执行什么。
• 此环境中没有浏览器或 GPU → 构建、进行类型检查并审查；将视觉效果和帧时间门槛报告为 NOT_RUN，并注明需要由人使用的页面和设备。绝不要仅凭阅读代码就声称「流畅」。
• 项目使用较旧版本的 three.js → 指明版本差距；不要不加判断地套用 r186 的名称，也不要未经操作者同意就升级依赖。
• R3F 项目需要使用 WebGPU → 使用 references/performance-and-r3f.md 中的异步 gl 工厂模式；切换之前，列出场景所用且无法在 WebGPU 上运行的 drei 组件。

参考资料

阅读	适用场景
references/renderer-and-loop.md	创建渲染器、回退方案、循环和时钟、色彩与色调映射、后期处理、设备丢失、释放资源
references/tsl-and-compute.md	编写 TSL 材质或着色器、计算通道、粒子、原子操作、回读，或移植 GLSL
references/performance-and-r3f.md	测量或修复帧时间、绘制调用和内存；在 WebGPU 上运行 React Three Fiber；在 WebGPU 上使用 drei

资源文件和预算见 web3d-assets；制作动画见 web3d-animation。公开的 webgpu-threejs-tsl 技能（dgreenheck）启发了本文优先讲解常见问题的结构；重新依据 r186 核验其示例时发现的勘误，也列在上面的常见问题中。

触发词

其他会将请求路由到此处的短语：“WGSL”、“compute shader” / “компьют-шейдер”、“particles collapsed” / “частицы схлопнулись”、“device lost” / “потеря устройства”、“React Three Fiber”、“post-processing” / “постобработка”、“WebGL fallback”。

这些短语于 0.2.4 版本从描述中移至此处：“three.js WebGPU”、“the 3D scene is slow”。