init

examples/3d/SDK_USAGE.md

@@ -0,0 +1,140 @@
+# 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)`**
+加载动画帧数据
+
+**`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