在 Chrome/WebGPU 项目中集成…

当需要在浏览器中用 WebGPU 加速实现刚体/软体、碰撞、关节和弹簧模拟，并接受实验性 Chrome-only 项目时使用。

适用场景

解决思路

1. 安装与运行：执行 `git clone https://github.com/jure/webphysics.git`，`cd webphysics`，`npm install`；开发用 `npm run dev`，生产构建用 `npm run build`；Vite 开发服务器通常为 `http://localhost:5173`。
2. 按项目结构定位：主编排在 `src/physics/PhysicsEngine.ts`；GPU 求解在 `src/physics/gpu/avbdState.ts`；broad phase 在 `src/physics/gpu/broadPhase.ts`；narrow phase 在 `src/physics/gpu/contactGeneration.ts`；接触记录在 `src/physics/gpu/contactRecord.ts`；LBVH 构建在 `src/lvbh/GPULBVHBuilder.ts`。
3. 初始化引擎：先通过 `navigator.gpu.requestAdapter()` 获取 adapter，再 `adapter.requestDevice()` 获取 GPUDevice；用 `const engine = new PhysicsEngine(device); await engine.init();` 创建并初始化。
4. 添加刚体：调用 `engine.addBody`，传入 `type: 'box'`、`position`、`rotation`（四元数 `[x,y,z,w]`）、`halfExtents`、`mass`（静态体用 0）、`restitution`、`friction`；静态地面和动态盒子的示例参数按原文设置。
5. 步进模拟：设 `TIMESTEP = 1 / 60`、`SUBSTEPS = 10`，在游戏循环中调用 `engine.step(dt, SUBSTEPS)`，再用 `engine.getBodyStates()` 读回状态并调用 `requestAnimationFrame(gameLoop)`。
6. 读取状态用于渲染：在 `engine.step()` 后调用 `engine.getBodyStates()`，遍历每个 state 的 `position`、`rotation`（四元数 `[x,y,z,w]`）、`bodyIndex`，用 `updateMeshTransform(bodyIndex, position, rotation)` 更新网格。
7. 添加关节/约束：调用 `engine.addJoint`，设置 `type: 'distance'`、`bodyA`、`bodyB`、`anchorA` 与 `anchorB`（局部空间锚点）、`restLength`、`stiffness`。
8. 添加弹簧/软体约束：调用 `engine.addSpring`，设置 `bodyA`、`bodyB`、`anchorA`、`anchorB`、`restLength`、`stiffness`、`damping`。
9. 理解 AVBD 管线：按 Algorithm 1 顺序处理：1 collision detection (`x^t`)；2 broad phase (LBVH)；3 narrow phase + warm start；4 per-body constraint lists；5 graph coloring；6 inertial target `y`、primal init、warm-start `α/γ`；7 循环 colored primal body solve（近似 Hessian）；8 循环 dual + stiffness update；9 finalize velocities。
10. 按管线映射文件：Orchestration 用 `src/physics/PhysicsEngine.ts`；Broad phase 用 `src/physics/gpu/broadPhase.ts`；Narrow phase 用 `src/physics/gpu/contactGeneration.ts`；Contact records 用 `src/physics/gpu/contactRecord.ts`；AVBD solve 用 `src/physics/gpu/avbdState.ts`；LBVH builder 用 `src/lvbh/GPULBVHBuilder.ts`。
11. 配置求解器参数：调用 `engine.step(dt, substeps, { gravity: [0, -9.81, 0], iterations: 10, restitutionThreshold: 1.0 })`。
12. 调稳：刚性堆叠或高速物体增加 `substeps`（如 20）；增加 `iterations` 改善约束收敛；静态体用 `mass: 0`；关节用较低 `stiffness` 更软更稳定；非弹跳堆叠用 `restitution: 0` 加高 `friction`。
13. 实现盒子堆叠：先添加地面 `mass: 0`、`halfExtents: [5, 0.25, 5]`、`friction: 0.7`、`restitution: 0.1`；再循环 8 次添加盒子，位置 `[0, 0.5 + i * 1.05, 0]`、`halfExtents: [0.5, 0.5, 0.5]`、`mass: 1.0`、`friction: 0.5`、`restitution: 0.1`。
14. 实现摆链：先添加静态起点；循环创建动态盒子并用 `addJoint` 距离关节连接前一个体；关节参数 `anchorA: [0, -0.15, 0]`、`anchorB: [0, 0.15, 0]`、`restLength: 0.7`、`stiffness: 1e5`；每轮更新 `prevIndex`。
15. 集成 Three.js：`import * as THREE from 'three'`；维护 `meshes` 数组；在 `syncPhysicsToRender` 中取 `engine.getBodyStates()`，对 `meshes[i]` 设置 `position.set(...state.position)` 和 `quaternion.set(state.rotation[0], state.rotation[1], state.rotation[2], state.rotation[3])`；在 `animate` 中调用 `engine.step(1 / 60, 10)`、同步、`renderer.render(scene, camera)`、`requestAnimationFrame(animate)`。
16. 排障 WebGPU 不可用：若 `navigator.gpu` 为 undefined，使用 Chrome 113+；旧版本在 `chrome://flags/#enable-unsafe-webgpu` 启用；Firefox/Safari 当前不支持。
17. 排障模拟爆炸/物体飞走：减小 timestep 或增加 `substeps`；降低关节 `stiffness`；确保静态体 `mass: 0`；检查 `halfExtents` 为正且非零。
18. 排障物体穿透地面：增加 `iterations`（试 15–20）；增加 `substeps`；检查碰撞形状尺寸与可视网格匹配。
19. 排障性能问题：项目仅 Chrome WebGPU，GPU 驱动问题可能造成变慢；减少 body count 或 iteration count；访问 `chrome://gpu` 确认硬件加速已开启。
20. 排障构建错误：确保 Node.js >= 18，运行 `node --version`；清理缓存 `rm -rf node_modules dist`；重新 `npm install` 和 `npm run build`。
21. 了解限制与路线图：Chrome only，无 Firefox/Safari；不是可直接 drop-in 的 npm 包，需 clone 后手动集成；双缓冲位置更新（同色冲突安全）尚未实现，当前使用 `avbdState.ts` 中的 in-place colored body solve；API 实验性，可能有破坏性变更；未导出外部 TypeScript 类型声明。
22. 查阅参考：Live Demo `https://jure.github.io/webphysics/`；AVBD Paper `https://graphics.cs.utah.edu/research/projects/avbd/Augmented_VBD-SIGGRAPH25.pdf`；WebGPU Spec `https://gpuweb.github.io/gpuweb/`。

适用边界 · 注意事项

• 需要 Firefox/Safari 或非 WebGPU 环境时不要使用；该项目仅支持 Chrome 113+ 且依赖 WebGPU。
• 生产项目、需要稳定 API、直接 npm 安装或外部 TypeScript 类型声明时不要使用；这是实验性 proof-of-concept，必须 clone 手动集成。
• 需要双缓冲位置更新（同色冲突安全）时不要使用；当前尚未实现，使用 in-place colored body solve。