155 lines
3.2 KiB
Markdown
155 lines
3.2 KiB
Markdown
# 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, // 形态键强度缩放
|
||
minBlendShapeValue: 0.1, // ignore values below this to avoid spikes
|
||
deltaThreshold: 0.002, // skip setInfluence when delta is tiny
|
||
prewarmFrameCount: 30, // number of frames used for warmup
|
||
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` 进行动画更新
|
||
- Blendshape values below 0.1 are zeroed to reduce CPU load
|
||
- Startup prewarms prewarmFrameCount frames to hide the first-frame hitch
|
||
- 空闲动画会在主动画播放时自动暂停
|
||
- 所有形态键值范围为 0-1
|