# BlendShape Animator SDK 使用文档

## 概述

BlendShapeAnimator 是一个引擎无关的形态键动画SDK，可以与任何3D引擎配合使用。

## 核心概念

### 形态键适配器 (Morph Target Adapter)

适配器是连接SDK和3D引擎的桥梁，需要实现以下接口：

```javascript
{
  setInfluence(name, value) {
    // 设置形态键的影响值 (0-1)
  },
  getInfluence(name) {
    // 获取形态键的当前影响值
    return 0;
  }
}
```

### 初始化配置

```javascript
const config = {
  blendShapeScale: 1.0,        // 形态键强度缩放
  dataFps: 30,                 // 动画数据帧率
  onStatusChange: (type, msg) => {
    // 状态变化回调
  },
  blinkParams: {               // 眨眼参数
    intervalMin: 2000,
    intervalMax: 5000,
    duration: 150,
    speed: 100
  },
  eyeLookParams: {             // 眼球移动参数
    intervalMin: 2000,
    intervalMax: 6000,
    durationMin: 1000,
    durationMax: 2500,
    speed: 250
  },
  expressionParams: {          // 表情参数
    intervalMin: 3000,
    intervalMax: 8000,
    speed: 400
  }
};
```

## 使用示例

```javascript
// 1. 创建适配器
const adapter = new BabylonMorphTargetAdapter();

// 2. 初始化SDK
const animator = new BlendShapeAnimator({
  blendShapeScale: 1.0,
  onStatusChange: (type, msg) => console.log(type, msg)
});

// 3. 设置适配器
animator.setMorphTargetAdapter(adapter);

// 4. 加载模型后构建缓存
BABYLON.SceneLoader.ImportMesh("", "./", "model.glb", scene, (meshes) => {
  adapter.buildCache(meshes);
});

// 5. 加载并播放动画
animator.loadAnimationFrames(animationData.frames);
animator.playAnimation();
```

## API 参考

### 核心方法

**`setMorphTargetAdapter(adapter)`**
设置形态键适配器

**`loadAnimationFrames(frames)`**
加载动画帧数据

**`appendAnimationFrames(frames)`**
追加动画帧数据（流式场景）

**`startStreaming()`**
开启流式模式，允许边接收边播放

**`endStreaming()`**
结束流式模式

**`playAnimation()`**
播放动画

**`stopAnimation()`**
停止动画

**`setIdleAnimation(name, target, duration, easing)`**
设置空闲动画
- `name`: 形态键名称
- `target`: 目标值 (0-1)
- `duration`: 持续时间 (ms)
- `easing`: 缓动函数名称

### 空闲动画控制

**`toggleBlink(enabled)`**
开启/关闭随机眨眼

**`toggleEyeLook(enabled)`**
开启/关闭眼球移动

**`toggleRandomExpression(enabled)`**
开启/关闭随机表情

### 配置更新

**`updateConfig(key, value)`**
更新配置参数

## 动画数据格式

```javascript
{
  frames: [
    {
      blendShapes: {
        "jawOpen": 0.5,
        "mouthSmileLeft": 0.3,
        "mouthSmileRight": 0.3
      }
    }
  ]
}
```

## 注意事项

- 形态键名称会自动转换为小写进行匹配
- SDK使用 `requestAnimationFrame` 进行动画更新
- 空闲动画会在主动画播放时自动暂停
- 所有形态键值范围为 0-1