Communitygithub.com

スクロール駆動3Dストーリーテリング

ページスクロールに連動して3Dシーンを演出します。カメラの動き、セクションごとのシーン展開、固定ヒーロー、スムーズスクロール、スクロール進行度に基づくシェーダー/アニメーションを実現します。

スクロール駆動3Dストーリーテリング とは?

このスキルは、ページスクロールに合わせて3Dシーンを物語のように進行させるためのアーキテクチャを提供します。固定されたCanvasを背景に配置し、スクロール位置を「進行度」に変換して3Dシーンの状態を制御します。主な機能として、スクロール範囲ごとにカメラ位置やモデルの状態を定義するストーリーボードの設計、Lenisを用いたアクセシブルなスムーズスクロール、CatmullRomCurve3による滑らかなカメラパス、DOM要素と3Dシーンの同期、パフォーマンス最適化(DPR制限、タブ非表示時のレンダリング停止)、アクセシビリティ(prefers-reduced-motion対応、WebGLフォールバック)などを含みます。Three.js、GSAP、Lenisなどのライブラリと組み合わせて使用し、高品質なスクロール連動型Webサイトを構築するためのベストプラクティスをまとめています。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/BLACKNIGHT-cloud12/scroll-driven-3d-story/tree/HEAD

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

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

ドキュメント

スクロール駆動3Dストーリーテリング は何をしますか?

トップクラスのAIウェブサイトの特徴:ページをスクロールすると、3Dシーンが物語を語る — カメラが滑らかに動き、モデルが組み上がり、パーティクルが再形成される。このスキルがそのためのアーキテクチャです。

アーキテクチャ: 1つの固定キャンバス、スクロールが数値を駆動する

キャンバスはDOMの背後に position: fixed で配置されます。スクロールはキャンバスを移動させず、シーンが補間する進行値を駆動します。その他はすべて実装の詳細です。

// DOMは通常通りスクロール。読み取りのみで、ハイジャックしない。
let scrollProgress = 0;
addEventListener('scroll', () => {
  scrollProgress = scrollY / (document.body.scrollHeight - innerHeight);
}, { passive: true });

RAFループ内で、scrollProgress からシーンの状態を補間します。これが全てです。ストーリーボード(以下)を作成し、ビートごとに補間関数を書きます。

ストーリーボード(常に最初に作成する)

コードを書く前に、スクロール範囲とシーンの状態をコメントまたはテーブルでマッピングします。

0.00–0.15  ヒーロー:    モデルが中央に浮遊、ゆっくり回転、カメラ z=8
0.15–0.35  機能紹介:   カメラが x=-4 にドリー、モデルが3つに分割
0.35–0.60  技術説明:   カメラが90°周回、パーティクルが集結、ワイヤーフレームオーバーレイがフェードイン
0.60–0.80  証拠提示:  カメラが後退、シーンが暗くなり、DOMカードがキャンバス上にフェード
0.80–1.00  CTA:       モデルが中央で再結合、グローが広がり、カメラ z=5

各ビートを (開始, 終了, apply(t)) のペアとして実装します。進行度を各範囲にクランプし、適用前に t をイージングします。カメラ位置、回転、uniform値をキーフレーム間で補間します。意図的にスナップさせる場合を除き、ビートの途中でテレポートさせないでください。

スムーズスクロール: Lenis、スクロールハイジャックはしない

慣性スクロールにはLenisを使用します。ネイティブスクロールを駆動するためアクセシビリティは維持されます。

const lenis = new Lenis({ lerp: 0.1 });
function raf(time) { lenis.raf(time); update3D(); requestAnimationFrame(raf); }
requestAnimationFrame(raf);
  • ネイティブスクロールをブロックしない(overflow: hidden をbodyに設定しない)— キーボード/モバイルユーザーとSEOを損なうため。
  • GSAP ScrollTriggerを手動進行の代わりに使用する場合も、キャンバスは固定したままシーンの状態を駆動し、ScrollTriggerにキャンバスを変換させないでください。

カメラパス

複数ビートの移動には、キーフレーム位置を通る THREE.CatmullRomCurve3 を定義し、イージングされた進行度でサンプリングします。これは点のペアをlerpするよりも滑らかです。注視点にも独自のカーブを設定します。イージング/カーブの詳細については threejs-animation スキルを参照してください。

DOM + 3D 同期

  • セクションテキストは通常のDOMです。mix-blend-mode または半透明パネルをキャンバス上に配置します。
  • セクションの表示をシーンのビートと同期させます。同じ scrollProgress 範囲からDOMアニメーション(GSAPまたはCSS)をトリガーします。1つの真実の情報源とします。
  • 3Dラベルを画面空間にアンカーするには、毎フレームワールド座標を投影します。カメラの背後にあるときは非表示にします。

パフォーマンスとモバイル

  • キャンバスのDPRは1〜2に制限します。スクロール連動シーンはスクロールに関係なく毎フレーム再レンダリングされるため、他のフレームごとの処理は削減します。
  • タブやシーンが画面外にある場合、RAFレンダリングを一時停止します(document.visibilityState、セクションのIntersectionObserver)。
  • モバイル:ビート数を減らし(スクロール長は変えない)、パーティクル数を減らし、ポストプロセッシングを無効にします(threejs-performanceおよびthreejs-postprocessingスキルを参照)。
  • iOS Safari:アドレスバーのリサイズによりスクロール中に innerHeight が変化します。リサイズをデバウンスし、ビートが跳ねる場合は visualViewport を考慮した高さを使用して進行度を計算します。

アクセシビリティとフォールバック

  • prefers-reduced-motion を尊重します。最終的な組み立て状態を静的なシーンとしてレンダリングし、カメラの動きをスキップします。スクロールは通常通りに動作します。
  • 3Dオフのフォールバック(GPUが弱い / failsIf):グラデーション背景と同一のDOMストーリー。ストーリーはWebGLがなくても成立する必要があります。

よくある間違い

  • スクロールイベントやホイールをハイジャックする — 「プレミアム」サイトが壊れているように感じる最も多い原因。
  • 毎フレーム scrollHeight を読み取る(レイアウトスラッシュ)— リサイズ時にキャッシュする。
  • 生の線形進行度をカメラ移動に適用する — 必ずイージング(スローインアウト)しないと、機械的に感じられる。
  • 多数のScrollTriggerが同じシーンプロパティを変更する — 競合するため、全てを1つの進行値でルーティングする。
  • ループ内で lenis.raf(time) を忘れるとスクロールが死んでいるように感じる。

関連スキル

  • threejs-animation — イージング、カーブ、モーフィング
  • ai-website-aesthetics — ビートの見た目
  • threejs-postprocessing — ビート間のブルームランプ
  • 3d-hero-interactions — ヒーロービートのクリック/ホバー動作

関連スキル