> 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-unreal-engine-plugin/features/character-actions/troubleshoot-character-actions.md).

# 排查角色动作问题

修复 Convai Unreal Engine 插件中不触发的角色动作、移动失败、引用问题和队列停滞。

使用此页面诊断角色动作未触发、中途停止、移动到错误位置或收到空参数的问题。

{% hint style="info" %}
在调试任何动作问题之前，先打开 **输出日志** 。 `ConvaiChatbotComponentLog` 会报告会话、队列和分发消息，包括处理程序缺失警告。 `ConvaiSubsystemLog` 会报告动作配置解析和参数解析消息。 `ConvaiDefinitionsLog` 会报告来自 `Resolve Goal Location`的目标解析和环境进入警告。若要提高日志详细程度，请将以下内容添加到 `DefaultEngine.ini`:

```ini
[Core.Log]
ConvaiChatbotComponentLog=Verbose
ConvaiSubsystemLog=Verbose
ConvaiDefinitionsLog=Verbose
```

{% endhint %}

### 升级后蓝图无法编译

**症状：** 更新插件后，调用 `Invoke Speech` 或 `Invoke Narrative Design Trigger` 的蓝图出现编译错误，或缺少以前具有的输入引脚；读取对象条目移动目标字段的节点也无法再解析该字段。

**原因：** 此次升级移除了这两个节点上的引脚，并弃用了旧的移动目标枚举。每个受影响的节点都需要刷新一次。

**修复方法：** 按照 [迁移到 4.0.0-beta.27](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/overview/migrate-to-4-0-0-beta-27.md)中的说明操作；其中列出了所有已移除的引脚和已重命名的字段，以及需要进行的修改。

**验证：** 所有 Convai 蓝图均可无错误编译，且每个已刷新的节点只显示当前的引脚集。

### 动作未触发

#### 角色会说话，但执行 Follow 或 Move To 时不会移动

**症状：** Convai 确认收到指令，但 NPC 留在原地。

**原因 A：** 未配置 Pawn 移动。

**修复方法：** 在 **内容浏览器**中右键单击角色蓝图，选择 **Convai > Setup Convai Pawn Movement**，然后编译并保存。请参阅 [角色动作快速入门](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/character-actions-quick-start.md).

**验证：** 蓝图具有一个移动组件（`Floating Pawn Movement` 或 `Character Movement`）和一个 **AI 控制器类** 已分配。

***

**原因 B：** NavMesh 未覆盖 NPC 或目标位置。

**解决方法：** 调整 `Nav Mesh Bounds Volume`的大小，重新构建路径（**Build > Build Paths**），然后按下 **P** 以确认覆盖区域显示为绿色。

**验证：** NPC 生成点和目标位置下方均显示绿色 NavMesh。

***

**原因 C：** 角色蓝图中缺少默认操作处理程序。

**解决方法：** 实现 [内置操作处理程序](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/built-in-action-handlers.md)中的四个参考处理程序，或者使用 **Create Convai Action Handler**.

**验证：** 在每个处理程序顶部添加一个 **Print String** 节点；说出对应命令时，该节点应触发。

***

#### 角色回应后，没有调用任何操作处理程序

**症状：** 角色会说话，但不会运行任何蓝图处理程序函数。回应后，操作队列似乎为空。

**原因 A：** `bEnableActions` 在聊天机器人的 `false` 属性中为 `Environment` 。

**解决方法：** 在 `Convai Chatbot` 组件的 Details 面板中，展开 **Environment** 并勾选 **Enable Actions**.

**验证：** 检查会话日志中是否有 `ActionConfig:` 条目。如果没有发送操作配置，请确认 **Enable Actions** 已开启，并且 `Actions` 重新连接前数组不为空。

***

**原因 B：** 中的操作名称 `Actions` 数组与 Blueprint 函数名称不匹配。

**修复方法：** 确保 `Name` 字段在 `FConvaiAction` 模板中与 NPC Actor Blueprint 中的自定义事件或函数名称完全一致，包括空格和标点。Unreal 不区分大小写来解析处理函数名称，但 `"Stop Moving"` 和 `"StopMoving"` 是不同的名称。例如，如果模板名称是 `"Move To"`，则 Blueprint 事件必须命名为 `Move To` （中间有空格）。

**验证：** 在处理函数的开头添加一个 **Print String** 节点。如果它没有触发，则原因是名称不匹配。检查输出日志（`ConvaiChatbotComponentLog`）中是否有包含以下内容的警告： `TriggerNamedBlueprintAction: Could not find a valid function '<name>' on the owning actor or the component (self).`

***

**原因 C：** 处理函数的签名有误。

**修复方法：** 该函数必须接受零个或一个类型为 `FConvaiResultAction` (`（在类型选择器中显示为` Convai Result Action `）的参数。如果参数类型不正确，插件会记录警告，且不会调用处理函数——队列会停滞，直到调用` 或 `AbortActionSequence` 。

**验证：** 检查输出日志（`ConvaiChatbotComponentLog`）中是否有包含以下内容的警告： `Ensure it accepts 'FConvaiResultAction' or has no parameters.`

***

#### 操作触发一次后，队列便停滞

**症状：** 序列中的第一个操作会运行，但后续操作始终不会触发。

**原因：** `HandleActionCompletion` 未被调用，或调用时未设置为 `IsSuccessful = true`.

**修复方法：** 确保处理程序中的每条代码路径都会调用 `HandleActionCompletion`。常见的遗漏路径包括：

* 守卫条件不满足时提前返回（此处调用 `AbortActionSequence` 或 `HandleActionCompletion(false)` ）。
* 异步操作（委托回调、计时器）中，完成调用位于无法到达的分支。
* 动画蒙太奇中， **中断时** 未连接到 `Handle Action Completion` 与……并列 **完成时**.

**验证：** 添加一个 **打印字符串** 节点，紧挨在每个……之前 `HandleActionCompletion` 调用。确认所有路径都会到达完成调用。

***

#### 自定义操作在“播放”模式下未显示

**症状：** 你已向 `Actions` 数组中添加了一个操作，但处理程序始终不会运行。

**原因：** 编辑操作模板后，未编译角色蓝图。

**修复方法：** 点击 **编译** 并 **保存** 到角色蓝图，然后重新启动 Play 模式。

**验证：** 中的操作名称 **环境 > 操作** 与事件图表中的自定义事件名称完全一致。

***

#### On Actions Received 已触发，但队列立即变为空

**症状：** 该 `On Actions Received` 事件触发，且 `SequenceOfActions` 中包含条目，但 `IsActionsQueueEmpty` 会返回 `true` 紧接着便如此。

**原因：** 在你检查队列之前，某个处理程序清空了队列。这可能是当前处理程序，因为 `On Actions Received` 会在插件将动作加入队列并安排分发第一个动作后广播；也可能是之前调用了 `HandleActionCompletion(false)` 或 `AbortActionSequence`.

**修复方法：** 检查是否有处理程序过早调用了 `HandleActionCompletion(false)` 或 `AbortActionSequence` 。另外，检查是否在非预期的位置调用了 `ClearActionQueue` 。

**验证：** 在每个 **打印字符串** 节点前添加一个 `HandleActionCompletion(false)`, `AbortActionSequence`以及 `ClearActionQueue` 调用。确认在你检查队列之前，这些调用都没有执行。

***

### NavMesh 和移动故障

#### 执行 Move To 动作后，角色没有移动

**症状：** Move To `处理程序会触发，但 NPC 仍停在原地。` 原因 A：

**NPC Actor 未分配 AI Controller。** 修复方法：

**将 NPC Actor 上的** AI Controller Class **设置为一个** 子类。你可以使用 UE 内置的 `AIController` 。 `AIController`.

**验证：** 在 Play In Editor 中，在 Blueprint 里使用 `Get Controller` → `Is Valid` 。结果应为 `true`.

***

**原因 B：** Nav Mesh Bounds Volume `未覆盖 NPC 的生成点或目标位置。` 修复方法：

**在编辑器中，选择该** Nav Mesh Bounds Volume `Nav Mesh Bounds Volume` 并将其边界扩展到覆盖所有可行走区域。重建导航（**Build > Build Paths**）。在视口中启用 **P** （导航可视化），确认 NPC 和目标位置处都存在导航网格。

**验证：** 视口中，NPC 和已注册的目标位置下方都显示绿色的导航网格覆盖区域。

***

**原因 C：** `bOut Success` 从 `Resolve Goal Location` 返回了 `false` ，但处理程序仍然调用了 `AI Move To` 。

**修复方法：** 始终根据 `bOut Success`进行分支判断。当其为 `false`时， `Ref` Actor 为空或已销毁： `Target Actor` 为 `null` ，且 `Destination` 保存的是过期快照，因此 `AI Move To` 要么不执行任何操作，要么将 Pawn 发送到过期位置。应改为调用 `AbortActionSequence` 并提供清晰的错误消息。

**验证：** 在 `bOut Success` 之前打印 `AI Move To`。运动节点运行前，其值必须为 `true` 。

***

**原因 D：** AcceptanceRadius `值小于受导航网格分辨率限制的 AI 实际可达到范围。` 修复方法：

**增大** AcceptanceRadius `AcceptanceRadius` 在 `FConvaiObjectEntry` （默认值为 `150` cm）。对于按钮或杠杆等小型对象，请将 **Object Is** 设为 `Specific Component` ，以指定一个具体点，而不是整个 Actor 的边界范围。

**验证：** 打印 `AI Move To` 的结果或完成回调。到达可达半径后，移动应成功完成。

***

#### 角色走到了错误的位置

**症状：** NPC 导航到了注册对象附近的位置，但并未到达对象本身。

**原因：** 处理程序将 `Object Actor` （用于非移动用途的高级引脚，例如附加效果）连接到了 `AI Move To`的 **Target Actor** 引脚，而不是 `Target Actor`.

**修复：** 将 `Resolve Goal Location`的 `Target Actor` 和 `Destination` 输出直接连接到 `AI Move To`对应的引脚即可——无需添加分支。 `Target Actor` 为 `null` 恰好表示目标是固定位置（即选中了一个 Movement Point，或条目引用了一个 `Specific Component`），因此 `AI Move To` 会自动回退到 `Destination` 。

**验证：** 打印 `Target Actor` 和 `Destination`。对于一次解析，两者中应只有一个为非 null/非零值。

***

### 引用和参数解析

#### GetParamAsRef 返回空条目

**症状：** `GetParamAsRef` 会返回一个 `FConvaiObjectEntry` 其中 `Ref` 为空，或 `Name`.

**原因 A：** 该对象不在 `Objects` 或 `Characters` 数组中。引用解析只会搜索已注册的环境。

**解决方法：** 在 Details 面板的 `Objects` 或 `Characters` 数组中添加该对象，或者在需要目标对象的响应之前调用 `AddObject` / `AddCharacter` 。使用简短的注册名称，以便 Convai 能够准确返回该名称。

**验证：** 打印返回的 `FConvaiObjectEntry.Name` 和 `FConvaiObjectEntry.Ref` ，在调用 `GetParamAsRef`之后检查。名称应与注册条目一致，并且 `Ref` 应为有效引用。

***

**原因 B：** Convai 返回的名称与已注册的对象或角色名称不完全一致。

**解决方法：** 将已注册条目的 `Name` 调整为 Convai 可能返回的确切标签，并使用 `Description` 来引导选择。例如，优先使用 `SafetyValve` ，而不是较长的句子式名称。

**验证：** 打印 `GetParamAsString` 获取同一参数的值，并将其与已注册的 `Name`进行比较。两者应完全一致。

***

#### Choices 参数解析为不受支持的值

**症状：** 玩家请求的变体不在 **Choices** 数组中（例如 `"ballet"` 而列表中只有 `"groove"`, `"disco"`和 `"g-style"` ）。处理程序会运行 **默认** 分支，或不播放任何内容。

**原因：** Convai 返回了一个不在已声明 **Choices** 列表中的值。解析器仍会传递该字符串，但处理程序必须处理回退情况。

**修复：** 添加一个 **Switch on String** 默认分支，并在其中调用 `HandleActionCompletion` ，并设置 `IsSuccessful = false`, `bAutoReport = true`以及 `ShouldRespond = Always` ，以便 Convai 能够说明此限制。请参阅 [参数化操作](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/parameterized-actions.md).

**验证：** 分别请求一个受支持的选项（处理程序播放蒙太奇）和一个不受支持的选项（角色会做出回应，但不会播放动画）。

***

#### GetParamAsNumber 意外地返回 0

**症状：** 一个 `Number`类型的参数解析为 `0` ，尽管 Convai 本应提供一个值。

**原因：** Convai 返回了类似 `"five seconds"` 这样的文本，而不是 `"5"`. `NumberValue` 通过 `Atof`填充；对于非数字字符串，该函数会返回 `0` 。

**修复：** 使用 `GetParamAsString` 读取原始值并手动解析，或者改进参数描述，引导 Convai 输出数字：设置 `Description` 到 `"A plain integer number of seconds, e.g. 3"`.

**验证：** 同时打印 `GetParamAsString` 和 `GetParamAsNumber`。如果预期自动解析数字，字符串应以数值开头。

***

### 注意力与引用问题

#### SetObjectInAttention 无效

**症状：** 调用 `SetObjectInAttention` 似乎没有任何效果——角色仍然引用其他对象。

**原因：** `聊天机器人的` 为 `false` 。 `当聊天机器人在会话开始时未发送` 时，SetObjectInAttention `action_config` 会无效。

**解决方法：** 启用 **启用操作** 并重新连接会话。

**验证：** 重新连接后，再次调用 `SetObjectInAttention` ，并检查聊天机器人 `CurrentAttentionObject` 的 `Environment` 属性。

***

#### 注视驱动的注意力被忽略

**症状：** 玩家看向带有 `UConvaiObjectComponent`的 Actor，但 `AttentionSource` 仍为 `Explicit` ，且槽位不会更新。

**原因：** 之前的一次 `SetObjectInAttention` 调用将槽位设为 `Explicit`，从而阻止所有由注视驱动的更新。

**修复：** 使用 `SetObjectInAttention` 并传入默认构造的 `FConvaiObjectEntry` （空 `Name`）以清除显式锁定。清除后，该槽位会恢复为 `None` ，注视即可重新获得控制权。

**验证：** 清除后读取 `AttentionSource` 。它应返回 `None` ，然后注视会将其更新为 `Gaze`.

***

### 后续步骤

{% content-ref url="/pages/ff7bceb97bf09634f482eda883836953606d574f" %}
[角色动作的工作原理](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/how-character-actions-work.md)
{% endcontent-ref %}

{% content-ref url="/pages/8e18d509947b40274dca96b384f432486348198f" %}
[动作 Blueprint 参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/actions-blueprint-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/convai-unreal-engine-plugin/features/character-actions/troubleshoot-character-actions.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.
