Communityコーディング&開発github.com

3D物理シミュレーション

three.js のウェブサイト内で、剛体、重力、衝突、ラグドール、布、チェーン、GPUパーティクルなどのリアルな物理シミュレーションを実行します。

3D物理シミュレーション とは?

このスキルは、three.js ベースのWebサイトやアプリケーションに、本格的な物理シミュレーションを組み込むための包括的なガイドを提供します。Rapier(推奨)とcannon-esの2つの主要な物理エンジンの選択基準、導入方法、およびthree.jsとの連携パターンを詳細に解説しています。物理エンジンが状態を管理し、three.jsはレンダリングのみを行うという「状態主導」のアーキテクチャを推奨し、固定タイムステップによる安定したシミュレーション、クリックによるインパルス付与(ヒーローセクションのインタラクション)、多数のボディのインスタンス化によるパフォーマンス最適化、不要な演算を避けるスリープ機能の活用など、実践的なテクニックを網羅しています。さらに、本格的な物理エンジンが不要な場合の「フェイク物理」の判断基準や、数千のパーティクルを扱うGPUシミュレーションについても触れており、開発者はプロジェクトの要件に応じて適切なアプローチを選択できます。関連スキル(threejs-fundamentals, threejs-interaction, threejs-performance, 3d-hero-interactions)と組み合わせることで、印象的な3Dインタラクティブ体験を構築できます。

対応~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に質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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(); // ワールド作成前に1回だけ必要
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))、永遠に回転し続けるのではなく、信頼できるスピンにすることを推奨します。

多数のボディ:インスタンス化、予算、スリープ

  • ジオメトリごとに1つの THREE.InstancedMesh を使用。world.step() の後にボディのトランスフォームをインスタンス行列に書き込みます。約50オブジェクトを超えたら、ボディごとに1つのメッシュは避けます。
  • 予算:デスクトップで約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レイヤー(ホバー状態、バースト、マグネットカーソル)

関連スキル