For the complete documentation index, see llms.txt. This page is also available as Markdown.

为角色添加你自己的动画

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

使用您自己的 GLB 文件或直接从 Mixamo 为 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 如果身体也列出了该名称,则会替换身体的片段。一个文件可以包含多个动画;对于您想从中使用的每个名称,都将其列出一次。

加载您的片段

传入 animations ,在创建角色时传入它。在 React 中,将其作为 prop 传入;请保持该对象稳定,因为角色只读取一次,并且在其变化时不会重新加载。

src/App.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}
    />
  )
}
src/character.ts
import { createCharacter } from '@convai/embody'

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

此处 Idle 会替换身体自身的待机动画,而 Wave 会添加到身体的片段中。文件会与身体并行加载。位于其他主机上的文件需要允许您的页面访问的 CORS 标头。

使用来自 Mixamo 和其他骨骼的动画

为其他骨骼制作的片段会在角色加载时重定向到角色身体,因此您可以直接传入 Mixamo 下载文件。

Convai Embody 可识别三种骨骼:

骨骼
识别依据

Mixamo

诸如以下的骨骼名称 mixamorig:Hips,可带任意 mixamorig 前缀或不带前缀

Rigify

诸如以下的变形骨骼 DEF-hips, DEF-thigh.L,以及 DEF-upper_arm.L

Unreal Engine mannequin

诸如以下的骨骼名称 pelvis, spine_01,以及 thigh_l。这些是 MetaHuman 名称,因此 mannequin 片段会在身体上按制作时的方式播放,无需重定向。

来自可识别骨骼的文件不需要匹配的片段名称。当文件中没有与键同名的动画时,会以该键的名称使用其唯一动画;Mixamo 将每个片段命名为 mixamo.com,因此这就是使 Mixamo 文件可用的原因。包含多个动画的文件仍需要键匹配其中一个动画。

重定向会根据源骨骼从各自静止姿势起的移动方式来移动每根骨骼,因此以 T 姿势制作的片段能在绑定为 A 姿势的身体上正确播放。它还会使片段适配身体:

  • 髋部移动会按两套骨骼髋部高度的比例缩放,因此片段会以身体的尺寸播放。

  • 脚部会从身体自身的平坦站姿开始移动,颈部和头部则基于身体自身的构造,而非复制源骨骼的构造。

  • 肘部和手部会保持在躯干和大腿外侧。为较瘦身体制作的片段,否则会使手部停留在较宽身体的内部。

  • 在角色站立的片段中,躯干最多向前倾斜 6 度,弯曲的膝盖会被伸直,较低的肩膀最多会被抬高 6 度,因为 Mixamo 的站立片段在 MetaHuman 身体上会后仰。髋部下沉的片段,例如跪姿或坐姿,会保持其姿势。

仅当 URL 以以下后缀结尾时才会加载 FBX 支持: .fbx,因此从不使用 FBX 的应用不会包含 FBX 加载器。没有该扩展名的 URL,例如 blob: URL,会被作为 glTF 读取。

从 Mixamo 下载时,请选择 FBX Binary (.fbx) 和 Without Skin:重定向器只读取骨骼,而没有网格的文件会小得多。对于走路或跑步,请勾选 In Place ,以免片段将角色带离原处。

选择最先播放的片段

角色加载时,会播放名为 idle的片段,不区分大小写。没有此类片段的身体会播放其第一个片段,因此角色不会停留在绑定姿势。使用 idleClip 来选择其他片段,或使用 false 以开始时不播放任何片段。

角色没有的名称不会播放任何内容,而不会使用替代片段。

播放和交叉淡入淡出片段

character.animations 控制播放。它一次播放一个片段,并从当前片段混合到下一个片段。

crossfadeTo 在该片段已经播放时不会执行任何操作。角色没有的片段名称会抛出错误,并列出它拥有的名称。

在 React 中,从以下位置获取角色: onReady:

onReady 会针对每个加载的角色运行一次,因此在此处完成的设置不会在组件重新渲染时重复执行。

角色说话时切换到说话片段

Convai Embody 会在角色说话时移动嘴部,但不会改变身体片段。要播放说话片段,请监听客户端的 speakingChange 事件并进行交叉淡入淡出。

无论播放哪个片段,唇形同步、视线和眨眼都会继续叠加运行,因此说话片段只需移动身体。

在角色加载后添加片段

要稍后添加片段,请自行加载文件并注册其动画。 register 会针对每个片段返回保留了多少轨道以及丢弃了多少轨道。

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

验证片段

运行应用。

故障排查

症状
原因与修复

[embody] 未知片段 "Wave"(拥有:Hi、Idle、…)

没有名为 Wave 的动画被加载。请检查 animations 中的键是否与文件内动画的名称完全一致,逐字母匹配。

控制台警告 片段 "…":N/M 个轨道指向不存在的骨骼——已丢弃

该片段为模型没有的骨骼制作了动画,例如额外的手指、头发或辅助骨骼。这些轨道会被跳过,其余部分仍会播放。从更丰富的绑定导出的片段出现这种情况是预期的;如果片段完全不动,则它是在不同的骨骼上制作的。

片段正在播放,但身体不动或移动错误

该动画是在既非 MetaHuman 骨骼、也非 Convai Embody 可从中重定向的骨骼(Mixamo、Rigify)上制作的。请在您的 3D 工具中将其重定向到 MetaHuman 骨骼,然后再次导出。

控制台警告 片段 "…":从 mixamo 重定向失败

文件的骨骼已被识别,但无法测量,例如其静止姿势中髋部不位于脚部上方。其他片段仍会加载。请从源文件重新导出该文件。

文件从未加载

查看浏览器的网络面板。位于其他主机上的文件需要允许您的页面访问的 CORS 标头。

您的走路片段使角色走离原处

片段会按制作时的方式播放,包括其中烘焙的任何前进移动。默认身体的 Walk 会以原地方式导出;对于保持在您放置位置的角色,也请以相同方式导出您的动画。

下一步

使用你自己的 3D 模型createCharacter 参考

最后更新于

这有帮助吗?