> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/add-your-own-animations.md).

# 为角色添加你自己的动画

将你自己的动画片段加载到 Convai Embody 角色上，包括 Mixamo FBX 文件，对其进行播放和交叉淡化，并在角色说话时切换到说话动画片段。

为 Convai Embody 角色添加你自己的动画，例如挥手、做手势或不同的待机动作。动画可以来自你自己的 GLB 文件，也可以直接来自 Mixamo。如果角色模型自带的动画不是你想要的，请使用本页。完成后，角色会播放你的动画片段，在片段之间进行交叉淡化，并在说话时切换到说话动画片段。

### 前提条件

* 已渲染角色的页面。请参阅 [向 React 应用添加 3D 角色](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/add-a-3d-character-to-a-react-app.md) 或 [向 three.js 场景添加 3D 角色](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/add-a-3d-character-to-a-three-js-scene.md).
* 以 GLB、glTF 或 FBX 文件形式提供的动画。使用 Unreal Engine MetaHuman 骨架制作的动画片段， `convai-mha-1` 绑定，可以直接播放。使用 Mixamo 或 Rigify 骨架制作的动画片段会在角色加载时重定向到角色身体上；请参阅 [使用来自 Mixamo 和其他骨架的动画](#use-animations-from-mixamo-and-other-skeletons).
* 对于使用 MetaHuman 骨架的文件，需要提供文件中每个动画的名称。Convai Embody 根据名称查找动画片段，而不是根据文件名查找。

### 如何查找动画片段

角色的动画片段来自两个位置，Convai Embody 会在创建角色时加载这两个位置中的内容：

1. **角色的身体。** 其清单按名称和文件列出动画片段。男性默认身体自带 `Hi`, `Idle`, `Talk`，以及 `Walk`。女性默认身体自带 `Hi`, `Idle`, `Talk`, `walk`, `SitDown`, `SitIdle`，以及 `StandUp`。名称区分大小写，因此请读取 `character.animations.names` ，不要自行假设。
2. **该 `animations` 选项。** 从片段名称到包含同名动画的 GLB、glTF 或 FBX 文件 URL 的映射。

一个 `animations` 中的名称，如果主体也列出了该名称，则会替换主体中的片段。一个文件可以包含多个动画；对于要从中使用的每个动画名称，都应将该文件列出一次。

{% hint style="warning" %}
animations `中的键` 必须与 GLB 内部的动画名称一致。 `animations: { Wave: '/clips/gestures.glb' }` 如果该文件中的动画名为 `wave_01`。在 glTF 查看器或 Blender 中打开文件即可查看名称。
{% endhint %}

### 加载动画片段

传入 `animations` 在创建角色时传入。在 React 中，将其作为 prop 传入；请保持对象稳定，因为角色只会读取一次，之后即使对象发生变化也不会重新加载。

{% tabs %}
{% tab title="React" %}
{% code title="src/App.tsx" %}

```tsx
import { ConvaiCharacter } from '@convai/embody/react'

const ANIMATIONS = {
  Wave: '/animations/gestures.glb',
  Idle: '/animations/calm-idle.glb',
}

export default function App() {
  return (
    <ConvaiCharacter
      token={token}
      characterId="YOUR_CHARACTER_ID"
      animations={ANIMATIONS}
    />
  )
}
```

{% endcode %}
{% endtab %}

{% tab title="three.js" %}
{% code title="src/character.ts" %}

```typescript
import { createCharacter } from '@convai/embody'

const character = await createCharacter({
  token,
  characterId: 'YOUR_CHARACTER_ID',
  animations: {
    Wave: '/animations/gestures.glb',
    Idle: '/animations/calm-idle.glb',
  },
})
```

{% endcode %}
{% endtab %}
{% endtabs %}

此处 `Idle` 会替换身体自带的待机动画，而 `Wave` 则会添加到身体的动画片段中。动画文件会与身体模型并行加载。若文件托管在其他主机上，该主机必须设置允许你所在页面访问的 CORS 标头。

### 使用 Mixamo 和其他骨架的动画

角色加载时，为其他骨架制作的动画片段会重定向到角色身体上，因此可以直接传入 Mixamo 下载的文件。

```typescript
const character = await createCharacter({
  token,
  characterId: 'YOUR_CHARACTER_ID',
  animations: {
    Wave: '/animations/Waving.fbx',
    Think: '/animations/Thinking.fbx',
  },
})
```

Convai Embody 可识别三种骨架：

| 骨架                 | 识别依据                                                                                          |
| ------------------ | --------------------------------------------------------------------------------------------- |
| Mixamo             | 骨骼名称，例如 `mixamorig:Hips`，带有任意 `mixamorig` 前缀或不带前缀                                             |
| Rigify             | 变形骨骼，例如 `DEF-hips`, `DEF-thigh.L`和 `DEF-upper_arm.L`                                          |
| Unreal Engine 人形骨架 | 骨骼名称，例如 `pelvis`, `spine_01`和 `thigh_l`。这些是 MetaHuman 使用的骨骼名称，因此人形骨架动画片段会按原始姿势直接应用到身体上，无需重定向。 |

使用可识别骨架的文件时，动画片段名称无需与键名一致。如果文件中没有与键名同名的动画，则会将文件中唯一的动画以该键名使用；Mixamo 会将每个动画片段命名为 `mixamo.com`，因此 Mixamo 文件才能正常使用。如果文件包含多个动画，则仍需确保键名与其中一个动画名称一致。

重定向会根据每个骨架自身的静止姿势，按源骨骼的运动方式移动对应骨骼，因此，为 T 姿势制作的动画片段也能在绑定为 A 姿势的身体上正确播放。它还会使动画片段适配身体：

* 髋部移动会按两个骨架髋部高度的比例缩放，因此动画片段会以符合身体尺寸的幅度播放。
* 脚部移动以身体自身的平站姿为基准；颈部和头部则根据身体自身的体型调整，而不是照搬源骨架。
* 肘部和手部会保持在躯干和大腿之外。否则，为较纤瘦身体制作的动画片段会让双手停在较宽身体的内部。
* 对于角色站立的动画片段，躯干最多向前倾斜 6 度，弯曲的膝盖会伸直，低垂的肩膀最多抬高 6 度，因为 Mixamo 的站立动画片段应用于 MetaHuman 身体时会向后倾斜。如果动画片段中髋部下沉（例如跪姿或坐姿），则会保留原有姿势。

只有当 URL 以以下内容结尾时，才会加载 FBX 支持 `.fbx`，因此从不使用 FBX 的应用不会打包 FBX 加载器。没有此扩展名的 URL（例如 `blob:` URL）会被作为 glTF 读取。

{% hint style="info" %}
从 Mixamo 下载时，选择 **FBX Binary (.fbx)** 和 **Without Skin**：重定向器只读取骨架，而且不包含网格的文件要小得多。对于行走或奔跑动画，请勾选 **In Place** ，以免动画片段带着角色移动。
{% endhint %}

### 选择首先播放的动画片段

角色加载后，会播放名为 `idle`的动画片段（不区分大小写）。如果角色没有此名称的动画片段，就会播放第一个动画片段，因此角色不会一直保持在绑定姿势。使用 `idleClip` 指定其他动画片段，或使用 `false` 让角色在加载时不播放动画片段。

```typescript
const character = await createCharacter({ token, characterId, idleClip: 'SitIdle' })
```

如果指定的名称不是角色拥有的动画片段，就不会播放任何动画，而不会改播其他片段。

### 播放和交叉淡化动画片段

`character.animations` 用于控制播放。它一次播放一个动画片段，并从当前片段混合过渡到下一个片段。

```typescript
// 从当前播放的片段混合过渡到 Wave，播放一次，然后返回 Idle。
character.animations.crossfadeTo('Wave', { once: true, thenBackTo: 'Idle' })

// 循环播放一个片段，并在半秒内混合淡入。
character.animations.crossfadeTo('Walk', { duration: 0.5 })

character.animations.names   // 角色拥有的所有动画片段
character.animations.playing // 当前播放的动画片段；若没有则为 null
```

`crossfadeTo` 如果该动画片段已经在播放，则不会执行任何操作。如果角色没有指定名称的动画片段，就会抛出错误，并列出角色实际拥有的动画片段名称。

在 React 中，通过 `onReady`:

```tsx
<ConvaiCharacter
  token={token}
  characterId="YOUR_CHARACTER_ID"
  animations={ANIMATIONS}
  onReady={(character) => character.animations.crossfadeTo('Wave', { once: true, thenBackTo: 'Idle' })}
/>
```

`onReady` 会针对每个加载的角色运行一次，因此在其中执行的设置不会因组件重新渲染而重复。

### 角色说话时切换到说话动画片段

Convai Embody 会在角色说话时驱动嘴部动作，但不会切换身体动画片段。要播放说话动画片段，请监听客户端的 `speakingChange` 事件并进行交叉淡化。

```typescript
const stop = character.client?.on('speakingChange', (speaking) => {
  character.animations.crossfadeTo(speaking ? 'Talk' : 'Idle')
})

// 角色离开时：
stop?.()
```

无论播放哪个动画片段，口型同步、视线和眨眼都会持续运行，因此说话动画片段只需驱动身体动作。

### 角色加载后添加动画片段

如需稍后添加动画片段，请自行加载文件并注册其中的动画。 `register` 会针对每个动画片段返回保留和丢弃的轨道数量。

```typescript
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'
import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js'

const loader = new GLTFLoader()
const draco = new DRACOLoader()
draco.setDecoderPath('https://www.gstatic.com/draco/versioned/decoders/1.5.7/')
loader.setDRACOLoader(draco)

const gltf = await loader.loadAsync('/animations/dance.glb')
draco.dispose()

character.animations.register(gltf.animations)
character.animations.crossfadeTo('Dance', { once: true, thenBackTo: 'Idle' })
```

仅当文件经过 Draco 压缩时，才需要 Draco 解码器。

### 验证动画片段

运行应用。

{% hint style="success" %}
`character.animations.names` 会列出动画片段名称，角色会从你选择的待机动画开始，并通过交叉淡化平滑过渡到你的动画片段。
{% endhint %}

### 故障排查

| 症状                                                           | 原因与解决方法                                                                                                     |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `[embody] unknown clip "Wave" (have: Hi, Idle, …)`           | 未加载名为 `Wave` 的动画。请检查 `animations` 中的键是否与文件内的动画名称完全一致，逐字母核对。                                                 |
| 控制台显示警告 `clip "…": N/M tracks target absent bones — dropped` | 该动画片段为模型不存在的骨骼制作了动画，例如额外的手指、头发或辅助骨骼。这些轨道会被跳过，其余部分仍会播放。对于从更丰富的骨架导出的动画片段，这是正常现象；如果动画片段完全没有动作，则说明它是在不同的骨架上制作的。 |
| 动画片段在播放，但身体没有动作或动作不正确                                        | 该动画是在既不是 MetaHuman 骨架、也不是 Convai Embody 支持重定向的骨架（Mixamo、Rigify）上制作的。请在 3D 工具中将其重定向到 MetaHuman 骨架，然后重新导出。    |
| 控制台显示警告 `clip "…": retargeting from mixamo failed`           | 文件的骨架已被识别，但无法测量，例如静止姿势下髋部没有高于脚部。其他动画片段仍会加载。请从源文件重新导出。                                                       |
| 文件始终无法加载                                                     | 查看浏览器的网络面板。若文件位于其他主机上，该主机必须提供允许你的页面访问的 CORS 标头。                                                             |
| 行走动画片段会让角色偏离原位                                               | 动画片段会按制作时的效果播放，包括其中烘焙的任何向前移动。默认角色的 `Walk` 是以原地行走的方式导出的；请用相同方式导出你的动画，让角色保持在你放置的位置。                           |

### 后续步骤

{% content-ref url="/pages/7896d1fe790aa3f610fbff28930f360eaa6809e8" %}
[使用你自己的 3D 模型](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/use-your-own-3d-model.md)
{% endcontent-ref %}

{% content-ref url="/pages/b60906ed5049da52cc6ddb85571a9101f1eacdb4" %}
[createCharacter 参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/createcharacter-reference.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/add-your-own-animations.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
