@linxai/3d-shared 0.1.0

package/src/types/character.ts

@@ -0,0 +1,136 @@
+import type { ReactNode } from 'react'
+import type { SceneConfig, OrbitControlsConfig, ModelLoadConfig, AnimationStatesConfig } from './index'
+
+/**
+ * Character 接口
+ * 只暴露最核心的 API，极简设计
+ */
+export interface Character {
+  /** 加载的模型对象 */
+  model: any
+  
+  /** 设置动画状态（如 'idle', 'speaking', 'dancing'） */
+  setState: (state: string, mood?: string) => void
+  
+  /** 获取当前状态和情绪 */
+  getState: () => { state: string; mood: string }
+  
+  /** 开始说话（可选指定情绪） */
+  startSpeak: (emotion?: string) => void
+  
+  /** 停止说话 */
+  stopSpeak: () => void
+  
+  /** 追加字幕文本（支持流式，仅 web 平台） */
+  appendSubtitle?: (text: string) => void
+  
+  /** 替换字幕文本（仅 web 平台） */
+  setSubtitle?: (text: string) => void
+  
+  /** 清空字幕（仅 web 平台） */
+  clearSubtitle?: () => void
+}
+
+/**
+ * 内部 Character 接口
+ * 包含所有底层 API，仅供内部使用
+ * @internal
+ */
+export interface CharacterInternal extends Character {
+  /** 动画剪辑列表（内部使用） */
+  clips: any[] | null
+  /** 根据 ID 获取动画剪辑（内部使用） */
+  getClip: (id: string) => any | null
+  /** 动画 Map (id -> clip)（内部使用） */
+  animationsMap: Map<string, any>
+  /** AnimationMixer 实例（内部使用） */
+  mixer: any | null
+  
+  // 底层动画控制（内部使用）
+  play: (animationId: string, options?: { loop?: boolean; fadeIn?: number; fadeOut?: number }) => void
+  stop: (fadeOut?: number) => void
+  pause: () => void
+  resume: () => void
+  getCurrentAnimation: () => string | null
+  isPlaying: () => boolean
+  isSpeaking: () => boolean
+  
+  // 情绪和表情控制（内部使用）
+  setMood: (mood: string) => void
+  applyEmotion: (emotion: string) => void
+  setMorphWeight: (morphName: string, value: number) => void
+  setDualMorph: (baseName: string, value: number) => void
+  
+  // 程序化动画开关（内部使用）
+  setHeadSwayEnabled: (enabled: boolean) => void
+  setBlinkingEnabled: (enabled: boolean) => void
+  setLipSyncEnabled: (enabled: boolean) => void
+}
+
+/**
+ * 覆盖层配置（UI 相关）
+ * 字幕通过 Character.appendSubtitle/setSubtitle/clearSubtitle 控制
+ */
+export interface OverlayConfig {
+  /** 是否显示浮层 */
+  show?: boolean
+  /** 是否显示说话按钮 */
+  showSpeakButton?: boolean
+  /** 是否正在加载/连接 */
+  isLoading?: boolean
+  /** 是否已连接 */
+  isConnected?: boolean
+  /** 按钮点击回调 */
+  onButtonClick?: () => void
+  /** 字幕样式 */
+  subtitleStyle?: any
+  /** 浮层容器样式 */
+  style?: any
+}
+
+/**
+ * CharacterView Props 接口
+ * 平台包需要实现这个接口
+ */
+export interface CharacterViewProps {
+  // 核心配置（必需）
+  /** 模型配置 */
+  model: ModelLoadConfig
+  /** 动画状态机配置 */
+  animationStates?: AnimationStatesConfig
+  
+  // 初始状态
+  /** 初始状态（默认 'idle'） */
+  initialState?: string
+  /** 初始情绪（默认 'neutral'） */
+  initialMood?: string
+  /** 是否启用欢迎动画 */
+  enableWelcome?: boolean
+  
+  // 场景配置
+  /** 场景配置（灯光、相机等） */
+  sceneConfig?: SceneConfig
+  /** 轨道控制器配置 */
+  controlsConfig?: OrbitControlsConfig
+  
+  // UI 配置
+  /** 覆盖层配置（字幕、按钮等） */
+  overlay?: OverlayConfig
+  /** Canvas 样式 */
+  style?: any
+  /** Canvas className */
+  className?: string
+  
+  // 扩展内容
+  /** 额外的 3D 场景内容 */
+  children?: ReactNode
+  
+  // 回调
+  /** 角色加载完成 */
+  onReady?: (character: Character) => void
+  /** 状态变化 */
+  onStateChange?: (state: string, mood: string) => void
+  /** 错误处理 */
+  onError?: (error: Error) => void
+}
+

package/src/types/index.ts

@@ -0,0 +1,197 @@
+/**
+ * 光源配置
+ */
+export interface LightConfig {
+  /** 环境光强度 */
+  ambientIntensity?: number
+  /** 点光源配置 */
+  pointLight?: {
+    position?: [number, number, number]
+    intensity?: number
+  } | null
+  /** 方向光配置 */
+  directionalLight?: {
+    position?: [number, number, number]
+    intensity?: number
+  } | null
+}
+
+/**
+ * GridHelper 配置
+ */
+export interface GridHelperConfig {
+  /** 是否显示网格 */
+  visible?: boolean
+  /** 网格大小 */
+  size?: number
+  /** 网格分割数 */
+  divisions?: number
+  /** 中心线颜色 */
+  centerLineColor?: string
+  /** 网格线颜色 */
+  gridColor?: string
+}
+
+/**
+ * 3D 场景配置
+ */
+export interface SceneConfig {
+  /** 背景颜色 */
+  backgroundColor?: string
+  /** 环境光强度（已废弃，使用 lights.ambientIntensity） */
+  ambientLightIntensity?: number
+  /** 光源配置 */
+  lights?: LightConfig
+  /** 相机位置 */
+  cameraPosition?: [number, number, number]
+  /** 相机视野角度 */
+  fov?: number
+  /** GridHelper 配置 */
+  gridHelper?: GridHelperConfig
+}
+
+/**
+ * OrbitControls 配置
+ */
+export interface OrbitControlsConfig {
+  /** 是否启用阻尼 */
+  enableDamping?: boolean
+  /** 阻尼系数 */
+  dampingFactor?: number
+  /** 是否允许旋转 */
+  enableRotate?: boolean
+  /** 是否允许缩放 */
+  enableZoom?: boolean
+  /** 是否允许平移 */
+  enablePan?: boolean
+  /** 最小距离 */
+  minDistance?: number
+  /** 最大距离 */
+  maxDistance?: number
+  /** 最小极角 */
+  minPolarAngle?: number
+  /** 最大极角 */
+  maxPolarAngle?: number
+  /** 控制器目标点（摄像机看向的位置） */
+  target?: [number, number, number]
+}
+
+/**
+ * 动画配置
+ */
+export interface AnimationConfig {
+  /** 动画 ID（用于重命名） */
+  id: string
+  /** 动画文件路径 (Web: URL string, Native: require() 结果或 Asset URI string) */
+  path: string | number
+  /** 动画描述（可选） */
+  description?: string
+}
+
+/**
+ * 动画状态机配置
+ */
+export interface AnimationStateConfig {
+  /** 
+   * 状态下的动画列表
+   * State 决定播放哪些动画，Mood 决定面部表情
+   */
+  animations: string[]
+  /** UI 显示标签（可选） */
+  label?: string
+  /** UI 显示图标（可选） */
+  icon?: string
+  /** 状态配置 */
+  config?: {
+    /** 是否循环播放 */
+    loop?: boolean
+    /** 持续时间（毫秒），用于自动切换到下一个动画 */
+    duration?: number
+    /** 淡入时间（秒） */
+    fadeIn?: number
+    /** 淡出时间（秒） */
+    fadeOut?: number
+    /** 是否随机播放（从动画列表中） */
+    random?: boolean
+  }
+}
+
+/**
+ * 动画状态机总配置
+ */
+export interface AnimationStatesConfig {
+  [state: string]: AnimationStateConfig
+}
+
+/**
+ * 模型加载配置
+ */
+export interface ModelLoadConfig {
+  /** 模型路径 (Web: URL string, Native: require() 结果或 Asset URI string) */
+  path: string | number
+  /** 缩放比例 */
+  scale?: number | [number, number, number]
+  /** 位置偏移 */
+  position?: [number, number, number]
+  /** 旋转角度 */
+  rotation?: [number, number, number]
+  /** 是否启用阴影 */
+  castShadow?: boolean
+  /** 是否接收阴影 */
+  receiveShadow?: boolean
+  /** 动画配置列表 */
+  animations?: AnimationConfig[]
+}
+
+/**
+ * 模型实例配置
+ */
+export interface ModelInstance {
+  /** 模型 ID */
+  id: string
+  /** 模型配置 */
+  config: ModelLoadConfig
+  /** 是否可见 */
+  visible?: boolean
+}
+
+/**
+ * 3D 场景状态
+ */
+export interface SceneState {
+  /** 是否已加载 */
+  loaded: boolean
+  /** 加载进度 (0-1) */
+  progress?: number
+  /** 错误信息 */
+  error?: Error | null
+}
+
+/**
+ * 头部微动参数
+ */
+export interface HeadSwayParams {
+  /** 摆动速度 */
+  speed: number
+  /** 摆动范围（弧度） */
+  range: number
+  /** 俯仰偏移（弧度） */
+  pitchOffset: number
+}
+
+/**
+ * 情绪表情配置
+ */
+export interface EmotionConfig {
+  /** 情绪名称 */
+  emotion: string
+  /** 头部微动参数 */
+  headSway?: HeadSwayParams
+  /** Morph targets 配置 */
+  morphs?: {
+    [morphName: string]: number
+  }
+}
+
+// Character 接口（从独立文件导出）
+export type { Character, CharacterViewProps, CharacterInternal, OverlayConfig } from './character'

package/src/utils/characterUtils.ts

@@ -0,0 +1,156 @@
+import type { Object3D, Bone, SkinnedMesh } from 'three'
+
+/**
+ * 查找模型中的头部骨骼（支持标准 Humanoid 骨骼命名）
+ */
+export function findHeadBone(model: any): Bone | null {
+  if (!model?.scene) return null
+
+  const headBoneNames = ['Head', 'head', 'mixamorig:Head', 'mixamorigHead']
+  
+  let headBone: Bone | null = null
+  model.scene.traverse((child: any) => {
+    if (child.isBone && headBoneNames.includes(child.name)) {
+      headBone = child as Bone
+    }
+  })
+
+  return headBone
+}
+
+/**
+ * 查找模型中所有包含 morph targets 的 SkinnedMesh
+ */
+export function findMorphTargetMeshes(model: any): SkinnedMesh[] {
+  if (!model?.scene) return []
+
+  const meshes: SkinnedMesh[] = []
+  model.scene.traverse((child: any) => {
+    if (child.isSkinnedMesh && child.morphTargetDictionary && child.morphTargetInfluences) {
+      meshes.push(child as SkinnedMesh)
+    }
+  })
+
+  return meshes
+}
+
+/**
+ * 设置单个 Morph Target 的权重
+ */
+export function setMorphWeight(
+  meshes: SkinnedMesh[],
+  morphName: string,
+  value: number
+): void {
+  meshes.forEach(mesh => {
+    const index = mesh.morphTargetDictionary?.[morphName]
+    if (index !== undefined && mesh.morphTargetInfluences) {
+      mesh.morphTargetInfluences[index] = Math.max(0, Math.min(1, value))
+    }
+  })
+}
+
+/**
+ * 设置双侧 Morph Target（ARKit 标准，如 eyeBlinkLeft/eyeBlinkRight）
+ */
+export function setDualMorph(
+  meshes: SkinnedMesh[],
+  baseName: string,
+  value: number
+): void {
+  const leftName = `${baseName}Left`
+  const rightName = `${baseName}Right`
+  
+  setMorphWeight(meshes, leftName, value)
+  setMorphWeight(meshes, rightName, value)
+}
+
+/**
+ * 重置所有 lip-sync 相关的 morph targets
+ */
+export function resetLipSyncMorphs(meshes: SkinnedMesh[]): void {
+  // 基础嘴部 morphs
+  setMorphWeight(meshes, 'jawOpen', 0)
+  setDualMorph(meshes, 'mouthFunnel', 0)
+
+  // 其他嘴部 morphs
+  const mouthMorphs = [
+    'mouthClose',
+    'mouthPucker',
+    'mouthLeft',
+    'mouthRight',
+    'mouthRollLower',
+    'mouthRollUpper',
+    'mouthShrugLower',
+    'mouthShrugUpper',
+    'mouthStretch',
+    'mouthPress',
+    'mouthDimple',
+    'mouthLowerDown',
+    'mouthUpperUp',
+  ]
+
+  mouthMorphs.forEach(morphName => {
+    setMorphWeight(meshes, morphName, 0)
+    setDualMorph(meshes, morphName, 0)
+  })
+
+  // 重置眨眼
+  setDualMorph(meshes, 'eyeBlink', 0)
+}
+
+/**
+ * 获取情绪对应的头部微动参数
+ */
+export function getEmotionHeadSwayParams(emotion: string) {
+  const D2R = Math.PI / 180
+
+  switch (emotion) {
+    case 'happy':
+      return { speed: 1.8, range: 7 * D2R, pitchOffset: -5 * D2R }
+    case 'sad':
+      return { speed: 0.6, range: 3 * D2R, pitchOffset: 8 * D2R }
+    case 'excited':
+      return { speed: 2.2, range: 9 * D2R, pitchOffset: -3 * D2R }
+    case 'neutral':
+    default:
+      return { speed: 1.0, range: 5 * D2R, pitchOffset: 0 }
+  }
+}
+
+/**
+ * 应用情绪表情 (ARKit morph targets)
+ */
+export function applyEmotionMorphs(
+  meshes: SkinnedMesh[],
+  emotion: string
+): void {
+  // 重置基础表情
+  const morphsToReset = ['mouthSmile', 'mouthFrown', 'cheekSquint', 'eyeSquint', 'browDown']
+  morphsToReset.forEach(key => setDualMorph(meshes, key, 0))
+  setMorphWeight(meshes, 'browInnerUp', 0)
+
+  // 应用情绪表情
+  switch (emotion) {
+    case 'happy':
+      setDualMorph(meshes, 'mouthSmile', 0.7)
+      setDualMorph(meshes, 'cheekSquint', 0.5)
+      setDualMorph(meshes, 'eyeSquint', 0.2)
+      break
+    case 'sad':
+      setDualMorph(meshes, 'mouthFrown', 0.6)
+      setMorphWeight(meshes, 'browInnerUp', 0.7)
+      break
+    case 'excited':
+      setDualMorph(meshes, 'mouthSmile', 0.9)
+      setDualMorph(meshes, 'cheekSquint', 0.7)
+      setDualMorph(meshes, 'eyeSquint', 0.3)
+      setMorphWeight(meshes, 'browInnerUp', 0.4)
+      break
+    case 'neutral':
+    default:
+      setDualMorph(meshes, 'mouthSmile', 0.1)
+      break
+  }
+}
+

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020", "DOM"],
+    "jsx": "react-jsx",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+

package/tsup.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: ['src/index.ts', 'src/internal.ts'],
+  format: ['cjs', 'esm'],
+  dts: true,
+  external: ['react', 'react-native', 'three', '@react-three/fiber', '@react-three/drei'],
+  // 使用 React 17+ 的新 JSX runtime
+  esbuildOptions(options) {
+    options.jsx = 'automatic'
+  },
+})
+