> 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/convai-unity-sdk/embodiment/body-animation/troubleshooting.md).

# 身体动画故障排查

诊断无动作、T 姿势、移动不同步、与 Animator Controller 冲突、动作从不触发以及指向手势偏移的问题。

大多数身体动画问题都归因于少数几种设置缺失之一，而且 `ConvaiBodyAnimationController`' 的检查器会在你打开控制台之前就按名称报告其中的大多数。本页涵盖清单未能完全解释的症状、 `AnimTraceVerbosity` 用于更深入诊断的调节项，以及对每一种常见故障的完整参考。

### 使用 AnimTraceVerbosity 进行诊断

`ConvaiBodyAnimationConfig`的 **跟踪详细级别** 字段通过以下枚举控制角色向控制台输出多少内容， `AnimTraceVerbosity` 枚举： `关闭`, `State`, `详细信息`, `火力全开`。它默认提供为 `关闭`，但仍会记录所有警告和错误——一个会走路和说话的角色会不断切换状态，因此如果控制台里全是日常播放过程的逐条日志，真正的警告就会被淹没而无人阅读。

| 级别      | 它增加的内容                                        |
| ------- | --------------------------------------------- |
| `关闭`    | 无跟踪输出。警告和错误仍会记录。                              |
| `State` | 状态机转换、层所有权变更、动作生命周期以及片段选择——将你正在诊断的那个角色提升到此级别。 |
| `详细信息`  | 增加选择器决策（角度、距离、脚步阶段）、带权重的变体掷取，以及速度扭曲限幅。        |
| `火力全开`  | 增加按节流的逐帧层权重和混合位置转储。信息极其冗长；仅用于短时间调试会话。         |

提高 **跟踪详细级别** 到 `State` 到你正在诊断的角色上，复现症状，然后再把它改回 `关闭`。SDK 自己的 `ConvaiSettings` 日志级别也必须允许该行通过： `State` 日志，在 `信息`, `详细信息`/`火力全开` 中声明所需权限，位置为 `调试`。这些相同的条目也会馈入一个环形缓冲区，为控制器检查器的紧凑 **Live** 条带以及 **Body Animation Editor** 窗口更深层的实时模式提供支持——详细级别也会限制环形缓冲区，因此在 `关闭` 实时界面中仍会显示对话状态、移动状态以及任何警告，但滚动的转换日志需要 `State` 或更高才能填充。

### 症状快速参考

| 症状                  | 可能原因                                                          | 修复方法                                                                           | 验证                                                |
| ------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------- |
| 角色从不进入待机或对语音作出反应    | 没有 `Animator`，不是 Humanoid 头像，或者没有 `ConvaiBodyAnimationSet` 分配 | 添加 Humanoid `Animator`，或将一个动画集分配给该组件或其配置文件                                     | 控制器检查器显示 **Ready** 而不是 **未设置**                    |
| 角色保持 T 姿势           | 与上面相同—— `PlayableGraph` 从未构建，因此 Animator 回退到其绑定姿势             | 与无动作相同的修复                                                                      | 角色在播放模式下显示循环待机                                    |
| 角色滑行、脚部打滑，或双腿与移动不同步 | 行走动画片段没有测量元数据，或者自定义行走提供程序未实现 `IConvaiManagedLocomotion`       | 运行 **测量片段** 该动画集上的接口，或者实现托管行走能力                                                | `LocomotionClipsMissingMetadata` 在设置清单中显示为 `0`    |
| 腿部或手臂抽动，或与预期姿势相互冲突  | Animator 上仍分配着一个运行时 Animator Controller                       | 清除 Animator 的 **Controller** 字段                                                | 该 `rig.redundant-animator-controller` 该问题项会从设置中消失 |
| 某个动作或手势从未播放         | 动作名称与任何 `ActionName`/别名都不匹配，或者调用发生在运行时准备就绪之前                  | 将请求的名称与该动画集编写的名称进行比较（不区分大小写，空格/短横线/下划线等效）；从 `RuntimeReady` 而不是 `Awake`/`Start` | 控制台显示匹配的名称到达 `_actionLayer.Play` ，而不是“没有匹配动作”的警告  |
| 指向手臂指向了错误的位置        | 动画集的指向表中只编写了一个或少数几个方向； `PointAt` 会跳转到角度上最近的那个                 | 编写更多方向性的指向动画片段，覆盖你的场景所需的角度                                                     | 所播放片段编写的偏航/俯仰角与请求方向很接近                            |

### 完全没有动作

一个完全没有动作的角色——没有待机摆动、没有说话手势，什么都没有——几乎总是会失败于控制器自己的检查器在你打开控制台之前报告的三项设置检查之一：

* **在角色根节点下未找到 Animator。** `ConvaiBodyAnimationController` 需要一个 Humanoid `Animator` 来构建其 `PlayableGraph`，因此在没有该组件时模块会保持未激活（`BodyAnimationTroubleshooter.cs:228-230`).
* **Animator 的 avatar 不是有效的 Humanoid 骨架。** 将模型的 **Animation Type** 到 **Humanoid** 在其导入设置中（`BodyAnimationTroubleshooter.cs:238-239`).
* **未分配动画集**，无论是直接分配还是通过配置文件——角色有可以播放的内容，但没有任何东西连接到它（`BodyAnimationTroubleshooter.cs:264-267`).

打开控制器的检查器或 **Convai > 身体动画编辑器**的设置模式；这三项都会以错误级别的问题项报告，并明确指出缺少的具体部分，而不是笼统的失败。

### 角色卡在 T 姿势

当没有任何东西驱动 Animator 时，T 姿势是 Unity 的回退状态——它与完全没有动作有相同的根本原因，而且看起来更明显地不对，因为角色没有可回退的编写待机动作。检查相同的三项条件：一个 Humanoid `Animator`、一个有效的 Humanoid avatar，以及一个已分配的 `ConvaiBodyAnimationSet` ，并且至少包含一个循环待机条目。没有有效待机条目的动画集（`HasAnyIdle` 为 false）即使图本身成功构建后，也会让角色没有任何可混合到的内容。

### 移动与 NavMeshAgent 不同步

这一标题下有两种不同的症状，它们有不同的原因。

**角色根本不会走动。** `ConvaiNavMeshLocomotion.MoveTo` 会记录确切原因并返回 `false`:

```
[ConvaiNavMeshLocomotion] '<name>' 无法行走：它没有站在已烘焙的 NavMesh 上。请为地板烘焙一个 NavMesh（Window > AI > Navigation），并检查角色是否从其上开始。
```

(`ConvaiNavMeshLocomotion.cs:238-242`。）一个附近没有可行走地面的目的地会记录第二条类似警告，指出目的地（`ConvaiNavMeshLocomotion.cs:248-252`），而位于断开 NavMesh 片段上的目的地会记录第三条，指出连接性问题（`ConvaiNavMeshLocomotion.cs:260-264`）。请烘焙一个同时覆盖角色起始位置以及你发送其前往的每个目的地的 NavMesh。

**角色会走，但脚会打滑，或者速度快时步态看起来不对。** 这是一个测量问题，而不是 NavMesh 问题：分配给该动画集的行走动画片段需要先由 Clip Motion Analyzer 测量其地面速度，动画才能跟踪代理的真实速度。设置清单会直接报告这一点：

```
{N} 个行走动画片段尚未测量，因此角色会回退到配置的速度，而不是使用这些片段的真实地面速度——这通常就是脚部打滑的原因。方向性起步和落脚停止也会保持不准确，直到它们的运动被测量。
```

(`BodyAnimationTroubleshooter.cs:359-363`。）重新运行 **测量片段** ——在该动画集自己的检查器中，或在 Body Animation Editor 的内容模式中——在任何行走动画片段更改之后。

### Animator Controller 与图相冲突

`ConvaiBodyAnimationController`的 `PlayableGraph` 在激活时会替换 Animator 的输出，但不会清除留在 Animator 组件上已分配的 Runtime Animator Controller。只要存在一个，设置清单就会报告它：

```
已分配 Animator Controller；身体动画 PlayableGraph 在激活时会替换其输出。请将其移除以避免混淆，或者将其保留为无作用的回退。
```

(`BodyAnimationTroubleshooter.cs:247-249`。）在实践中，遗留的控制器最常表现为腿部或手臂抽动，或者短暂地跳到与图意图不同的姿势。清除 Animator 的 **Controller** 字段——设置清单为这个特定问题提供了一键修复。

### 动作未触发

某个 `PlayAction` 从未播放的调用会以两种方式之一失败，控制台会告诉你是哪一种：

* **运行时尚未准备就绪。** 从以下位置发出的调用 `Awake()`/`Start()`，在 `PlayableGraph` 完成构建之前，会排入一个单一的延迟槽并自动重放——但仅在它过期之前：

  ```
  在动画图准备就绪之前请求了 PlayAction('<name>')——一旦图构建完成，它将自动重放，或在 2 秒后过期。
  ```

  (`ConvaiBodyAnimationController.cs:462-465`。）订阅 `RuntimeReady`，或者先检查 `IsRuntimeBuilt`，不要依赖那个延迟槽来处理任何不能丢失的内容。
* **该名称与任何已编写条目都不匹配。** 匹配不区分大小写，并将空格、短横线和下划线视为等效，但未匹配的名称仍然会失败：

  ```
  PlayAction('<name>')——动画集 '<set display name>' 中没有匹配的动作。
  ```

  (`ConvaiBodyAnimationController.cs:472-473`。）将你的代码或后端动作发送的确切名称与 `动作名称` 和 `别名` 该动画集中编写的字段进行比较。

`PlayAction` 从不返回 `null` 在这两种情况下都——检查 `handle.Failed` 并读取 `handle.FailureReason` ，而不是期待异常。

### 指向看起来不对

`ConvaiBodyAnimationController.PointAt` 会直接失败（`handle.Failed`）仅当目标是 `null`，运行时尚未构建，或者该动画集根本没有编写任何指向动画片段——每种情况都会报告各自的 `FailureReason` (`ConvaiBodyAnimationController.cs:594-667`).

一个能够播放但瞄准错误位置的指向手势并不是失败——这是方向选择方式决定的预期行为。每个 `PointingEntry` 都编写了一个固定的角色本地偏航和俯仰角，并且 `PointAt` 总是播放在角度上最接近请求方向的已编写条目；它不会在条目之间混合，也不会程序化地在条目之间瞄准（`PointingEntry.cs:8-12,84-106`）。只有少数已编写方向的动画集会跳转到最近的那个，这对于明显超出任何已编写角度范围的目标来说可能会明显偏离。请编写更多方向性的指向动画片段，覆盖你的场景实际需要的角度范围。

### 下一步

{% content-ref url="/pages/13dbbe592147612edba60a45974dc24d1b9f3e61" %}
[播放动作和手势](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-animation/play-actions-and-gestures.md)
{% endcontent-ref %}

{% content-ref url="/pages/5e8d8a3b4fe5ee06381a3ed5c6ba13e6f297f706" %}
[身体动画配置参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-animation/config-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/61cfb72bb1467fd3d8cfd00b7d7b8ce11d90740c" %}
[发行说明](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/overview/release-notes.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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-animation/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.