immersive-3d-web

没入感のある3D Web

公式の公開ドキュメント（threejs.org/manual、threejs.org/docs、r3f.docs.pmnd.rs、drei.docs.pmnd.rs、gsap.com/docs）に基づいて厳選しています。学習データからの推測ではありません。ドキュメントをそのまま転載するのではなく、構造を抽出しています。メンタルモデル、判断基準、そして実際の制作で失敗につながる要因をまとめています。

これがある理由

プレミアムな3Dアセットのショーケース（大胆なヒーローの動き、スクロールに連動したカメラパス、製品品質のライティング）を備えたサイトは、十分に文書化された小規模なスタックで構築できます。難しいのはAPIを見つけることではなく、何かを実現する5つの方法のうち、ミドルレンジのスマートフォンでも60fpsを維持できる方法を見極めることです。このスキルでは、そうした判断をあらかじめ整理しています。

使い方

• 新しいヒーローシーンを作り始める場合 → まず reference/concept-to-form.md を読み、three-core.md より先に確認してください。 このスキルを使うと、サイトとの実際の関連性がまったくない、技術的には優れた3Dヒーローを簡単に作れてしまいます。画面中央に浮かぶ多面体は、時計ブランドでも、ボルダリングジムでも、SaaSダッシュボードでも、同じように「プレミアム」に見えます。まさにそれが問題です。ジオメトリのコードを書く前に、サイトが実際に扱う対象をもとに、オブジェクトの形や動きを決めてください。
• ゼロから構築する場合 → まず reference/three-core.md（メンタルモデル）を読み、Reactで作業する場合は次に reference/r3f-drei.md を読んでください。
• スクロールに連動する動きを追加する場合 → reference/gsap-scroll.md。
• シーンに多数の反復オブジェクト（パーティクル、群衆、データポイント）がある場合、または動作が遅い場合 → reference/performance.md。
• ヒーロー／ショーケースシーンを組み立てる場合や、よくある間違いがないか確認する場合 → reference/patterns-and-antipatterns.md。各要素の仕組みを理解してから読む、総括的な資料です。
• 既存サイトのスタイルを変更したり3Dを追加したりする場合（新規構築ではない場合） → まず reference/retrofit.md を読んでください。統合戦略、壊してはいけないもの、プラットフォーム固有の注意事項（例：GitHubリポジトリと同期されたLovable／vite_react_shadcn_tsプロジェクト）を扱っています。対象が既存のコードベースなら、ほかの資料より先に読んでください。
• 3Dそのものを作るのではなく、ヒーローセクションを演出する場合（背景動画／埋め込み3D、ガラス風カード、段階的な登場アニメーション、流動的なタイポグラフィなど） → reference/hero-dressing.md。背景がR3F、埋め込みSplineシーン、通常の動画のいずれでも使えます。これは3Dレイヤーではなく、その周囲のCSS／モーションレイヤーを扱います。
• サイトの残りの部分（ナビゲーションリンク、ボタン、カード）も仕上げて、ヒーローだけのデモではなく完成した製品に見せる場合 → reference/micro-interactions.md。ヒーローだけでなくサイト全体が対象です。ナビゲーションのアンダーラインアニメーション、ボタンのホバー／押下フィードバック、光沢のスイープ、傾きやカーソル追従を取り入れたカード、カードのホバー時の浮き上がり、そして個々の効果よりも全体の一貫性が重要な理由を扱っています。目を引くヒーローがあるかどうかにかかわらず、このスキルを使うあらゆる制作で、一度は確認する価値があります。
• 読み込み／選択済み／ロック状態、数値や進捗の表示、カスタムカーソル、ティッカーテープ、一度だけ再生するお祝いアニメーションを扱う場合 → reference/state-and-feedback.md。カーソルではなく「アプリケーションの状態」に結びついたフィードバックを扱います。完成状態しか表示しないデモと、あらゆる状態を正確に描画する必要がある実際の製品との違いがわかります。また、不透明な二重背景と mask-composite オーバーレイのどちらを使うか、グラデーションボーダーの2つの手法を選ぶための判断基準も含まれています。

中核となる考え方（最初に押さえ、必要に応じて reference/ で詳しく確認）

何よりもまず、形は慣習ではなく題材に合わせます。 icosahedronGeometry／torusGeometry／torusKnotGeometry は手軽で、いつでも高級感のある見た目にできます。だからこそ、このサイトの題材に本当に合っているかを考えずに選びがちです。concept-to-form.md を参照してください。

スタック： Three.js（WebGL エンジン）→ React Three Fiber / R3F（そのための宣言的な React レンダラーで、JSX は THREE.* コンストラクターに1対1で対応します）→ drei（照明リグ、ローダー、カメラコントロールなどの既成ヘルパー）→ GSAP ScrollTrigger（スクロールをカメラ／オブジェクトアニメーションの再生ヘッドとして扱います）。

Three.js の5つの基本要素： Scene（ツリー）、Camera（視点）、Renderer（キャンバスに描画）、Mesh = Geometry（形状）+ Material（表面）、Light（照明 — コストはライトごとに増加し、最も低コストなのは Ambient/Hemisphere → Directional → Point/Spot → RectArea です）。

最も重要なパフォーマンス上の判断： 画面上に多数のオブジェクトがある場合、作成後にそれぞれ独立して動きますか？ いいえ → Geometry をマージして1回のドローコールにまとめます。はい → THREE.InstancedMesh を使います。繰り返し表示するアイテムごとに Mesh を1つ作るのは避けてください。

スクロール連動3Dのパターン： GSAP の ScrollTrigger に scrub を指定すると、スクロール位置をアニメーションの再生ヘッド（self.progress、0→1）として扱えます。onUpdate で値を読み取り、R3F の useFrame 内でカメラ／オブジェクトのトランスフォームに適用します。Three.js オブジェクトのプロパティには、GSAP のデフォルトの DOM トゥイーンを使用しないでください。

補完的なスキル： 周囲のページのタイポグラフィ、色、レイアウト、非3D UI のアクセシビリティについては、frontend-design に引き継いでください。このスキルの範囲は「WebGL レイヤーをどう構築／最適化するか」までです。

情報源に関する注記

ドキュメントは直接取得しています（ファイルごとの出典行を参照）。R3F+GSAP のスクロールチュートリアルが404を返すなど、アクセスできないページがある場合、gsap-scroll.md／patterns-and-antipatterns.md のパターンは、検証済みの基本要素（ScrollTrigger の文書化された onUpdate／scrub、R3F の文書化された useFrame）を明示的に組み合わせたものです。引用例として提示しているわけではなく、その旨を明記しています。

reference/hero-dressing.md は、このスキルの他のファイルとは異なる方法で情報源を得ています。実際の本番環境向けプロンプトから要点をまとめており、その旨はファイル内に明記しています。

reference/micro-interactions.md と reference/state-and-feedback.md は、このスキルを使った実践的な構築／レビュー作業に加え、実際の2つの本番コードベース（稼働中の金融ダッシュボードと個人サイト）で個別に確認されたパターンを情報源としています。hero-dressing.md と同じ注意事項が当てはまります。

reference/concept-to-form.md は、このスキルを使って1回のセッションで行った4つの構築作業において、自分で観察したアンチパターンを情報源としています。利用者がそのパターンに直接名前を付けたものであり、ドキュメントや外部のコードベースに基づくものではありません。その旨はファイル内に明記しています。