Community程式設計與開發github.com

3D物理模擬

在 three.js 網站中執行真實物理與模擬:剛體、重力、碰撞、布娃娃、布料、鏈條,以及使用 Rapier 或 cannon-es 的 GPU 粒子模擬。

3D物理模擬 是什麼?

這個技能讓開發者能夠在 three.js 場景中輕鬆整合真實物理模擬。它支援選擇物理引擎(預設為高效能、確定性高的 Rapier;或是在無法使用 WASM 時採用較慢但相容性佳的 cannon-es),並提供將物理狀態同步至 three.js 物件的核心連接模式。技能涵蓋了從基本剛體、碰撞與重力,到進階的點擊脈衝互動、大量物體實例化、效能預算管理,以及基於 GPU 的粒子系統(如煙霧或神經網路雲)。它也強調了常見的陷阱,例如忘記初始化 Rapier 的 WASM、不正確的狀態同步,或是使用可變時間步長導致的抖動。此技能最適合需要物體互相碰撞、堆疊或碎裂的場景,而對於僅需視覺上合理動作(如游標感應浮球)的簡易行銷頁面,則建議採用「假物理」替代方案,以節省效能。

相容平台~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(同步)僅適用於純 script 標籤。
  • 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 秒為單位進行步進,每影格最多執行 3 步(防止死亡螺旋)。
  • 對於平台或移動載具,使用運動學物體;每一影格呼叫 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(懸停狀態、爆發效果、磁性游標)

相關技能