@linxai/3d-shared 0.1.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@linxai/3d-shared",
+  "version": "0.1.0",
+  "description": "3D 可视化共享组件 - Web & React Native 通用",
+  "main": "./dist/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.mjs",
+      "require": "./dist/internal.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@react-three/fiber": ">=8.0.0",
+    "react": ">=18.0.0",
+    "react-native": "*",
+    "three": ">=0.160.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.7",
+    "@types/three": "^0.166.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}
+

package/src/components/SceneBuilder.tsx

@@ -0,0 +1,34 @@
+import type { ReactNode } from 'react'
+import type { SceneConfig, OrbitControlsConfig, GridHelperConfig } from '../types'
+
+/**
+ * 场景构建器接口
+ * Web 和 Native 分别实现此接口来装配场景
+ */
+export interface SceneBuilder {
+  /** 构建 Canvas 组件 */
+  buildCanvas: (props: {
+    children: ReactNode
+    config?: SceneConfig
+    style?: any
+    className?: string
+  }) => ReactNode
+
+  /** 构建 OrbitControls 组件 */
+  buildOrbitControls: (config?: OrbitControlsConfig) => ReactNode | null
+
+  /** 构建 GridHelper 组件 */
+  buildGridHelper: (config?: GridHelperConfig) => ReactNode | null
+}
+
+/**
+ * 使用构建器创建场景的 Hook
+ * 返回构建好的场景组件
+ */
+export function useSceneBuilder(builder: SceneBuilder) {
+  return {
+    buildCanvas: builder.buildCanvas,
+    buildOrbitControls: builder.buildOrbitControls,
+  }
+}
+

package/src/components/SceneContent.tsx

@@ -0,0 +1,63 @@
+import type { ReactNode } from 'react'
+import type { SceneConfig } from '../types'
+
+interface SceneContentProps {
+  /** 子组件 */
+  children: ReactNode
+  /** 场景配置 */
+  config?: SceneConfig
+}
+
+/**
+ * 通用的场景内容组件
+ * 包含背景色、光源等通用元素
+ * 这个组件在 Web 和 Native 中完全复用
+ * 
+ * 注意：此组件返回 JSX 片段，需要在 R3F Canvas 内部使用
+ */
+export function SceneContent({ children, config = {} }: SceneContentProps) {
+  const {
+    backgroundColor = '#000',
+    ambientLightIntensity = 0.5, // 向后兼容
+    lights,
+  } = config
+
+  // 光源配置（支持新配置和旧配置）
+  const ambientIntensity = lights?.ambientIntensity ?? ambientLightIntensity
+  const pointLight = lights?.pointLight
+  const directionalLight = lights?.directionalLight
+
+  return (
+    <>
+      {/* @ts-ignore - R3F JSX 元素 */}
+      <color attach="background" args={[backgroundColor]} />
+      
+      {/* 环境光 */}
+      {ambientIntensity > 0 && (
+        /* @ts-ignore - R3F JSX 元素 */
+        <ambientLight intensity={ambientIntensity} />
+      )}
+
+      {/* 点光源 */}
+      {pointLight && (
+        /* @ts-ignore - R3F JSX 元素 */
+        <pointLight 
+          position={pointLight.position || [10, 10, 10]} 
+          intensity={pointLight.intensity ?? 1} 
+        />
+      )}
+
+      {/* 方向光 */}
+      {directionalLight && (
+        /* @ts-ignore - R3F JSX 元素 */
+        <directionalLight 
+          position={directionalLight.position || [-10, -10, -5]} 
+          intensity={directionalLight.intensity ?? 0.5} 
+        />
+      )}
+
+      {children}
+    </>
+  )
+}
+

package/src/contexts/LoadingContext.tsx

@@ -0,0 +1,46 @@
+import { createContext, useContext, useState, useCallback, ReactNode } from 'react'
+
+interface LoadingContextValue {
+  progress: number
+  isLoading: boolean
+  setProgress: (progress: number) => void
+  setLoading: (loading: boolean) => void
+}
+
+const LoadingContext = createContext<LoadingContextValue | null>(null)
+
+/**
+ * 简单的加载状态管理 Context (Web)
+ */
+export function LoadingProvider({ children }: { children: ReactNode }) {
+  const [progress, setProgressState] = useState(0)
+  const [isLoading, setLoadingState] = useState(false)
+
+  const setProgress = useCallback((value: number) => {
+    setProgressState(Math.max(0, Math.min(1, value)))
+  }, [])
+
+  const setLoading = useCallback((loading: boolean) => {
+    setLoadingState(loading)
+  }, [])
+
+  return (
+    <LoadingContext.Provider
+      value={{ progress, isLoading, setProgress, setLoading }}
+    >
+      {children}
+    </LoadingContext.Provider>
+  )
+}
+
+/**
+ * 使用加载状态的 Hook
+ */
+export function useLoading() {
+  const context = useContext(LoadingContext)
+  if (!context) {
+    throw new Error('useLoading must be used within LoadingProvider')
+  }
+  return context
+}
+

package/src/hooks/useAnimationControl.ts

@@ -0,0 +1,145 @@
+import { useRef, useCallback, useState, useEffect } from 'react'
+import { AnimationMixer, AnimationAction, LoopOnce, LoopRepeat } from 'three'
+import { useFrame } from '@react-three/fiber'
+
+export interface AnimationControlOptions {
+  /** 加载的模型 */
+  model: any
+  /** 动画 Map */
+  animationsMap: Map<string, any> | null
+}
+
+export interface PlayOptions {
+  /** 是否循环播放 */
+  loop?: boolean
+  /** 淡入时间（秒） */
+  fadeIn?: number
+  /** 淡出时间（秒） */
+  fadeOut?: number
+  /** 播放速度 */
+  speed?: number
+}
+
+/**
+ * 动画控制 Hook
+ * 管理 AnimationMixer、动画播放、切换和过渡
+ */
+export function useAnimationControl(options: AnimationControlOptions) {
+  const { model, animationsMap } = options
+
+  const [mixer, setMixer] = useState<AnimationMixer | null>(null)
+  const currentActionRef = useRef<AnimationAction | null>(null)
+  const currentAnimationIdRef = useRef<string | null>(null)
+
+  // 初始化 AnimationMixer
+  useEffect(() => {
+    if (model?.scene) {
+      const newMixer = new AnimationMixer(model.scene)
+      setMixer(newMixer)
+      
+      return () => {
+        setMixer(null)
+      }
+    }
+  }, [model])
+
+
+  /**
+   * 播放动画
+   */
+  const play = useCallback((animationId: string, options: PlayOptions = {}) => {
+    if (!mixer || !animationsMap) return
+
+    const clip = animationsMap.get(animationId)
+    if (!clip) {
+      console.warn(`[AnimationControl] Animation clip not found: ${animationId}`)
+      return
+    }
+
+    const { loop = true, fadeIn = 0.3, speed = 1 } = options
+    const blendTime = fadeIn
+
+    const newAction = mixer.clipAction(clip)
+    newAction.loop = loop ? LoopRepeat : LoopOnce
+    newAction.clampWhenFinished = !loop
+
+    // 如果是同一个动画，不做任何操作
+    if (currentActionRef.current === newAction) {
+      return
+    }
+
+    // 如果有当前动画，使用 crossFadeTo 实现平滑过渡
+    if (currentActionRef.current && currentActionRef.current.isRunning()) {
+      // 准备新动画
+      newAction.reset().setEffectiveWeight(1).setEffectiveTimeScale(speed).play()
+      // 从当前动画平滑过渡到新动画
+      currentActionRef.current.crossFadeTo(newAction, blendTime, false)
+    } else {
+      // 首次播放，直接启动
+      newAction.reset().fadeIn(blendTime).play()
+    }
+
+    currentActionRef.current = newAction
+    currentAnimationIdRef.current = animationId
+  }, [mixer, animationsMap])
+
+  /**
+   * 停止动画
+   */
+  const stop = useCallback((fadeOut = 0.3) => {
+    if (currentActionRef.current) {
+      currentActionRef.current.fadeOut(fadeOut)
+      currentActionRef.current = null
+      currentAnimationIdRef.current = null
+    }
+  }, [])
+
+  /**
+   * 暂停动画
+   */
+  const pause = useCallback(() => {
+    if (currentActionRef.current?.isRunning()) {
+      currentActionRef.current.paused = true
+    }
+  }, [])
+
+  /**
+   * 恢复播放
+   */
+  const resume = useCallback(() => {
+    if (currentActionRef.current?.paused) {
+      currentActionRef.current.paused = false
+    }
+  }, [])
+
+  /**
+   * 获取当前播放的动画 ID
+   */
+  const getCurrentAnimation = useCallback(() => currentAnimationIdRef.current, [])
+
+  /**
+   * 是否正在播放
+   */
+  const isPlaying = useCallback(() => {
+    return currentActionRef.current ? currentActionRef.current.isRunning() : false
+  }, [])
+
+  /**
+   * 更新 AnimationMixer
+   */
+  useFrame((_, delta) => {
+    mixer?.update(delta)
+  })
+
+  return {
+    mixer,
+    currentAction: currentActionRef.current,
+    play,
+    stop,
+    pause,
+    resume,
+    getCurrentAnimation,
+    isPlaying,
+  }
+}
+

package/src/hooks/useAnimationLoader.ts

@@ -0,0 +1,149 @@
+import { useState, useEffect, useRef } from 'react'
+import type { AnimationConfig } from '../types'
+
+/**
+ * 动画加载状态
+ */
+export interface AnimationLoadState {
+  /** 是否已加载 */
+  loaded: boolean
+  /** 加载进度 (0-1) */
+  progress?: number
+  /** 错误信息 */
+  error?: Error | null
+  /** 加载的动画剪辑 */
+  clips?: any[] // Three.js AnimationClip[]
+}
+
+/**
+ * 动画加载器 Hook 返回值
+ */
+export interface AnimationLoaderResult {
+  /** 动画剪辑列表 */
+  clips: any[] | null
+  /** 加载状态 */
+  state: AnimationLoadState
+  /** 根据 ID 获取动画剪辑 */
+  getClip: (id: string) => any | null
+  /** 动画 Map (id -> clip) */
+  animationsMap: Map<string, any>
+}
+
+/**
+ * 平台特定的动画加载适配器
+ * 平台包提供具体的加载实现
+ */
+export interface AnimationLoaderAdapter {
+  /**
+   * 加载单个动画文件
+   * @param path 动画文件路径
+   * @param onProgress 进度回调
+   * @returns Promise<动画对象（包含 animations 数组）>
+   */
+  load: (
+    path: string | number,
+    onProgress?: (progress: number) => void
+  ) => Promise<{ animations: any[] }>
+}
+
+/**
+ * 使用动画加载器的 Hook
+ * 在 shared 中实现核心逻辑，使用平台适配器加载
+ * 加载后使用配置的 ID 重命名动画剪辑
+ */
+export function useAnimationLoader(
+  animations: AnimationConfig[] | undefined,
+  adapter: AnimationLoaderAdapter
+): AnimationLoaderResult {
+  const [state, setState] = useState<AnimationLoadState>({
+    loaded: false,
+    progress: 0,
+  })
+  const clipsMapRef = useRef<Map<string, any>>(new Map())
+
+  useEffect(() => {
+    if (!animations || animations.length === 0) {
+      setState({ loaded: true, progress: 1, clips: [] })
+      clipsMapRef.current.clear()
+      return
+    }
+
+    let mounted = true
+    let loadedCount = 0
+    const totalCount = animations.length
+    clipsMapRef.current.clear()
+
+    const loadAll = async () => {
+      try {
+        const loadPromises = animations.map(async (config, index) => {
+          try {
+            const fbxObject = await adapter.load(config.path, (progress) => {
+              if (mounted) {
+                const overallProgress = (index + progress) / totalCount
+                setState((prev) => ({
+                  ...prev,
+                  progress: overallProgress,
+                }))
+              }
+            })
+
+            if (mounted && fbxObject.animations && fbxObject.animations.length > 0) {
+              const clip = fbxObject.animations[0] // 取第一个动画剪辑
+              // 使用配置的 ID 重命名
+              clip.name = config.id
+              clipsMapRef.current.set(config.id, clip)
+            }
+
+            loadedCount++
+            if (mounted) {
+              setState((prev) => ({
+                ...prev,
+                progress: loadedCount / totalCount,
+              }))
+            }
+          } catch (error) {
+            console.error(`加载动画失败 (${config.id}):`, error)
+            if (mounted) {
+              setState((prev) => ({
+                ...prev,
+                error: error as Error,
+              }))
+            }
+          }
+        })
+
+        await Promise.all(loadPromises)
+
+        if (mounted) {
+          setState({
+            loaded: true,
+            progress: 1,
+            error: null,
+            clips: Array.from(clipsMapRef.current.values()),
+          })
+        }
+      } catch (error) {
+        if (mounted) {
+          setState({
+            loaded: false,
+            progress: 0,
+            error: error as Error,
+          })
+        }
+      }
+    }
+
+    loadAll()
+
+    return () => {
+      mounted = false
+    }
+  }, [animations, adapter])
+
+  return {
+    clips: state.clips || null,
+    state,
+    getClip: (id: string) => clipsMapRef.current.get(id) || null,
+    animationsMap: clipsMapRef.current,
+  }
+}

package/src/hooks/useAnimationStateMachine.ts

@@ -0,0 +1,229 @@
+import { useRef, useCallback, useState, useEffect } from 'react'
+import type { AnimationStatesConfig } from '../types'
+import type { PlayOptions } from './useAnimationControl'
+
+export interface AnimationStateMachineOptions {
+  /** 动画状态机配置 */
+  animationStates?: AnimationStatesConfig
+  /** 初始状态 */
+  initialState?: string
+  /** 初始情绪 */
+  initialMood?: string
+  /** 是否启用 welcome 状态 */
+  enableWelcome?: boolean
+  /** 播放动画函数 */
+  playAnimation: (animationId: string, options?: PlayOptions) => void
+  /** AnimationMixer */
+  mixer: any
+  /** 应用情绪表情函数 */
+  applyEmotion?: (emotion: string) => void
+  /** 状态变化回调 */
+  onStateChange?: (state: string, mood: string) => void
+}
+
+/**
+ * 动画状态机 Hook
+ * 管理状态、情绪切换和动画调度
+ */
+export function useAnimationStateMachine(options: AnimationStateMachineOptions) {
+  const { 
+    animationStates,
+    initialState = 'idle',
+    initialMood = 'neutral',
+    enableWelcome = false,
+    playAnimation,
+    mixer,
+    applyEmotion,
+    onStateChange,
+  } = options
+
+  // 状态初始化：如果启用 welcome 则先用 welcome，否则用 initialState
+  const getInitialState = () => {
+    if (enableWelcome && animationStates?.welcome) {
+      return 'welcome'
+    }
+    return initialState
+  }
+
+  const [currentState, setCurrentStateInternal] = useState<string>(getInitialState())
+  const [currentMood, setCurrentMoodInternal] = useState<string>(initialMood)
+  
+  const nextAnimationTimeoutRef = useRef<NodeJS.Timeout | null>(null)
+  const currentAnimationListRef = useRef<string[]>([])
+  const currentAnimationIndexRef = useRef<number>(0)
+  const targetStateAfterWelcomeRef = useRef<string>(initialState)
+  const initializedRef = useRef<boolean>(false)
+
+  // 清理定时器
+  useEffect(() => {
+    return () => {
+      if (nextAnimationTimeoutRef.current) {
+        clearTimeout(nextAnimationTimeoutRef.current)
+      }
+    }
+  }, [])
+
+  /**
+   * 播放状态机中的下一个动画
+   * State 决定动画，Mood 决定表情
+   */
+  const playNextAnimation = useCallback((state: string, mood: string, isWelcome = false) => {
+    if (!animationStates || !animationStates[state]) return
+
+    const stateConfig = animationStates[state]
+    const animations = stateConfig.animations
+    
+    if (!animations || animations.length === 0) {
+      console.warn(`[StateMachine] No animations found for state: ${state}`)
+      return
+    }
+    
+    // 应用情绪表情（morphTargets）
+    if (applyEmotion) {
+      applyEmotion(mood)
+    }
+
+    const config = stateConfig.config || {}
+    const { random = false, loop = true, fadeIn = 0.3, fadeOut = 0.3, duration } = config
+
+    let animationId: string
+
+    if (random) {
+      // 随机选择
+      const randomIndex = Math.floor(Math.random() * animations.length)
+      animationId = animations[randomIndex]
+    } else {
+      // 顺序播放
+      if (currentAnimationListRef.current !== animations) {
+        // 动画列表变了，重置索引
+        currentAnimationListRef.current = animations
+        currentAnimationIndexRef.current = 0
+      }
+      
+      animationId = animations[currentAnimationIndexRef.current]
+      currentAnimationIndexRef.current = (currentAnimationIndexRef.current + 1) % animations.length
+    }
+    
+    // 播放动画
+    playAnimation(animationId, { loop, fadeIn, fadeOut })
+
+    // 如果是 welcome 状态，监听动画结束事件
+    if (isWelcome && mixer) {
+      const handleWelcomeFinished = (e: any) => {
+        console.log('[StateMachine] Welcome animation finished, transition to:', targetStateAfterWelcomeRef.current)
+        setState(targetStateAfterWelcomeRef.current, mood)
+        mixer.removeEventListener('finished', handleWelcomeFinished)
+      }
+      
+      mixer.addEventListener('finished', handleWelcomeFinished)
+    } else {
+      // 如果设置了 duration，自动播放下一个
+      if (duration && duration > 0) {
+        if (nextAnimationTimeoutRef.current) {
+          clearTimeout(nextAnimationTimeoutRef.current)
+        }
+        
+        nextAnimationTimeoutRef.current = setTimeout(() => {
+          playNextAnimation(state, mood, false)
+        }, duration) as any
+      }
+    }
+  }, [animationStates, playAnimation, mixer])
+
+  /**
+   * 设置状态（和可选的情绪）
+   */
+  const setState = useCallback((state: string, mood?: string) => {
+    if (!animationStates || !animationStates[state]) {
+      console.warn(`[StateMachine] State not found: ${state}`)
+      return
+    }
+
+    const newMood = mood || currentMood
+    setCurrentStateInternal(state)
+    setCurrentMoodInternal(newMood)
+
+    // 清理之前的定时器
+    if (nextAnimationTimeoutRef.current) {
+      clearTimeout(nextAnimationTimeoutRef.current)
+      nextAnimationTimeoutRef.current = null
+    }
+
+    // 应用情绪表情
+    if (applyEmotion) {
+      applyEmotion(newMood)
+    }
+
+    // 播放对应的动画（welcome 状态特殊处理）
+    const isWelcome = state === 'welcome'
+    playNextAnimation(state, newMood, isWelcome)
+    
+    // 触发状态变化回调
+    if (onStateChange) {
+      onStateChange(state, newMood)
+    }
+  }, [animationStates, currentState, currentMood, playNextAnimation, applyEmotion, onStateChange])
+
+  /**
+   * 设置情绪（保持当前状态）
+   */
+  const setMood = useCallback((mood: string) => {
+    // mood 现在只影响表情，不影响动画选择
+    setCurrentMoodInternal(mood)
+    
+    // 应用情绪表情（morphTargets）
+    if (applyEmotion) {
+      applyEmotion(mood)
+    }
+    
+    // 触发状态变化回调
+    if (onStateChange) {
+      onStateChange(currentState, mood)
+    }
+  }, [currentState, applyEmotion, onStateChange])
+
+  /**
+   * 获取当前状态和情绪
+   */
+  const getCurrentState = useCallback(() => {
+    return { state: currentState, mood: currentMood }
+  }, [currentState, currentMood])
+
+  /**
+   * 初始化状态机（播放初始动画）
+   */
+  const initialize = useCallback(() => {
+    // 只初始化一次
+    if (initializedRef.current || !animationStates) return
+    
+    initializedRef.current = true
+    
+    // 应用初始情绪表情
+    if (applyEmotion) {
+      applyEmotion(initialMood)
+    }
+    
+    // currentState 已在 useState 时设置，这里只需要播放动画
+    if (currentState === 'welcome') {
+      targetStateAfterWelcomeRef.current = initialState
+      playNextAnimation('welcome', initialMood, true)
+    } else {
+      playNextAnimation(currentState, initialMood, false)
+    }
+    
+    // 触发状态变化回调
+    if (onStateChange) {
+      onStateChange(currentState, initialMood)
+    }
+  }, [animationStates, currentState, initialMood, initialState, playNextAnimation, applyEmotion, onStateChange])
+
+  return {
+    currentState,
+    currentMood,
+    setState,
+    setMood,
+    getCurrentState,
+    initialize,
+  }
+}
+