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

3Dヒーローインタラクション

ヒーローセクションの3Dモデルを、ポインター追跡パララックス、ホバーグロー、クリック反応(衝撃、パーティクルバースト、モーフ)、ドラッグ回転、磁気ボタン、カスタムカーソルなどでユーザー操作に反応させます。

3Dヒーローインタラクション とは?

このスキルは、静的で反応のない3Dヒーローモデルに命を吹き込むための包括的なガイドです。ユーザーの操作に対して「生きている」と感じさせるための階層的なアプローチ(カーソル応答 > クリック応答 > アイドル動作)を提供します。具体的には、単一の正規化ベクトルを用いたフレームレート非依存のダンピング処理によるポインター追跡、インタラクティブメッシュのみを対象とした効率的なレイキャスティングによるホバー検出、クリック時の衝撃・スプリングキック・パーティクルバースト・モーフといった反応の実装、ドラッグ回転(慣性とイージング付き)、磁気ボタン、カスタムカーソルなどをカバーしています。Three.js上で動作し、特に`threejs-interaction`や`3d-physics-simulations`と組み合わせて使用することで、プロフェッショナルで没入感のあるインタラクティブなヒーロー体験を構築できます。また、パフォーマンス低下を防ぐためのベストプラクティス(フルシーンレイキャストの回避、タッチデバイスでのホバー処理の除外など)も詳しく説明されています。

対応~Claude Code~Codex CLI✓Cursor
Part ofReact
npx skills add https://github.com/BLACKNIGHT-cloud12/3d-hero-interactions/tree/HEAD

Installed? Explore more コーディング&開発 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

お気に入りのAIに質問する

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

ドキュメント

3Dヒーローインタラクション は何をしますか?

回転するだけのヒーローモデルはスクリーンセーバーです。「生きている」と感じさせる優先順位は、カーソルに応答する(ホバー) > 入力に応答する(クリック) > アイドル動作に応答する(アンビエントモーション) です。この順序で構築してください。

ポインター追跡:1つの正規化ベクトル、すべてにダンピング

ポインターを一度追跡し、すべての反応が同じNDCベクトルをダンピングフォロワーを通じて読み取ります。コンポーネントが独自のリスナーを追加することは絶対に避けてください。

const pointer = new THREE.Vector2(0, 0);     // 生の値、-1..1
const smooth = new THREE.Vector2(0, 0);      // ダンピング済み
addEventListener('pointermove', e => {
  pointer.set((e.clientX / innerWidth) * 2 - 1, -(e.clientY / innerHeight) * 2 + 1);
});unction tick(dt) {
  smooth.lerp(pointer, 1 - Math.pow(0.001, dt)); // フレームレート非依存のダンピング
}
  • パララックス:カメラ(またはシーングループ)を注視点を中心にsmooth * 0.3だけオフセットします。奥行き感が生まれ、3行のコードで実現できます。
  • 傾き:ヒーローメッシュをカーソル方向に角度制限(±0.15 rad)をつけて傾けます。「あなたを見ている」ように見えます。
  • ダンピング定数は〜0.001〜0.01:値が小さいほど重く、高級感があります。生の追跡は安っぽく見えます。

ホバー:限定リストにレイキャスト、カーソル状態を設定

レイキャストはヒーローのインタラクティブメッシュのみ(明示的な配列を渡す)とし、シーン全体に対しては決して行わないでください。pointermoveごとに20万トライアングルのレイキャストを行うと、ヒーローセクションのフレームレートが低下します。

raycaster.setFromCamera(pointer, camera);
const hit = raycaster.intersectObjects(interactives, false)[0];
canvas.style.cursor = hit ? 'pointer' : 'default';
// 進入/離脱時:emissiveIntensityまたはスケールをトゥイーン(1 → 1.04)、詳細は threejs-interaction 参照

pointerenter/leave の遷移には、即時切り替えではなくトゥイーン(〜150msかけてlerp)で反応します。タッチデバイスにはホバーがないため、タップはクリックとして扱い、ホバー状態は完全にスキップします。

クリック反応(楽しい階層)

意図に応じて選択 — クリック ⇒ そのオブジェクトのスクリプト化された応答:

  1. 衝撃(物理ボディあり):applyImpulse — 3d-physics-simulations参照。
  2. スプリングキック(物理エンジンなし):変位 + スプリングで休止位置に戻す(v += k*(rest - x); v *= damp)。最も堅牢なヒーローパターン。
  3. パーティクルバースト:ヒットポイントからN個のパーティクルを放射状速度+重力+フェードで放出。1つのInstancedMesh/Pointsプールを使用(再利用、新規確保は禁止)。テンプレート:3d-physics-simulations → references/gpgpu-particles.md。
  4. モーフ/アセンブリ:ブレンド値を進めるか、アセンブリアニメーションを再実行(GSAPでuniforms/モーフターゲット)。

クリック後16ms以内にフィードバックがないと、ユーザーは操作がつながっていないと感じます。clickの解決を待たずに、pointerdownで応答を開始します。

ドラッグ回転

ドラッグとクリックは、移動しきい値(5px)とポインターダウン時間で区別します。メッシュの親グループをダンピング速度で回転させ、解放時は慣性を与えた後、アイドル回転にイージングして戻します。ヒーローではOrbitControlsのような自由カメラは無効にしてください。構図を維持する必要があります。

磁気DOM要素

カーソルから約80px以内のボタンはカーソルに向かって移動し(6〜8pxに制限)、離脱時にはスナップバックします。3Dパララックスと組み合わせて平面を統一します。同じダンピングフォロワーをtransform: translate()に適用します。

カスタムカーソル

意味がある場合のみ(例:ヒーロー上で「グラブ」のヒントになる場合):小さなドット+後続リング、mix-blend-mode: difference、タッチデバイスでは非表示。カスタムカーソルがサイト独自のカーソルと競合するのは、ないより悪いです。ホバー状態でカスタムが必要であることが証明されるまで、ネイティブカーソルを表示したままにします。

よくある間違い

  • pointermoveごとにフルシーンにレイキャストする — メッシュを限定するか、フレームごとにスロットルします。
  • ホットリロード/ルート変更ごとにリスナーが追加される — 登録したのと同じ場所でクリーンアップします。
  • キャンバスのオーバーレイがDOMへのクリックを奪う:キャンバスがインタラクションサーフェスでない限りpointer-events: noneにします。DOMは独自のz-indexで上に浮かべます。
  • pointerdownのみのデバイスでホバー効果がちらつく — matchMedia('(hover: hover)')の背後にホバーコードをゲートします。
  • scroll-driven-3d-storyからのスクロール駆動カメラの上にパララックスを重ね、単一の所有者がいない — オフセットは1箇所(カメラリググループ)で追加します。そうしないとビート同士が競合します。

関連スキル

  • threejs-interaction — レイキャスター/コントロールの基礎
  • 3d-physics-simulations — 衝撃とバースト
  • scroll-driven-3d-story — これが接続するカメラの振り付け
  • ai-website-aesthetics — ヒーローがどのように見えるべきか

関連スキル