> 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).

# 排查角色动作问题

使用本页排查未触发、在序列中途停止、移动到错误位置或接收到空参数的角色动作。

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

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

{% endhint %}

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

**症状：** 更新插件后，调用 `调用语音` 或 `调用叙事设计触发器` 的蓝图会显示编译错误，或缺少其原本拥有的输入引脚，或者读取对象条目 movement-target 字段的节点不再能解析。

**原因：** 此次升级移除了两个节点上的引脚，并弃用了旧的 movement-target 枚举。所有受影响的节点都需要一次性刷新。

**解决方法：** 按以下步骤处理 [迁移到 4.0.0-beta.27](/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 > 设置 Convai Pawn 移动**，然后编译并保存。参见 [角色动作快速入门](/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`，重建路径（**构建 > 构建路径**），然后按 **P** 以确认绿色覆盖。

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

***

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

**解决方法：** 从以下内容实现四个参考处理程序： [内置动作处理器](/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` 在聊天机器人的 `环境` 属性上。

**解决方法：** 在以下组件的 Details 面板中： `Convai 聊天机器人` 组件，展开 **环境** 并勾选 **启用动作**.

**验证：** 在会话日志中查找 `ActionConfig:` 条目。如果未发送动作配置，请确认 **启用动作** 已开启，并且 `动作` 数组在重新连接前不为空。

***

**原因 B：** 中的动作名称 `动作` 与蓝图函数名称不匹配。

**解决方法：** 确保 `名称` 上的字段 `FConvaiAction` 模板与 NPC Actor 蓝图中的 Custom Event 或函数名称完全一致，包括空格和标点。Unreal 在解析处理程序名称时不区分大小写，但 `"Stop Moving"` 和 `"StopMoving"` 是不同的名称。例如，如果模板名称是 `"Move To"`，那么蓝图事件必须命名为 `移动到` （包含空格）。

**验证：** 为每个结构和安全门添加一个 **Print String** 节点放在处理程序顶部。如果它没有触发，则原因是名称不匹配。检查 Output Log（`ConvaiChatbotComponentLog`）中包含以下内容的警告： `TriggerNamedBlueprintAction：在所属 Actor 或组件（self）上找不到有效的函数“<name>”。`

***

**原因 C：** 处理程序函数签名不正确。

**解决方法：** 该函数必须接受 0 个或 1 个参数，参数类型为 `FConvaiResultAction` (`Convai Result Action` （在类型选择器中）。如果参数类型错误，插件会记录警告且不会调用处理程序——队列会停滞，直到 `HandleActionCompletion` 或 `AbortActionSequence` 被调用。

**验证：** 检查 Output Log（`ConvaiChatbotComponentLog`）中包含以下内容的警告： `确保它接受 'FConvaiResultAction' 或者不带任何参数。`

***

#### 动作触发一次后队列停滞

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

**原因：** `HandleActionCompletion` 未被调用，或者未以 `IsSuccessful = true`.

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

* 当保护条件失败时的提前返回（改为调用 `AbortActionSequence` 或 `HandleActionCompletion(false)` 而不是在此处）。
* 异步操作（委托回调、计时器），其中完成调用位于不可达分支。
* 动画蒙太奇，其中 **已中断** 未连接到 `处理动作完成` 以及 **On Completed**.

**验证：** 为每个结构和安全门添加一个 **Print String** 节点，并在每次 `HandleActionCompletion` 调用之前立即放置该节点。确认所有路径都能到达完成调用。

***

#### 新的自定义动作未在 Play 模式中出现

**症状：** 你已向以下内容添加了一个动作： `动作` 数组，但处理程序从未运行。

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

**解决方法：** 点击 **编译** 和 **“保存”** 在角色蓝图上，然后重新启动 Play 模式。

**验证：** 中的动作名称 **Environment > Actions** 与事件图中的 Custom Event 名称完全一致。

***

#### On Actions Received 触发了，但队列立刻为空

**症状：** 该 `收到动作` 事件触发，并且 `SequenceOfActions` 包含条目，但 `IsActionsQueueEmpty` 返回 `true` 紧接着就为空了。

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

**解决方法：** 检查是否没有任何处理程序在调用 `HandleActionCompletion(false)` 或 `AbortActionSequence` 过早调用。同时检查 `ClearActionQueue` 未在意外位置被调用。

**验证：** 为每个结构和安全门添加一个 **Print String** 节点，并在每次 `HandleActionCompletion(false)`, `AbortActionSequence`，以及 `ClearActionQueue` 调用之前放置。确认在你检查队列之前没有任何一个运行。

***

### NavMesh 和移动失败

#### 执行 Move To 动作后角色不移动

**症状：** 该 `移动到` 处理程序触发了，但 NPC 仍停在原地。

**原因 A：** NPC Actor 未分配 AI Controller。

**解决方法：** 设置 **AI 控制器类** 将 NPC Actor 上的 `AIController` 子类。你可以使用 UE 内置的 `AIController`.

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

***

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

**解决方法：** 在编辑器中，选择 `Nav Mesh Bounds Volume` 并扩展其边界以覆盖所有可行走区域。重建导航（**构建 > 构建路径**）。启用 **P** （导航可视化）在视口中确认 NPC 和目标位置都存在 navmesh。

**验证：** 视口会在 NPC 和注册目标下方显示绿色 NavMesh 覆盖。

***

**原因 C：** `bOut Success` 来自 `解析目标位置` 是 `false` 但处理程序调用了 `AI Move To` 。

**解决方法：** 始终基于以下内容分支： `bOut Success`。当 `false`， `Ref` Actor 为空或已销毁： `目标 Actor` 为 `为空` 和 `目标` 持有的是过时快照，因此 `AI Move To` 将要么无操作，要么把 Pawn 发送到过时的位置。请改为调用 `AbortActionSequence` 并附带说明性消息。

**验证：** 打印 `bOut Success` 在……之前 `AI Move To`。它必须在 `true` 移动节点运行之前。

***

**原因 D：** 该 `接受半径` 在给定 NavMesh 分辨率下，该值小于 AI 实际可达范围。

**解决方法：** 增大 `接受半径` 位于 `FConvaiObjectEntry` （默认值为 `150` 厘米）。对于按钮或拉杆等小物体，将 **对象是** 为 `特定组件` 设置为指向某个具体点，而不是整个 Actor 的边界。

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

***

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

**症状：** NPC 导航到一个接近但并非位于已注册对象上的位置。

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

**解决方法：** 连接 `解析目标位置`的 `目标 Actor` 和 `目标` 输出直接连接到 `AI Move To`的对应引脚——无需分支。 `目标 Actor` 为 `为空` 仅当目标是固定位置时（一个 Movement Point，或者该条目引用了 `特定组件`），因此 `AI Move To` 会落入 `目标` 中自动处理。

**验证：** 打印 `目标 Actor` 和 `目标`。对于给定的一次解析，它们中只能有一个为非空/非零。

***

### 引用和参数解析

#### GetParamAsRef 返回空条目

**症状：** `GetParamAsRef` 返回一个 `FConvaiObjectEntry` ，并带有空 `Ref` 或空的 `名称`.

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

**解决方法：** 将该对象添加到 `对象` 或 `角色` 数组中（在 Details 面板里），或者调用 `AddObject` / `AddCharacter` ，然后再进行需要该目标的响应之前调用。使用一个简短的已注册名称，以便 Convai 能精确返回。

**验证：** 打印返回的 `FConvaiObjectEntry.Name` 和 `FConvaiObjectEntry.Ref` 之后 `GetParamAsRef`。名称应与已注册条目匹配，并且 `Ref` 应有效。

***

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

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

**验证：** 打印 `GetParamAsString` 针对同一参数，并将其与已注册的 `名称`进行比较。它们应完全一致。

***

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

**症状：** 玩家请求的变体不在 **Choices** 数组中（例如 `"ballet"` 而实际上只有 `"groove"`, `"disco"`，以及 `"g-style"` 被列出）。处理程序会运行 **默认** 分支，或者什么也不播放。

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

**解决方法：** 为每个结构和安全门添加一个 **按字符串切换** 默认分支中调用 `HandleActionCompletion` 使用 `IsSuccessful = false`, `bAutoReport = true`，以及 `ShouldRespond = Always` 以便 Convai 可以解释该限制。参见 [参数化动作](/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 输出数字：将 `描述` 为 `"一个普通的整数秒数，例如 3"`.

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

***

### 注意和引用问题

#### SetObjectInAttention 没有作用

**症状：** 调用 `SetObjectInAttention` 看起来没有任何效果——角色仍在引用其他对象。

**原因：** `bEnableActions` 为 `false` 在聊天机器人上。 `SetObjectInAttention` 在聊天机器人的以下内容未发送时没有效果： `action_config` 会话开始时未发送。

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

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

***

#### 基于凝视的注意力被忽略

**症状：** 玩家看向一个带有 `UConvaiObjectComponent`，但 `AttentionSource` 保持 `显式` ，且槽位不会更新。

**原因：** 之前的 `SetObjectInAttention` 调用将槽位设为 `显式`，这会阻止所有基于凝视的更新。

**解决方法：** 调用 `SetObjectInAttention` 使用一个默认构造的 `FConvaiObjectEntry` （空的 `名称`）来清除显式锁。清除后，槽位会回到 `无` ，并且凝视可以再次接管。

**验证：** 读取 `AttentionSource` 清除后。它应返回到 `无` ，在凝视将其更新为 `目光`.

***

### 下一步

{% content-ref url="/pages/ff7bceb97bf09634f482eda883836953606d574f" %}
[角色动作的工作方式](/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 参考](/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 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-unreal-engine-plugin/features/character-actions/troubleshoot-character-actions.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.