Community编程与开发github.com

3D物理模拟

在three.js网站中运行真实的物理和模拟:刚体、重力、碰撞、布娃娃、布料、链式结构和GPU粒子模拟,使用Rapier或cannon-es引擎。

3D物理模拟 是什么?

该技能为开发者提供了在three.js中集成物理模拟的完整指导,涵盖引擎选择(推荐Rapier,备选cannon-es)、核心同步模式、点击施力交互、大批量物体性能优化以及假物理效果决策。支持Rapier的WASM加速确定性物理模拟,用于碰撞、堆叠、破碎等真实交互;同时提供GPU粒子模拟实现数千粒子的烟雾、星群等视觉效果。强调固定时间步长、实例化网格和休眠机制以维持60fps性能。适用于营销页面、英雄区交互和游戏场景。

兼容平台~Claude Code~Codex CLI✓Cursor
Part ofReact
npx skills add https://github.com/BLACKNIGHT-cloud12/3d-physics-simulations/tree/HEAD

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

3D物理与模拟

让3D场景动起来:物体下坠、堆叠、破碎,并通过逼真的质量感对点击做出反应。本技能涵盖引擎选择、与three.js的集成、保持60fps性能,以及英雄区域常用的点击-冲击模式。

选择引擎

  • Rapier(@dimforge/rapier3d-compat)—— 默认选项。基于WASM,确定性模拟,积极维护,性能最佳。对于打包工具使用rapier3d-compat(异步WASM初始化);仅对于纯脚本标签使用rapier3d(同步)。
  • cannon-es —— 仅在必须避免WASM加载时使用(如file://演示、严格CSP)。速度较慢且维护较少。
  • GPGPU/FBO粒子 —— 用于烟雾、群组、“AI神经”粒子云(数千个以上)。非物理引擎;请参见下方的GPU部分。

在创建任何物体前加载Rapier:

import RAPIER from '@dimforge/rapier3d-compat';
await RAPIER.init(); // 仅需一次,在世界创建之前
const world = new RAPIER.World({ x: 0, y: -9.81, z: 0 });

核心集成模式 (three.js + Rapier)

物理引擎拥有状态;three.js仅渲染它。切勿移动带有物理体的网格——每帧从物理体读取位置并赋值给网格。

// 1. 先创建物理体
const bodyDesc = RAPIER.RigidBodyDesc.dynamic().setTranslation(0, 5, 0);
const body = world.createRigidBody(bodyDesc);
const colliderDesc = RAPIER.ColliderDesc.cuboid(0.5, 0.5, 0.5).setRestitution(0.4);
world.createCollider(colliderDesc, body);

// 2. 渲染循环 — 同步,而不是设置
function tick(dt) {
  world.timestep = dt;
  world.step();
  mesh.position.copy(body.translation());
  mesh.quaternion.copy(body.rotation());
}
  • 使用固定时间步长以确保稳定性:累积dt,按1/60秒的步长执行,每帧最多三步(死循环保护)。
  • 平台/移动物体使用运动学体;每帧调用setNextKinematicTranslation()。
  • 碰撞体不会继承网格缩放——需显式在世界单位为它们指定大小。

点击-冲击模式(英雄区)

通过射线投射鼠标指针,找到光标下方的物理体,并施加冲击力。这是顶级AI网站上常见的“戳英雄物体”交互。关于光线投射器的详情请参见threejs-interaction技能。

raycaster.setFromCamera(pointerNDC, camera);
const hit = world.castRay(new RAPIER.Ray(origin, dir), 100, true, undefined, undefined, undefined, filterPredicate);
if (hit) {
  const body = world.getCollider(hit.colliderHandle).parent();
  const dir3 = rayDir.clone().multiplyScalar(6); // 冲击力强度
  body.applyImpulse({ x: dir3.x, y: dir3.y, z: dir3.z }, true);
}

为可点击的物体设置轻微的角度阻尼(setAngularDamping(0.5)),使它们的旋转更逼真,而不是永远旋转不停。

大量物体:实例化、预算、休眠

  • 每种几何体使用一个THREE.InstancedMesh;在world.step()之后将物理体的变换写入实例矩阵。超过约50个物体后,绝对不要为每个物体使用一个单独的网格。
  • 预算:桌面端约200个动态盒子/碰撞体尚可;移动端约80个。低于此预算时,使用假物理(见下方“假物理”部分)。
  • 让物体休眠(默认行为),仅在交互时唤醒它们。场景中从不休眠的物体会白白消耗CPU。
  • 碰撞体使用简单几何体(盒子/球体/胶囊);仅在物体轮廓重要时使用凸包或复合网格。

假物理(先做这个决定)

大多数营销网站不需要物理引擎。问问自己:这个效果需要碰撞,还是只需要看起来像在动?

  • 对光标产生反应的浮动球体 → 使用弹簧/阻尼数学,无需引擎。
  • 点击散落的3D形状五彩纸屑 → 在单个着色器或循环中采用预计算速度加重力积分,无需引擎。
  • 可拖拽的英雄模型并弹回原位 → 使用弹簧趋向静态姿势(参见3d-hero-interactions技能)。 仅当物体需要碰撞、相互堆叠或堆积时,才使用Rapier。

GPU粒子模拟

用于神经网络云、星空、烟雾等效果——通过乒乓渲染目标(状态纹理)在GPU上更新数千个粒子。详细信息和可用的模板:请阅读references/gpgpu-particles.md。

常见错误

  • 忘记await RAPIER.init() → 导致神秘的WASM错误。
  • 同时设置mesh.position并让物理体驱动它——物理体占主导,网格会瞬移。移动物体,回读网格。
  • 帧与帧之间使用可变时间步长 → 导致堆叠抖动和隧穿。使用固定时间步长加累积器。
  • 在碰撞事件中添加渲染循环工作——将效果放入队列,在step()之后应用。
  • 使用three.js场景的光线投射进行物理拾取,而不是使用world.castRay(反之亦然)——在拥有对象的物理世界中进行拾取。
  • 页面切换时未恢复世界状态(R3F卸载会导致WASM物体泄漏;应销毁世界)。

相关技能

  • threejs-fundamentals — 场景、渲染器、循环
  • threejs-interaction — 光线投射与指针拾取
  • threejs-performance — 实例化与预算
  • 3d-hero-interactions — 上层UX层(悬停状态、爆裂效果、磁吸光标)

相关技能