Web3d Integration Patterns

作者 freshtechbro1da73febff0c無授權條款1K 個星標收錄於 2026年10月8日更新於 2026年10月8日儲存庫10 個月前更新

Meta-skill for combining Three.js, GSAP ScrollTrigger, React Three Fiber, Motion, and React Spring for complex 3D web experiences. Use when building applications that integrate multiple 3D and animation libraries, requiring architecture patterns, state management, and performance optimization across the stack. Triggers on tasks involving library integration, multi-library architectures, scroll-driven 3D experiences, physics-based 3D animations, or complex interactive 3D applications.

僅含說明Software Development
AI 產生的概覽

在 3D 網頁應用中整合 Three.js、GSAP、React Three Fiber、Motion 與 React Spring 的架構模式。

功能
這是一份僅含說明的中繼技能，提供在網頁應用中整合多個 3D 與動畫函式庫的架構模式、程式碼範例與選型指引。內容涵蓋分層式、統一 React 式、混合式與物理導向的做法，以及狀態管理、效能最佳化和常見陷阱。它產出的是參考指引與範例程式碼，而非可直接執行的成品。
適用情境
適用於規劃或建構整合多個渲染與動畫函式庫的複雜 3D 網頁體驗。適合捲動驅動的 3D 場景、物理導向的互動、跨函式庫狀態管理與效能調校。在為特定情境挑選函式庫組合時也很有幫助。
執行需求
實際上並未附帶任何指令碼或資源，文件中只是提及。所述模式假定使用 JavaScript 或 React 專案，並依賴 Three.js、GSAP 與 ScrollTrigger、React Three Fiber、Motion 和 React Spring，可選用 Zustand 與 Drei。

Web 3D Integration Patterns

Overview

This meta-skill provides architectural patterns, best practices, and integration strategies for combining multiple 3D and animation libraries in web applications. It synthesizes knowledge from the threejs-webgl, gsap-scrolltrigger, react-three-fiber, motion-framer, and react-spring-physics skills into cohesive patterns for building complex, performant 3D web experiences.

When to use this skill:

  • Building complex 3D applications that combine multiple libraries
  • Creating scroll-driven 3D experiences with animation orchestration
  • Implementing physics-based interactions with 3D scenes
  • Managing state across 3D rendering and UI animations
  • Optimizing performance in multi-library architectures
  • Designing reusable component architectures for 3D applications
  • Migrating between or combining animation approaches

Core Integration Combinations:

  1. Three.js + GSAP - Scroll-driven 3D animations, timeline orchestration
  2. React Three Fiber + Motion - State-based 3D with declarative animations
  3. React Three Fiber + GSAP - Complex 3D sequences in React
  4. React Three Fiber + React Spring - Physics-based 3D interactions
  5. Three.js + GSAP + React - Hybrid imperative/declarative 3D

Architecture Patterns

Pattern 1: Layered Separation (Three.js + GSAP + React UI)

Use case: 3D scene with overlaid UI, scroll-driven animations

Architecture:

├── 3D Layer (Three.js)│   ├── Scene management│   ├── Camera controls│   └── Render loop├── Animation Layer (GSAP)│   ├── ScrollTrigger for 3D properties│   ├── Timelines for sequences│   └── UI transitions└── UI Layer (React + Motion)    ├── HTML overlays    ├── State management    └── User interactions

Implementation:

javascript
// App.jsx - React rootimport { 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(() => {    // Initialize Three.js scene    sceneRef.current = initThreeScene(canvasRef.current)
    // Initialize GSAP ScrollTrigger animations    initScrollAnimations(sceneRef.current)
    // Cleanup    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">          {/* Scrollable content */}        </section>      </motion.div>    </div>  )}
javascript
// three/scene.js - Three.js setupimport * 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
  // Setup scene objects  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)
  // Lighting  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)
  // Animation loop  function animate() {    requestAnimationFrame(animate)    controls.update()    renderer.render(scene, camera)  }  animate()
  // Resize handler  window.addEventListener('resize', () => {    camera.aspect = window.innerWidth / window.innerHeight    camera.updateProjectionMatrix()    renderer.setSize(window.innerWidth, window.innerHeight)  })
  return { scene, camera, renderer, cube }}
javascript
// animations/scroll.js - GSAP ScrollTrigger integrationimport gsap from 'gsap'import { ScrollTrigger } from 'gsap/ScrollTrigger'
gsap.registerPlugin(ScrollTrigger)
export function initScrollAnimations(sceneRefs) {  const { camera, cube } = sceneRefs
  // Animate camera on scroll  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)    }  })
  // Animate mesh rotation  gsap.to(cube.rotation, {    y: Math.PI * 2,    x: Math.PI,    scrollTrigger: {      trigger: '.content',      start: 'top bottom',      end: 'bottom top',      scrub: true    }  })
  // Animate material properties  gsap.to(cube.material, {    opacity: 0.3,    scrollTrigger: {      trigger: '.content',      start: 'top center',      end: 'center center',      scrub: 1    }  })}

Benefits:

  • Clear separation of concerns
  • Easy to reason about data flow
  • Performance optimization per layer
  • Independent testing of layers

Trade-offs:

  • More boilerplate
  • Manual synchronization between layers
  • State management complexity

Pattern 2: Unified React Component (React Three Fiber + Motion)

Use case: React-first architecture with declarative 3D and animations

Architecture:

React Component Tree├── <Canvas> (R3F)│   ├── 3D Scene Components│   ├── Lights│   ├── Camera│   └── Effects└── <motion.div> (UI overlays)    ├── HTML content    └── Animations

Implementation:

jsx
// App.jsx - Unified React approachimport { 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>  )}
jsx
// components/Scene.jsx - R3F sceneimport { 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>  )}

Benefits:

  • Declarative, React-first approach
  • Unified state management
  • Component reusability
  • Easy testing with React tools

Trade-offs:

  • R3F learning curve
  • Less control over render loop
  • Potential React re-render issues

Pattern 3: Hybrid Approach (R3F + GSAP Timelines)

Use case: Complex animation sequences with React state management

Implementation:

jsx
// components/AnimatedScene.jsximport { useRef, useEffect } from 'react'import { useFrame } from '@react-three/fiber'import gsap from 'gsap'
export function AnimatedScene() {  const groupRef = useRef()  const timelineRef = useRef()
  useEffect(() => {    // Create GSAP timeline for complex sequence    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) // Start at same time
    timelineRef.current = tl
    return () => tl.kill()  }, [])
  return (    <group ref={groupRef}>      <mesh>        <boxGeometry />        <meshStandardMaterial color="cyan" />      </mesh>    </group>  )}

Pattern 4: Physics-Based 3D (R3F + React Spring)

Use case: Natural, physics-driven 3D interactions

Implementation:

jsx
// components/PhysicsCube.jsximport { 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]    })
    // Return to original after delay    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>  )}

Common Integration Patterns

1. Scroll-Driven Camera Movement

Three.js + GSAP:

javascript
import gsap from 'gsap'import { ScrollTrigger } from 'gsap/ScrollTrigger'
gsap.registerPlugin(ScrollTrigger)
// Smooth camera path through multiple pointsconst 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):

jsx
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. Gesture-Driven 3D Manipulation

R3F + Motion (Framer Motion 3D):

jsx
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. State-Synchronized Animations

R3F + Zustand + GSAP:

jsx
// store.jsimport create from 'zustand'
export const useStore = create((set) => ({  selectedObject: null,  cameraMode: 'orbit',  setSelectedObject: (obj) => set({ selectedObject: obj }),  setCameraMode: (mode) => set({ cameraMode: mode })}))
jsx
// components/InteractiveObject.jsximport { 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>  )}

State Management Strategies

1. Zustand for Global 3D State

Best for: Shared state across 3D scene and UI

javascript
// store/scene.jsimport create from 'zustand'
export const useSceneStore = create((set, get) => ({  // State  camera: { position: [0, 2, 5], target: [0, 0, 0] },  objects: {},  selectedId: null,  isAnimating: false,
  // Actions  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 })}))

Usage in R3F:

jsx
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>  )}

Performance Optimization

Cross-Library Performance Patterns

1. Render Loop Optimization

Coordinate render loops between Three.js and animation libraries:

javascript
// Unified render loop with conditional renderingimport { Clock } from 'three'
const clock = new Clock()let needsRender = true
function animate() {  requestAnimationFrame(animate)
  const delta = clock.getDelta()  const elapsed = clock.getElapsedTime()
  // Only render when needed  if (needsRender || controls.enabled) {    // Update GSAP animations (handled automatically)
    // Update Three.js    controls.update()    renderer.render(scene, camera)
    // Reset flag    needsRender = false  }}
// Trigger re-render on interactionsScrollTrigger.addEventListener('update', () => {  needsRender = true})
2. On-Demand Rendering (R3F)
jsx
import { Canvas } from '@react-three/fiber'
function App() {  return (    <Canvas      frameloop="demand" // Only renders when needed      dpr={[1, 2]} // Adaptive pixel ratio    >      <Scene />    </Canvas>  )}
function Scene() {  const invalidate = useThree((state) => state.invalidate)
  // Trigger render on state change  const handleClick = () => {    // Update state...    invalidate() // Manually trigger render  }
  return <mesh onClick={handleClick}>...</mesh>}

Common Pitfalls

1. Animation Conflicts

Problem: Multiple libraries trying to animate the same property

jsx
// ❌ Wrong: GSAP and React Spring both animating positiongsap.to(meshRef.current.position, { x: 5 })api.start({ position: [10, 0, 0] }) // Conflict!

Solution: Choose one library per property or coordinate timing

jsx
// ✅ Correct: Separate propertiesgsap.to(meshRef.current.position, { x: 5 }) // GSAP handles positionapi.start({ scale: 1.5 }) // Spring handles scale

2. State Synchronization Issues

Problem: React state out of sync with Three.js scene

jsx
// ❌ Wrong: Updating Three.js without updating React statemesh.position.x = 5 // Three.js updated// But React state still shows old value!

Solution: Use refs or state management

jsx
// ✅ Correct: Update bothconst updatePosition = (x) => {  mesh.position.x = x  setPosition(x) // Update React state}

3. Memory Leaks from Abandoned Animations

Problem: Not cleaning up animations on unmount

jsx
// ❌ Wrong: No cleanupuseEffect(() => {  gsap.to(meshRef.current.rotation, { y: Math.PI * 2, repeat: -1 })}, [])

Solution: Always cleanup in useEffect return

jsx
// ✅ Correct: Cleanup on unmountuseEffect(() => {  const tween = gsap.to(meshRef.current.rotation, { y: Math.PI * 2, repeat: -1 })
  return () => {    tween.kill()  }}, [])

Decision Matrix

When to Use Which Combination

Use CaseRecommended StackRationale
Marketing landing page with scroll-driven 3DThree.js + GSAP + React UIGSAP excels at scroll orchestration
React app with interactive 3D product viewerR3F + MotionDeclarative, state-driven, component-based
Complex animation sequences (timeline-based)R3F + GSAPGSAP timeline control with R3F components
Physics-based interactions (drag, momentum)R3F + React SpringSpring physics feel natural for gestures
High-performance particle systemsThree.js + GSAPImperative control, instancing, minimal overhead
Rapid prototyping, quick iterationsR3F + Drei + MotionHigh-level abstractions, fast development
Game-like experiences with physicsR3F + React Spring + Cannon (physics)Physics engine + spring-based UI feedback

Resources

This skill includes bundled resources for multi-library integration:

references/

  • architecture_patterns.md - Detailed architectural patterns and trade-offs
  • performance_optimization.md - Performance strategies across the stack
  • state_management.md - State management patterns for 3D applications

scripts/

  • integration_helper.py - Generate integration boilerplate for library combinations
  • pattern_generator.py - Scaffold common integration patterns

assets/

  • starter_unified/ - Complete starter template combining R3F + GSAP + Motion
  • examples/ - Real-world integration examples

Related Skills

Foundation Skills (use these for library-specific details):

  • threejs-webgl - Three.js fundamentals, scene setup, rendering
  • gsap-scrolltrigger - GSAP animations, ScrollTrigger, timelines
  • react-three-fiber - R3F components, hooks, Drei helpers
  • motion-framer - Motion components, gestures, layout animations
  • react-spring-physics - Spring physics, React Spring hooks

When to Reference Foundation Skills:

  • Three.js-specific API questions → threejs-webgl
  • ScrollTrigger syntax → gsap-scrolltrigger
  • R3F hooks and patterns → react-three-fiber
  • Motion gesture handling → motion-framer
  • Spring configuration → react-spring-physics

This Meta-Skill Covers:

  • Architecture patterns for combining libraries
  • State management across libraries
  • Performance optimization strategies
  • Common integration pitfalls
  • Decision-making frameworks

Use this skill when building complex 3D web applications that integrate multiple animation and rendering libraries. For library-specific implementation details, reference the individual foundation skills.

來源與署名

來源：freshtechbro/claudedesignskills位於.claude/skills/web3d-integration-patterns提交1da73fe

授權條款： 無授權條款

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架

更多來自 freshtechbro/claudedesignskills 的技能

Threejs Webgl

freshtechbro

指導 Three.js WebGL/WebGPU 開發，用於打造互動式 3D 網頁場景，並提供參考文件與起始場景。

包含腳本
Software Development1K10 個月前更新

Substance 3d Texturing

freshtechbro

指導在 Substance 3D Painter 中建立並匯出面向網頁與即時引擎的 PBR 貼圖，並提供 Python 批次自動化。

包含腳本
Design & Creative1K10 個月前更新

Scroll Reveal Libraries

freshtechbro

指導使用 AOS 函式庫為網頁加入簡單的捲動觸發顯現動畫。

包含腳本
Software Development1K10 個月前更新

Rive Interactive

freshtechbro

指導在 React 中以狀態機、輸入、ViewModel 和事件打造可互動的 Rive 向量動畫。

包含腳本
Design & Creative1K10 個月前更新

Pixijs 2d

freshtechbro

指導使用 PixiJS WebGL/WebGPU 引擎打造高效能 2D 圖形、粒子效果與互動式畫布。

包含腳本
Software Development1K10 個月前更新

Motion Framer

freshtechbro

指導使用 Motion（Framer Motion）為 React 介面製作動畫，涵蓋手勢、變體、版面與退場動畫。

包含腳本
Software Development1K10 個月前更新

更多Software Development技能

Playground

anthropics

精選

建立自成一體的互動式 HTML 遊樂場，包含控制項、即時預覽與可複製的提示詞輸出。

Software Development37K今天更新

M5 Onboard

anthropics

精選

透過 USB 偵測 M5Stack ESP32 開發板，燒錄 UIFlow 2.0 韌體並安裝 MicroPython 應用程式套件。

Software Development37K今天更新

Cardputer Buddy

anthropics

精選

指導迭代 Cardputer-Adv 的 MicroPython 應用程式套件：新增應用程式、透過 USB 序列埠推送檔案、查看日誌並執行 REPL 指令。

Software Development37K今天更新

Web Design Guidelines

vercel-labs

精選

依據從遠端來源取得的 Web Interface Guidelines 審查 UI 程式碼，並以 file:line 形式回報問題。

Software Development32K5 週前更新

Vercel React Native Skills

vercel-labs

精選

React Native 與 Expo 最佳實務規則，涵蓋清單效能、動畫、導覽、UI 模式、狀態與 monorepo 設定。

Software Development32K5 週前更新

Vercel React Best Practices

vercel-labs

精選

Vercel 的 React 與 Next.js 效能指南，以 70 條規則的形式用於撰寫、審查與重構程式碼。

Software Development32K5 週前更新