Web 3D インテグレーションパターン

概要

このメタスキルは、Webアプリケーションで複数の3Dおよびアニメーションライブラリを組み合わせるためのアーキテクチャパターン、ベストプラクティス、インテグレーション戦略を提供します。threejs-webgl、gsap-scrolltrigger、react-three-fiber、motion-framer、react-spring-physicsスキルの知識を統合して、複雑で高性能な3D Webエクスペリエンスを構築するための一貫したパターンを提供します。

このスキルを使用する場合：

• 複数のライブラリを組み合わせた複雑な3Dアプリケーション構築
• アニメーション調整を伴うスクロール駆動型3Dエクスペリエンス作成
• 3Dシーンを使用した物理ベースのインタラクション実装
• 3DレンダリングとUI アニメーション間での状態管理
• マルチライブラリアーキテクチャでのパフォーマンス最適化
• 3Dアプリケーション用の再利用可能なコンポーネントアーキテクチャ設計
• アニメーションアプローチ間のマイグレーション、または組み合わせ

コアインテグレーション組み合わせ：

1. Three.js + GSAP - スクロール駆動型3Dアニメーション、タイムライン調整
2. React Three Fiber + Motion - 状態ベースの3D と宣言的アニメーション
3. React Three Fiber + GSAP - React 内での複雑な3Dシーケンス
4. React Three Fiber + React Spring - 物理ベースの3Dインタラクション
5. Three.js + GSAP + React - ハイブリッド命令型/宣言型3D

アーキテクチャパターン

パターン1: レイヤード分離（Three.js + GSAP + React UI）

ユースケース： オーバーレイUIと3Dシーン、スクロール駆動アニメーション

アーキテクチャ：

├── 3D レイヤー（Three.js）
│   ├── シーン管理
│   ├── カメラコントロール
│   └── レンダーループ
├── アニメーション レイヤー（GSAP）
│   ├── 3D プロパティ用 ScrollTrigger
│   ├── シーケンス用タイムライン
│   └── UI トランジション
└── UI レイヤー（React + Motion）
    ├── HTML オーバーレイ
    ├── 状態管理
    └── ユーザーインタラクション

実装：

// App.jsx - React ルート
import { useEffect, useRef } from 'react'
import { initThreeScene } from './three/scene'
import { initScrollAnimations } from './animations/scroll'
import { motion } from 'framer-motion'

function App() {
  const canvasRef = useRef()
  const sceneRef = useRef()

  useEffect(() => {
    // Three.js シーン初期化
    sceneRef.current = initThreeScene(canvasRef.current)

    // GSAP ScrollTrigger アニメーション初期化
    initScrollAnimations(sceneRef.current)

    // クリーンアップ
    return () => {
      sceneRef.current.dispose()
    }
  }, [])

  return (
    <div className="app">
      <canvas ref={canvasRef} />

      <motion.div
        className="overlay"
        initial={{ opacity: 0 }}
        animate={{ opacity: 1 }}
      >
        <section className="hero">
          <h1>3D Experience</h1>
        </section>
        <section className="content">
          {/* スクロール可能なコンテンツ */}
        </section>
      </motion.div>
    </div>
  )
}

// three/scene.js - Three.js セットアップ
import * as THREE from 'three'
import { OrbitControls } from 'three/addons/controls/OrbitControls.js'

export function initThreeScene(canvas) {
  const scene = new THREE.Scene()
  const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000)
  const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true })

  renderer.setSize(window.innerWidth, window.innerHeight)
  renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2))

  const controls = new OrbitControls(camera, canvas)
  controls.enableDamping = true

  // シーンオブジェクト設定
  const geometry = new THREE.BoxGeometry(2, 2, 2)
  const material = new THREE.MeshStandardMaterial({ color: 0x00ff00 })
  const cube = new THREE.Mesh(geometry, material)
  scene.add(cube)

  // ライティング
  const ambientLight = new THREE.AmbientLight(0xffffff, 0.5)
  scene.add(ambientLight)

  const directionalLight = new THREE.DirectionalLight(0xffffff, 1)
  directionalLight.position.set(5, 10, 7.5)
  scene.add(directionalLight)

  camera.position.set(0, 2, 5)

  // アニメーションループ
  function animate() {
    requestAnimationFrame(animate)
    controls.update()
    renderer.render(scene, camera)
  }
  animate()

  // リサイズハンドラー
  window.addEventListener('resize', () => {
    camera.aspect = window.innerWidth / window.innerHeight
    camera.updateProjectionMatrix()
    renderer.setSize(window.innerWidth, window.innerHeight)
  })

  return { scene, camera, renderer, cube }
}

// animations/scroll.js - GSAP ScrollTrigger インテグレーション
import gsap from 'gsap'
import { ScrollTrigger } from 'gsap/ScrollTrigger'

gsap.registerPlugin(ScrollTrigger)

export function initScrollAnimations(sceneRefs) {
  const { camera, cube } = sceneRefs

  // スクロール時のカメラアニメーション
  gsap.to(camera.position, {
    x: 5,
    y: 3,
    z: 10,
    scrollTrigger: {
      trigger: '.content',
      start: 'top top',
      end: 'bottom center',
      scrub: 1,
      onUpdate: () => camera.lookAt(cube.position)
    }
  })

  // メッシュ回転アニメーション
  gsap.to(cube.rotation, {
    y: Math.PI * 2,
    x: Math.PI,
    scrollTrigger: {
      trigger: '.content',
      start: 'top bottom',
      end: 'bottom top',
      scrub: true
    }
  })

  // マテリアルプロパティアニメーション
  gsap.to(cube.material, {
    opacity: 0.3,
    scrollTrigger: {
      trigger: '.content',
      start: 'top center',
      end: 'center center',
      scrub: 1
    }
  })
}

メリット：

• 関心の明確な分離
• データフローが容易に理解可能
• レイヤーごとのパフォーマンス最適化
• レイヤーの独立したテスト

トレードオフ：

• より多くのボイラープレートコード
• レイヤー間の手動同期
• 状態管理の複雑性

---

パターン2: 統合 React コンポーネント（React Three Fiber + Motion）

ユースケース： React ファーストアーキテクチャと宣言的3Dおよびアニメーション

アーキテクチャ：

React コンポーネントツリー
├── <Canvas>（R3F）
│   ├── 3D シーンコンポーネント
│   ├── ライト
│   ├── カメラ
│   └── エフェクト
└── <motion.div>（UI オーバーレイ）
    ├── HTML コンテンツ
    └── アニメーション

実装：

// App.jsx - 統合 React アプローチ
import { Canvas } from '@react-three/fiber'
import { Suspense } from 'react'
import { motion } from 'framer-motion'
import { Scene } from './components/Scene'
import { Loader } from './components/Loader'

function App() {
  return (
    <div className="app">
      <Canvas
        camera={{ position: [0, 2, 5], fov: 75 }}
        dpr={[1, 2]}
        shadows
      >
        <Suspense fallback={<Loader />}>
          <Scene />
        </Suspense>
      </Canvas>

      <motion.div
        className="ui-overlay"
        initial={{ opacity: 0 }}
        animate={{ opacity: 1 }}
        transition={{ duration: 1 }}
      >
        <h1>React-First 3D Experience</h1>
      </motion.div>
    </div>
  )
}

// components/Scene.jsx - R3F シーン
import { useRef, useState } from 'react'
import { useFrame } from '@react-three/fiber'
import { OrbitControls, Environment } from '@react-three/drei'
import { motion } from 'framer-motion-3d'

export function Scene() {
  return (
    <>
      <ambientLight intensity={0.5} />
      <directionalLight position={[5, 10, 7.5]} castShadow />

      <AnimatedCube />
      <Floor />

      <OrbitControls enableDamping dampingFactor={0.05} />
      <Environment preset="sunset" />
    </>
  )
}

function AnimatedCube() {
  const [hovered, setHovered] = useState(false)
  const [active, setActive] = useState(false)

  return (
    <motion.mesh
      scale={active ? 1.5 : 1}
      onClick={() => setActive(!active)}
      onPointerOver={() => setHovered(true)}
      onPointerOut={() => setHovered(false)}
      animate={{
        rotateY: hovered ? Math.PI * 2 : 0
      }}
      transition={{ type: 'spring', stiffness: 200, damping: 20 }}
    >
      <boxGeometry args={[2, 2, 2]} />
      <meshStandardMaterial color={hovered ? 'hotpink' : 'orange'} />
    </motion.mesh>
  )
}

function Floor() {
  return (
    <mesh rotation={[-Math.PI / 2, 0, 0]} position={[0, -1, 0]} receiveShadow>
      <planeGeometry args={[100, 100]} />
      <meshStandardMaterial color="#222" />
    </mesh>
  )
}

メリット：

• 宣言的でReact ファーストのアプローチ
• 統合された状態管理
• コンポーネントの再利用性
• React ツールでの簡単なテスト

トレードオフ：

• R3F の学習曲線
• レンダーループの制御性の低下
• 潜在的なReact 再レンダリングの問題

---

パターン3: ハイブリッドアプローチ（R3F + GSAP タイムライン）

ユースケース： React 状態管理を備えた複雑なアニメーションシーケンス

実装：

// components/AnimatedScene.jsx
import { useRef, useEffect } from 'react'
import { useFrame } from '@react-three/fiber'
import gsap from 'gsap'

export function AnimatedScene() {
  const groupRef = useRef()
  const timelineRef = useRef()

  useEffect(() => {
    // 複雑なシーケンス用GSAP タイムライン作成
    const tl = gsap.timeline({ repeat: -1, yoyo: true })

    tl.to(groupRef.current.position, {
      y: 2,
      duration: 1,
      ease: 'power2.inOut'
    })
    .to(groupRef.current.rotation, {
      y: Math.PI * 2,
      duration: 2,
      ease: 'none'
    }, 0) // 同時に開始

    timelineRef.current = tl

    return () => tl.kill()
  }, [])

  return (
    <group ref={groupRef}>
      <mesh>
        <boxGeometry />
        <meshStandardMaterial color="cyan" />
      </mesh>
    </group>
  )
}

---

パターン4: 物理ベース3D（R3F + React Spring）

ユースケース： 自然な物理駆動型3Dインタラクション

実装：

// components/PhysicsCube.jsx
import { useRef } from 'react'
import { useFrame } from '@react-three/fiber'
import { useSpring, animated, config } from '@react-spring/three'

const AnimatedMesh = animated('mesh')

export function PhysicsCube() {
  const [springs, api] = useSpring(() => ({
    scale: 1,
    position: [0, 0, 0],
    config: config.wobbly
  }), [])

  const handleClick = () => {
    api.start({
      scale: 1.5,
      position: [0, 2, 0]
    })

    // 遅延後にオリジナル状態に戻す
    setTimeout(() => {
      api.start({
        scale: 1,
        position: [0, 0, 0]
      })
    }, 1000)
  }

  return (
    <AnimatedMesh
      scale={springs.scale}
      position={springs.position}
      onClick={handleClick}
    >
      <boxGeometry />
      <meshStandardMaterial color="orange" />
    </AnimatedMesh>
  )
}

---

一般的なインテグレーションパターン

1. スクロール駆動型カメラ移動

Three.js + GSAP：

import gsap from 'gsap'
import { ScrollTrigger } from 'gsap/ScrollTrigger'

gsap.registerPlugin(ScrollTrigger)

// 複数の点を通るなめらかなカメラパス
const cameraPath = [
  { x: 0, y: 2, z: 5, lookAt: { x: 0, y: 0, z: 0 } },
  { x: 5, y: 3, z: 10, lookAt: { x: 0, y: 0, z: 0 } },
  { x: -3, y: 1, z: 8, lookAt: { x: 0, y: 0, z: 0 } }
]

const tl = gsap.timeline({
  scrollTrigger: {
    trigger: '#container',
    start: 'top top',
    end: 'bottom bottom',
    scrub: 1,
    pin: true
  }
})

cameraPath.forEach((point, i) => {
  tl.to(camera.position, {
    x: point.x,
    y: point.y,
    z: point.z,
    duration: 1,
    onUpdate: () => camera.lookAt(point.lookAt.x, point.lookAt.y, point.lookAt.z)
  }, i)
})

R3F + ScrollControls（Drei）：

import { ScrollControls, Scroll, useScroll } from '@react-three/drei'
import { useFrame } from '@react-three/fiber'

function CameraRig() {
  const scroll = useScroll()

  useFrame((state) => {
    const offset = scroll.offset

    state.camera.position.x = Math.sin(offset * Math.PI * 2) * 5
    state.camera.position.z = Math.cos(offset * Math.PI * 2) * 5
    state.camera.lookAt(0, 0, 0)
  })

  return null
}

export function App() {
  return (
    <Canvas>
      <ScrollControls pages={3} damping={0.5}>
        <CameraRig />
        <Scroll>
          <Scene />
        </Scroll>
      </ScrollControls>
    </Canvas>
  )
}

2. ジェスチャー駆動型3D 操作

R3F + Motion（Framer Motion 3D）：

import { motion } from 'framer-motion-3d'

function DraggableObject() {
  return (
    <motion.mesh
      drag
      dragElastic={0.1}
      dragConstraints={{ left: -5, right: 5, top: 5, bottom: -5 }}
      whileHover={{ scale: 1.1 }}
      whileTap={{ scale: 0.9 }}
      animate={{
        rotateY: [0, Math.PI * 2],
        transition: { repeat: Infinity, duration: 4, ease: 'linear' }
      }}
    >
      <sphereGeometry args={[1, 32, 32]} />
      <meshStandardMaterial color="hotpink" />
    </motion.mesh>
  )
}

3. 状態同期アニメーション

R3F + Zustand + GSAP：

// store.js
import create from 'zustand'

export const useStore = create((set) => ({
  selectedObject: null,
  cameraMode: 'orbit',
  setSelectedObject: (obj) => set({ selectedObject: obj }),
  setCameraMode: (mode) => set({ cameraMode: mode })
}))

// components/InteractiveObject.jsx
import { useRef, useEffect } from 'react'
import { useStore } from '../store'
import gsap from 'gsap'

export function InteractiveObject({ id }) {
  const meshRef = useRef()
  const selectedObject = useStore((state) => state.selectedObject)
  const setSelectedObject = useStore((state) => state.setSelectedObject)

  const isSelected = selectedObject === id

  useEffect(() => {
    if (isSelected) {
      gsap.to(meshRef.current.scale, {
        x: 1.2,
        y: 1.2,
        z: 1.2,
        duration: 0.3,
        ease: 'back.out'
      })
      gsap.to(meshRef.current.material, {
        emissiveIntensity: 0.5,
        duration: 0.3
      })
    } else {
      gsap.to(meshRef.current.scale, {
        x: 1,
        y: 1,
        z: 1,
        duration: 0.3,
        ease: 'power2.inOut'
      })
      gsap.to(meshRef.current.material, {
        emissiveIntensity: 0,
        duration: 0.3
      })
    }
  }, [isSelected])

  return (
    <mesh
      ref={meshRef}
      onClick={() => setSelectedObject(isSelected ? null : id)}
    >
      <boxGeometry />
      <meshStandardMaterial color="cyan" emissive="cyan" />
    </mesh>
  )
}

---

状態管理戦略

1. グローバル3D 状態向けZustand

最適用途： 3DシーンとUI 間での共有状態

// store/scene.js
import create from 'zustand'

export const useSceneStore = create((set, get) => ({
  // 状態
  camera: { position: [0, 2, 5], target: [0, 0, 0] },
  objects: {},
  selectedId: null,
  isAnimating: false,

  // アクション
  updateCamera: (updates) => set((state) => ({
    camera: { ...state.camera, ...updates }
  })),

  addObject: (id, object) => set((state) => ({
    objects: { ...state.objects, [id]: object }
  })),

  selectObject: (id) => set({ selectedId: id }),

  setAnimating: (isAnimating) => set({ isAnimating })
}))

R3F での使用：

import { useSceneStore } from '../store/scene'

function Object3D({ id }) {
  const selectedId = useSceneStore((state) => state.selectedId)
  const selectObject = useSceneStore((state) => state.selectObject)

  const isSelected = selectedId === id

  return (
    <mesh onClick={() => selectObject(id)}>
      <boxGeometry />
      <meshStandardMaterial color={isSelected ? 'hotpink' : 'orange'} />
    </mesh>
  )
}

---

パフォーマンス最適化

クロスライブラリパフォーマンスパターン

1. レンダーループ最適化

Three.js とアニメーションライブラリ間のレンダーループを調整：

// 条件付きレンダリングを備えた統合レンダーループ
import { Clock } from 'three'

const clock = new Clock()
let needsRender = true

function animate() {
  requestAnimationFrame(animate)

  const delta = clock.getDelta()
  const elapsed = clock.getElapsedTime()

  // 必要な場合のみレンダリング
  if (needsRender || controls.enabled) {
    // GSAP アニメーション更新（自動的に処理）

    // Three.js を更新
    controls.update()
    renderer.render(scene, camera)

    // フラグをリセット
    needsRender = false
  }
}

// インタラクションでレンダリングを再実行
ScrollTrigger.addEventListener('update', () => {
  needsRender = true
})

2. オンデマンドレンダリング（R3F）

import { Canvas } from '@react-three/fiber'

function App() {
  return (
    <Canvas
      frameloop="demand" // 必要な場合のみレンダリング
      dpr={[1, 2]} // 適応型ピクセル比
    >
      <Scene />
    </Canvas>
  )
}

function Scene() {
  const invalidate = useThree((state) => state.invalidate)

  // 状態変更時にレンダリングを実行
  const handleClick = () => {
    // 状態を更新...
    invalidate() // 手動でレンダリングを実行
  }

  return <mesh onClick={handleClick}>...</mesh>
}

---

よくある落とし穴

1. アニメーション競合

問題： 複数のライブラリが同じプロパティをアニメートしようとする

// ❌ 間違い：GSAP と React Spring の両方がポジションをアニメート
gsap.to(meshRef.current.position, { x: 5 })
api.start({ position: [10, 0, 0] }) // 競合！

解決： ライブラリを選択するか、タイミングを調整

// ✅ 正しい：プロパティを分離
gsap.to(meshRef.current.position, { x: 5 }) // GSAP がポジションを処理
api.start({ scale: 1.5 }) // Spring がスケールを処理

2. 状態同期の問題

問題： React 状態がThree.js シーンと同期していない

// ❌ 間違い：React 状態を更新せずにThree.js を更新
mesh.position.x = 5 // Three.js は更新されたが
// React 状態は古い値のままであることに注意！

解決： refs または状態管理を使用

// ✅ 正しい：両方を更新
const updatePosition = (x) => {
  mesh.position.x = x
  setPosition(x) // React 状態も更新
}

3. 未処理のアニメーションからのメモリリーク

問題： アンマウント時にアニメーションをクリーンアップしていない

// ❌ 間違い：クリーンアップなし
useEffect(() => {
  gsap.to(meshRef.current.rotation, { y: Math.PI * 2, repeat: -1 })
}, [])

解決： 常に useEffect の戻り値でクリーンアップ

// ✅ 正しい：アンマウント時にクリーンアップ
useEffect(() => {
  const tween = gsap.to(meshRef.current.rotation, { y: Math.PI * 2, repeat: -1 })

  return () => {
    tween.kill()
  }
}, [])

---

決定マトリックス

どの組み合わせをいつ使うか

ユースケース	推奨スタック	根拠
スクロール駆動型3D のマーケティングランディングページ	Three.js + GSAP + React UI	GSAP はスクロール調整に優れている
インタラクティブな3D 製品ビューアーを備えた React アプリ	R3F + Motion	宣言的、状態駆動、コンポーネント ベース
複雑なアニメーションシーケンス（タイムラインベース）	R3F + GSAP	GSAP タイムライン制御と R3F コンポーネント
物理ベースのインタラクション（ドラッグ、モーメンタム）	R3F + React Spring	Spring 物理はジェスチャーに自然な感じ
高性能パーティクルシステム	Three.js + GSAP	命令型制御、インスタンシング、最小オーバーヘッド
迅速なプロトタイピング、高速反復	R3F + Drei + Motion	高レベルな抽象化、高速開発
ゲームのようなエクスペリエンス（物理）	R3F + React Spring + Cannon（物理）	物理エンジン + spring ベースUI フィードバック

---

リソース

このスキルには、マルチライブラリインテグレーション用のバンドルリソースが含まれます：

references/

• architecture_patterns.md - 詳細なアーキテクチャパターンとトレードオフ
• performance_optimization.md - スタック全体のパフォーマンス戦略
• state_management.md - 3D アプリケーション用状態管理パターン

scripts/

• integration_helper.py - ライブラリ組み合わせ用インテグレーションボイラープレート生成
• pattern_generator.py - 一般的なインテグレーションパターンをスキャフォルド

assets/

• starter_unified/ - R3F + GSAP + Motion を組み合わせた完全なスターターテンプレート
• examples/ - 実世界のインテグレーション例

---

関連スキル

基礎スキル（ライブラリ固有の詳細はこれらを使用）：

• threejs-webgl - Three.js の基礎、シーン設定、レンダリング
• gsap-scrolltrigger - GSAP アニメーション、ScrollTrigger、タイムライン
• react-three-fiber - R3F コンポーネント、hooks、Drei ヘルパー
• motion-framer - Motion コンポーネント、ジェスチャー、レイアウトアニメーション
• react-spring-physics - Spring 物理、React Spring hooks

基礎スキルを参照する場合：

• Three.js 固有の API 質問 → threejs-webgl
• ScrollTrigger 構文 → gsap-scrolltrigger
• R3F hooks とパターン → react-three-fiber
• Motion ジェスチャーハンドリング → motion-framer
• Spring 構成 → react-spring-physics

このメタスキルがカバー：

• ライブラリ組み合わせ用アーキテクチャパターン
• ライブラリ間の状態管理
• パフォーマンス最適化戦略
• よくあるインテグレーション落とし穴
• 意思決定フレームワーク

---

複数のアニメーションおよびレンダリングライブラリを統合する複雑な3D Webアプリケーション構築時にこのスキルを使用してください。ライブラリ固有の実装詳細については、個々の基礎スキルを参照してください。