@linxai/3d-shared 0.1.0

package/src/hooks/useCharacterController.ts

@@ -0,0 +1,203 @@
+import { useEffect, useRef, useCallback, useState } from 'react'
+import { Bone } from 'three'
+import { useFrame } from '@react-three/fiber'
+import type { ModelLoadConfig, AnimationStatesConfig, CharacterInternal, Character } from '../types'
+import type { ModelLoaderAdapter } from './useModelLoader'
+import type { AnimationLoaderAdapter } from './useAnimationLoader'
+import { useModelLoader } from './useModelLoader'
+import { useAnimationLoader } from './useAnimationLoader'
+import { useAnimationControl } from './useAnimationControl'
+import { useAnimationStateMachine } from './useAnimationStateMachine'
+import { useMorphControl } from './useMorphControl'
+import { useProceduralAnimations } from './useProceduralAnimations'
+import { useTalkingControl } from './useTalkingControl'
+import { findHeadBone } from '../utils/characterUtils'
+
+export interface UseCharacterControllerOptions {
+  /** 模型配置 */
+  model: ModelLoadConfig
+  /** 模型加载适配器 */
+  modelAdapter: ModelLoaderAdapter
+  /** 动画加载适配器 */
+  animationAdapter: AnimationLoaderAdapter
+  /** 动画状态机配置（可选） */
+  animationStates?: AnimationStatesConfig
+  /** 初始状态（默认 'idle'） */
+  initialState?: string
+  /** 初始情绪 */
+  initialMood?: string
+  /** 是否启用 welcome 状态 */
+  enableWelcome?: boolean
+  /** 错误回调 */
+  onError?: (error: Error) => void
+  /** 状态变化回调 */
+  onStateChange?: (state: string, mood: string) => void
+}
+
+/**
+ * Character 控制器核心 Hook
+ * 处理模型/动画加载、AnimationMixer 管理、Character 对象构建
+ * 支持基础动画控制和状态机控制
+ * 
+ * @param options - 配置选项
+ * @returns Character 对象和加载状态
+ */
+export function useCharacterController(options: UseCharacterControllerOptions): {
+  loadedModel: any
+  character: CharacterInternal | null
+  isReady: boolean
+} {
+  const { 
+    model, 
+    modelAdapter, 
+    animationAdapter, 
+    animationStates, 
+    initialState = 'idle',
+    initialMood = 'neutral',
+    enableWelcome = false,
+    onError,
+    onStateChange
+  } = options
+
+  // 加载模型和动画
+  const { model: loadedModel, state } = useModelLoader(model, modelAdapter)
+  const { clips, animationsMap, state: animationState } = useAnimationLoader(model.animations, animationAdapter)
+
+  const headBoneRef = useRef<Bone | null>(null)
+  const [character, setCharacter] = useState<CharacterInternal | null>(null)
+  
+  // 使用子 hooks 管理各个功能模块（注意顺序：morphControl 必须在 stateMachine 之前）
+  const animationControl = useAnimationControl({
+    model: loadedModel,
+    animationsMap,
+  })
+  
+  const morphControl = useMorphControl(loadedModel)
+  const proceduralAnimations = useProceduralAnimations()
+  
+  const stateMachine = useAnimationStateMachine({
+    animationStates,
+    initialState,
+    initialMood,
+    enableWelcome,
+    playAnimation: animationControl.play,
+    mixer: animationControl.mixer,
+    applyEmotion: morphControl.applyEmotion,
+    onStateChange,
+  })
+  
+  // 用于记录当前状态下的动画列表和索引（用于顺序播放）
+  const currentAnimationListRef = useRef<string[]>([])
+  const currentAnimationIndexRef = useRef<number>(0)
+  
+  // 用于记录目标状态（welcome 结束后要切换到的状态）
+  const targetStateAfterWelcomeRef = useRef<string>(initialState)
+
+  // 说话控制（需要在 stateMachine 之后初始化）
+  const talkingControl = useTalkingControl({
+    animationStates,
+    morphMeshes: morphControl.morphMeshes,
+    playAnimation: animationControl.play,
+    setState: stateMachine.setState,
+  })
+
+  // 处理错误
+  useEffect(() => {
+    if (state.error && onError) {
+      onError(state.error)
+    }
+    if (animationState.error && onError) {
+      onError(animationState.error)
+    }
+  }, [state.error, animationState.error, onError])
+
+  // 初始化头部骨骼
+  useEffect(() => {
+    if (loadedModel?.scene) {
+      headBoneRef.current = findHeadBone(loadedModel)
+      
+      return () => {
+        headBoneRef.current = null
+      }
+    }
+  }, [loadedModel, morphControl.morphMeshes.length, animationControl.mixer])
+
+
+  // 资源加载完成后初始化（只执行一次）
+  useEffect(() => {
+    console.log('[useCharacterController] Check:', {
+      hasCharacter: !!character,
+      hasModel: !!loadedModel,
+      hasMixer: !!animationControl.mixer,
+      hasAnimationsMap: !!animationsMap,
+      animationsMapSize: animationsMap?.size,
+    })
+    
+    if (character) return // 已经初始化过了
+    if (!loadedModel || !animationControl.mixer) return
+    
+    // 检查动画是否需要加载
+    const hasAnimations = model.animations && model.animations.length > 0
+    if (hasAnimations && (!animationsMap || animationsMap.size === 0)) return
+
+    console.log('[useCharacterController] ✅ Creating character...')
+
+    // 构建 Character 对象（极简公共接口 + 完整内部接口）
+    const characterObj: CharacterInternal = {
+      model: loadedModel,
+      clips,
+      animationsMap,
+      getClip: (id: string) => animationsMap?.get(id) || null,
+      mixer: animationControl.mixer,
+      
+      // 公共 API（仅 4 个核心方法）
+      setState: stateMachine.setState,
+      getState: stateMachine.getCurrentState,
+      startSpeak: talkingControl.startSpeak,
+      stopSpeak: talkingControl.stopSpeak,
+      
+      // 内部 API（不对外暴露，但内部可用）
+      play: animationControl.play,
+      stop: animationControl.stop,
+      pause: animationControl.pause,
+      resume: animationControl.resume,
+      getCurrentAnimation: animationControl.getCurrentAnimation,
+      isPlaying: animationControl.isPlaying,
+      isSpeaking: talkingControl.isSpeaking,
+      setMood: stateMachine.setMood,
+      applyEmotion: morphControl.applyEmotion,
+      setMorphWeight: morphControl.setMorphWeight,
+      setDualMorph: morphControl.setDualMorph,
+      setHeadSwayEnabled: proceduralAnimations.setHeadSwayEnabled,
+      setBlinkingEnabled: proceduralAnimations.setBlinkingEnabled,
+      setLipSyncEnabled: proceduralAnimations.setLipSyncEnabled,
+    }
+
+    // 初始化状态机
+    stateMachine.initialize()
+    
+    // 设置 character（这会触发 isReady = true）
+    setCharacter(characterObj)
+    console.log('[useCharacterController] ✅ Character created and set!')
+  }, [loadedModel, animationControl.mixer, animationsMap, character])
+
+  // 更新程序化动画
+  useFrame((_, delta) => {
+    // 更新程序化动画
+    proceduralAnimations.update(delta, {
+      headBone: headBoneRef.current,
+      morphMeshes: morphControl.morphMeshes,
+      emotion: talkingControl.getCurrentEmotion(),
+      isSpeaking: talkingControl.isSpeaking(),
+    })
+
+    // 更新说话手势调度
+    talkingControl.updateTalkGestures(delta)
+  })
+
+  return {
+    loadedModel,
+    character,
+    isReady: !!character,
+  }
+}

package/src/hooks/useModelLoader.ts

@@ -0,0 +1,115 @@
+import { useState, useEffect } from 'react'
+import type { ModelLoadConfig, SceneState } from '../types'
+
+/**
+ * 平台特定的模型加载适配器
+ * 平台包提供具体的加载实现
+ */
+export interface ModelLoaderAdapter {
+  /**
+   * 加载模型文件
+   * @param path 模型文件路径
+   * @param onProgress 进度回调
+   * @returns Promise<GLTF 对象>
+   */
+  load: (
+    path: string | number,
+    onProgress?: (progress: number) => void
+  ) => Promise<any> // GLTF
+}
+
+/**
+ * 使用模型加载器的 Hook
+ * 在 shared 中实现核心逻辑，使用平台适配器加载
+ */
+export function useModelLoader(
+  config: ModelLoadConfig,
+  adapter: ModelLoaderAdapter
+): { model: any | null; state: SceneState } {
+  const [state, setState] = useState<SceneState>({
+    loaded: false,
+    progress: 0,
+  })
+  const [model, setModel] = useState<any | null>(null)
+
+  useEffect(() => {
+    let mounted = true
+
+    const loadModel = async () => {
+      try {
+        setState({ loaded: false, progress: 0 })
+
+        const gltf = await adapter.load(config.path, (progress) => {
+          if (mounted) {
+            setState((prev) => ({
+              ...prev,
+              progress,
+            }))
+          }
+        })
+
+        if (mounted) {
+          setModel(gltf)
+          setState({
+            loaded: true,
+            progress: 1,
+            error: null,
+          })
+        }
+      } catch (error) {
+        if (mounted) {
+          setState({
+            loaded: false,
+            progress: 0,
+            error: error as Error,
+          })
+        }
+      }
+    }
+
+    loadModel()
+
+    return () => {
+      mounted = false
+    }
+  }, [config.path, adapter])
+
+  // 应用配置（缩放、位置、旋转等）
+  useEffect(() => {
+    if (model?.scene) {
+      const { scale, position, rotation, castShadow, receiveShadow } = config
+
+      if (scale) {
+        if (Array.isArray(scale)) {
+          model.scene.scale.set(...scale)
+        } else {
+          model.scene.scale.setScalar(scale)
+        }
+      }
+
+      if (position) {
+        model.scene.position.set(...position)
+      }
+
+      if (rotation) {
+        model.scene.rotation.set(...rotation)
+      }
+
+      // 遍历所有 mesh，设置阴影
+      model.scene.traverse((child: any) => {
+        if ('castShadow' in child) {
+          child.castShadow = castShadow ?? false
+        }
+        if ('receiveShadow' in child) {
+          child.receiveShadow = receiveShadow ?? false
+        }
+      })
+    }
+  }, [model, config])
+
+  return {
+    model,
+    state,
+  }
+}
+

package/src/hooks/useMorphControl.ts

@@ -0,0 +1,46 @@
+import { useRef, useCallback, useEffect } from 'react'
+import type { SkinnedMesh } from 'three'
+import {
+  findMorphTargetMeshes,
+  setMorphWeight as utilSetMorphWeight,
+  setDualMorph as utilSetDualMorph,
+  applyEmotionMorphs,
+} from '../utils/characterUtils'
+
+/**
+ * Morph Target 控制 Hook
+ * 管理模型的 morph targets（表情控制）
+ */
+export function useMorphControl(model: any) {
+  const morphMeshesRef = useRef<SkinnedMesh[]>([])
+
+  // 初始化 morph meshes
+  useEffect(() => {
+    if (model?.scene) {
+      morphMeshesRef.current = findMorphTargetMeshes(model)
+    }
+    return () => {
+      morphMeshesRef.current = []
+    }
+  }, [model])
+
+  const setMorphWeight = useCallback((morphName: string, value: number) => {
+    utilSetMorphWeight(morphMeshesRef.current, morphName, value)
+  }, [])
+
+  const setDualMorph = useCallback((baseName: string, value: number) => {
+    utilSetDualMorph(morphMeshesRef.current, baseName, value)
+  }, [])
+
+  const applyEmotion = useCallback((emotion: string) => {
+    applyEmotionMorphs(morphMeshesRef.current, emotion)
+  }, [])
+
+  return {
+    morphMeshes: morphMeshesRef.current,
+    setMorphWeight,
+    setDualMorph,
+    applyEmotion,
+  }
+}
+

package/src/hooks/useProceduralAnimations.ts

@@ -0,0 +1,91 @@
+import { useRef, useCallback } from 'react'
+import type { Bone, SkinnedMesh } from 'three'
+import {
+  setMorphWeight,
+  setDualMorph,
+  getEmotionHeadSwayParams,
+} from '../utils/characterUtils'
+
+export interface ProceduralAnimationsOptions {
+  headBone: Bone | null
+  morphMeshes: SkinnedMesh[]
+  emotion: string
+  isSpeaking: boolean
+}
+
+/**
+ * 程序化动画控制 Hook
+ * 管理头部微动、眨眼、lip-sync 等程序化动画
+ */
+export function useProceduralAnimations() {
+  const elapsedTimeRef = useRef<number>(0)
+  const headSwayEnabledRef = useRef<boolean>(true)
+  const blinkingEnabledRef = useRef<boolean>(true)
+  const lipSyncEnabledRef = useRef<boolean>(true)
+
+  const setHeadSwayEnabled = useCallback((enabled: boolean) => {
+    headSwayEnabledRef.current = enabled
+  }, [])
+
+  const setBlinkingEnabled = useCallback((enabled: boolean) => {
+    blinkingEnabledRef.current = enabled
+  }, [])
+
+  const setLipSyncEnabled = useCallback((enabled: boolean) => {
+    lipSyncEnabledRef.current = enabled
+  }, [])
+
+  /**
+   * 更新程序化动画（在 useFrame 中调用）
+   */
+  const update = useCallback((delta: number, options: ProceduralAnimationsOptions) => {
+    elapsedTimeRef.current += delta
+    const time = elapsedTimeRef.current
+    const { headBone, morphMeshes, emotion, isSpeaking } = options
+
+    // 头部微动
+    if (headSwayEnabledRef.current && headBone) {
+      const { speed, range, pitchOffset } = getEmotionHeadSwayParams(emotion)
+
+      let yaw = Math.sin(time * speed) * range
+      let pitch = (Math.cos(time * speed * 0.7) * (range * 0.5)) + pitchOffset
+
+      if (isSpeaking) {
+        yaw *= 0.3
+        pitch += Math.sin(time * 8.0) * 0.03
+      }
+
+      headBone.rotation.y = yaw
+      headBone.rotation.x = pitch
+    }
+
+    // 眨眼
+    if (blinkingEnabledRef.current && morphMeshes.length > 0) {
+      const blinkSignal = Math.sin(time * 1.2)
+      const isBlinking = blinkSignal > 0.98
+      setDualMorph(morphMeshes, 'eyeBlink', isBlinking ? 1.0 : 0.0)
+    }
+
+    // Lip Sync
+    if (lipSyncEnabledRef.current && morphMeshes.length > 0) {
+      if (isSpeaking) {
+        const openAmount = (Math.sin(time * 18.0) + 1) * 0.25
+        setMorphWeight(morphMeshes, 'jawOpen', openAmount)
+
+        const funnelAmount = (Math.cos(time * 12.0) + 1) * 0.2
+        setDualMorph(morphMeshes, 'mouthFunnel', funnelAmount)
+      } else {
+        setMorphWeight(morphMeshes, 'jawOpen', 0)
+        setDualMorph(morphMeshes, 'mouthFunnel', 0)
+      }
+    }
+  }, [])
+
+  return {
+    update,
+    setHeadSwayEnabled,
+    setBlinkingEnabled,
+    setLipSyncEnabled,
+  }
+}
+

package/src/hooks/useTalkingControl.ts

@@ -0,0 +1,109 @@
+import { useRef, useCallback } from 'react'
+import type { SkinnedMesh } from 'three'
+import type { AnimationStatesConfig } from '../types'
+import {
+  resetLipSyncMorphs,
+  getEmotionHeadSwayParams,
+  applyEmotionMorphs,
+} from '../utils/characterUtils'
+
+export interface TalkingControlOptions {
+  animationStates?: AnimationStatesConfig
+  morphMeshes: SkinnedMesh[]
+  playAnimation: (animationId: string, options?: { loop?: boolean }) => void
+  setState: (state: string, mood?: string) => void
+}
+
+/**
+ * 说话控制 Hook
+ * 管理说话状态、情绪和手势调度
+ */
+export function useTalkingControl(options: TalkingControlOptions) {
+  const { animationStates, morphMeshes, playAnimation, setState } = options
+
+  const isSpeakingRef = useRef<boolean>(false)
+  const currentEmotionRef = useRef<string>('neutral')
+  const talkGestureAnimationsRef = useRef<string[]>([])
+  const talkTimerRef = useRef<number>(0)
+  const nextTalkSwitchRef = useRef<number>(0)
+
+  const extractTalkGestures = useCallback(() => {
+    if (!animationStates?.speaking) return
+
+    const speakingConfig = animationStates.speaking
+    // animations 现在直接是 string[]
+    talkGestureAnimationsRef.current = speakingConfig.animations
+  }, [animationStates])
+
+  const triggerRandomTalkGesture = useCallback(() => {
+    if (talkGestureAnimationsRef.current.length === 0) {
+      extractTalkGestures()
+    }
+
+    if (talkGestureAnimationsRef.current.length === 0) {
+      return
+    }
+
+    const randomIndex = Math.floor(Math.random() * talkGestureAnimationsRef.current.length)
+    const nextAnim = talkGestureAnimationsRef.current[randomIndex]
+
+    playAnimation(nextAnim, { loop: true })
+
+    talkTimerRef.current = 0
+    nextTalkSwitchRef.current = 2.0 + Math.random() * 2.0
+  }, [playAnimation, extractTalkGestures])
+
+  const startSpeak = useCallback((emotion?: string) => {
+    const targetEmotion = emotion || currentEmotionRef.current
+    currentEmotionRef.current = targetEmotion
+    isSpeakingRef.current = true
+
+    applyEmotionMorphs(morphMeshes, targetEmotion)
+
+    if (animationStates?.speaking) {
+      setState('speaking', targetEmotion)
+      triggerRandomTalkGesture()
+    }
+  }, [animationStates, morphMeshes, setState, triggerRandomTalkGesture])
+
+  const stopSpeak = useCallback((resetEmotion?: string) => {
+    isSpeakingRef.current = false
+    
+    const targetEmotion = resetEmotion || currentEmotionRef.current
+    if (resetEmotion) {
+      currentEmotionRef.current = resetEmotion
+    }
+
+    resetLipSyncMorphs(morphMeshes)
+    applyEmotionMorphs(morphMeshes, targetEmotion)
+
+    if (animationStates?.idle) {
+      setState('idle', targetEmotion)
+    }
+  }, [animationStates, morphMeshes, setState])
+
+  const isSpeaking = useCallback(() => isSpeakingRef.current, [])
+
+  const getCurrentEmotion = useCallback(() => currentEmotionRef.current, [])
+
+  /**
+   * 更新说话手势调度（在 useFrame 中调用）
+   */
+  const updateTalkGestures = useCallback((delta: number) => {
+    if (isSpeakingRef.current && animationStates?.speaking) {
+      talkTimerRef.current += delta
+      if (talkTimerRef.current > nextTalkSwitchRef.current) {
+        triggerRandomTalkGesture()
+      }
+    }
+  }, [animationStates, triggerRandomTalkGesture])
+
+  return {
+    startSpeak,
+    stopSpeak,
+    isSpeaking,
+    getCurrentEmotion,
+    updateTalkGestures,
+  }
+}
+

package/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * 3D-Shared 公共 API
+ * 只暴露用户需要的配置类型和通用组件
+ */
+
+// ============================================================
+// 类型定义 - 用户配置所需
+// ============================================================
+export type {
+  // 场景配置
+  SceneConfig,
+  LightConfig,
+  GridHelperConfig,
+  OrbitControlsConfig,
+  
+  // 模型和动画配置
+  ModelLoadConfig,
+  AnimationConfig,
+  AnimationStatesConfig,
+  AnimationStateConfig,
+  
+  // Character 接口（供用户调用，只包含高级 API）
+  Character,
+  CharacterViewProps,
+  OverlayConfig,
+  // 注意：不导出 CharacterInternal（内部使用）
+} from './types'
+
+// ============================================================
+// 通用组件 - 跨平台复用
+// ============================================================
+export { SceneContent } from './components/SceneContent'

package/src/internal.ts

@@ -0,0 +1,52 @@
+/**
+ * 3D-Shared 内部 API
+ * 仅供 @linxai/3d-web 和 @linxai/3d-native 使用
+ * 不对最终用户暴露
+ */
+
+// ============================================================
+// 核心 Hook - 平台包只需要这一个
+// ============================================================
+export { useCharacterController } from './hooks/useCharacterController'
+export type { UseCharacterControllerOptions } from './hooks/useCharacterController'
+
+// ============================================================
+// 适配器接口 - 平台包需要实现
+// ============================================================
+export type { ModelLoaderAdapter } from './hooks/useModelLoader'
+export type { AnimationLoaderAdapter } from './hooks/useAnimationLoader'
+
+// ============================================================
+// 场景构建 - 平台包使用
+// ============================================================
+export type { SceneBuilder } from './components/SceneBuilder'
+export { useSceneBuilder } from './components/SceneBuilder'
+export { SceneContent } from './components/SceneContent'
+
+// ============================================================
+// Character 接口 - 平台包构建 Character 对象使用
+// ============================================================
+export type { Character, CharacterInternal, CharacterViewProps } from './types/character'
+
+// ============================================================
+// 上下文 - 平台包使用
+// ============================================================
+export { LoadingProvider, useLoading } from './contexts/LoadingContext'
+
+// ============================================================
+// 工具函数 - 平台包使用
+// ============================================================
+export {
+  findHeadBone,
+  findMorphTargetMeshes,
+  setMorphWeight,
+  setDualMorph,
+  resetLipSyncMorphs,
+  getEmotionHeadSwayParams,
+  applyEmotionMorphs,
+} from './utils/characterUtils'
+
+// ============================================================
+// 类型定义 - 平台包使用
+// ============================================================
+export type { SceneConfig, SceneState } from './types'