BlendShape Animator SDK 使用文档

概述

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

核心概念

形态键适配器 (Morph Target Adapter)

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

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

初始化配置

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
  }
};

使用示例

// 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) 更新配置参数

动画数据格式

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

注意事项

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

2.9 KiB Raw Blame History Unescape Escape