> 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` 报告来自 `解析目标位置`。如需提高日志详细程度，请将以下内容添加到 `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 > Setup Convai Pawn Movement**，然后编译并保存。参见 [角色动作快速入门](/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 Controller 类** 已分配。

***

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

**修复：** 缩放 `Nav Mesh Bounds Volume`，重建路径（**构建 > 构建路径**），然后按 **P** 以确认绿色覆盖区域。

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

***

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

**修复：** 从……实现四个参考处理器 [内置动作处理程序](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/built-in-action-handlers.md)，或者使用……搭建自定义处理器 **创建 Convai 动作处理器**.

**验证：** 一个 **打印字符串** 在每个处理器顶部放置的节点会在你说出匹配命令时触发。

***

#### 角色响应后没有调用任何动作处理器

**症状：** 角色说话了，但没有蓝图处理函数运行。响应后动作队列似乎为空。

**原因 A：** `bEnableActions` 是 `false` 在聊天机器人的 `Environment` 属性公开。

**修复：** 在……的 Details 面板中 `Convai 聊天机器人` 组件中，展开 **Environment** 并勾选 **启用操作**.

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

***

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

**修复：** 确保 `名称` 字段，在 `FConvaiAction` 模板与 NPC Actor 蓝图中的自定义事件或函数名完全匹配，包括空格和标点。Unreal 在解析处理器名称时不区分大小写，但 `“Stop Moving”` 和 `“StopMoving”` 是不同的名称。例如，如果模板名是 `"Move To"`，则蓝图事件必须命名为 `移动到` （包含空格）。

**验证：** 添加一个 **打印字符串** 节点放在处理器顶部。如果它没有触发，那么原因就是名称不匹配。检查输出日志（`ConvaiChatbotComponentLog`）中是否有包含以下内容的警告 `TriggerNamedBlueprintAction：在拥有该对象的 Actor 或组件（self）上找不到有效函数“<name>”。`

***

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

**修复：** 该函数必须接受 0 个或 1 个类型为 `FConvaiResultAction` (`Convai Result Action` 的参数（在类型选择器中）。 `HandleActionCompletion` 或 `AbortActionSequence` 之前调用。

**验证：** 检查输出日志（`ConvaiChatbotComponentLog`）中是否有包含以下内容的警告 `确保它接受“FConvaiResultAction”或不带参数。`

***

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

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

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

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

* 当守卫条件失败时提前返回（此处调用 `AbortActionSequence` 或 `HandleActionCompletion(false)` 替代）。
* 异步操作（委托回调、定时器），其中完成调用位于不可达分支中。
* 动画 Montage，其中 **On Interrupted** 未连接到 `Handle Action Completion` 与 **On Completed**.

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

***

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

**症状：** 你向……添加了一个动作 `动作` 数组，但处理器从未运行。

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

**修复：** 点击 **编译** 和 **保存** 在角色蓝图上，然后重新启动 Play 模式。

**验证：** 在……中的动作名称 **Environment > Actions** 与事件图中的自定义事件名称完全一致。

***

#### 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 动作后角色不移动

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

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

**修复：** 设置 **AI Controller 类** 在 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 移动到` 仍然如此。

**修复：** 始终基于……进行分支 `bOut Success`。当 `false`， `引用` Actor 为空或已销毁： `目标 Actor` 是 `null` 和 `Destination` 持有的是过时的快照，因此 `AI 移动到` 要么会无操作，要么会把 Pawn 发送到过时的位置。调用 `AbortActionSequence` 并改用带有说明性消息的方式。

**验证：** Print `bOut Success` 之前 `AI 移动到`。它必须在 `true` 移动节点运行之前。

***

**原因 D：** 该 `接受半径` 比在当前 navmesh 分辨率下 AI 物理上可达到的范围更小。

**修复：** 增加 `接受半径` 在 `FConvaiObjectEntry` （默认是 `150` 厘米）。对于按钮或拉杆等小对象，设置 **对象为** 为 `特定组件` 以针对某个特定点，而不是整个 Actor 边界。

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

***

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

**症状：** NPC 导航到了靠近但并未到达已注册对象的位置。

**原因：** 连接处理器时将 `Object Actor` （一个用于非移动用途的高级引脚，例如附加效果）接入到 `AI 移动到`的 **目标 Actor** 引脚，而不是 `目标 Actor`.

**修复：** 连接 `解析目标位置`的 `目标 Actor` 和 `Destination` 输出直接到 `AI 移动到`的对应引脚——无需分支。 `目标 Actor` 是 `null` 仅在目标是固定位置时（获得了一个 Movement Point，或者该条目引用了一个 `特定组件`），因此 `AI 移动到` 会落入 `Destination` 自动。

**验证：** Print `目标 Actor` 和 `Destination`。对于给定的解析，只有其中一个应为非空/非零。

***

### 引用和参数解析

#### GetParamAsRef 返回空条目

**症状：** `GetParamAsRef` 返回一个 `FConvaiObjectEntry` 带有空的 `引用` 或空的 `名称`.

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

**修复：** 将对象添加到 `对象` 或 `角色` Details 面板中的数组，或者调用 `添加对象` / `AddCharacter` ，在需要目标的响应之前。使用一个简短的已注册名称，以便 Convai 可以准确返回。

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

***

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

**修复：** 将已注册条目的 `名称` 调整为 Convai 可能返回的精确标签，并使用 `说明` 来引导选择。例如，优先使用 `SafetyValve` 而不是一个长的类似句子的名称。

**验证：** Print `GetParamAsString` 对同一参数并将其与已注册的 `名称`进行比较。它们应完全匹配。

***

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

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

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

**修复：** 添加一个 **按字符串切换** 调用……的默认分支 `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).

**验证：** 请求一个受支持的选项（处理器播放 Montage）和一个不受支持的选项（角色响应但不播放动画）。

***

#### GetParamAsNumber 意外返回 0

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

**原因：** Convai 返回了类似 `“five seconds”` 而不是 `"5"`. `NumberValue` 通过……填充 `Atof`，它会返回 `0` 对于非数字字符串则返回。

**修复：** 使用 `GetParamAsString` 读取原始值并手动解析，或者改进参数描述以引导 Convai 输出数字：设置 `说明` 为 `“一个普通的整数秒数，例如 3”`.

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

***

### 注意和引用问题

#### SetObjectInAttention 没有效果

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

**原因：** `bEnableActions` 是 `false` 在聊天机器人上。 `SetObjectInAttention` 当聊天机器人的……时没有效果 `action_config` 在会话开始时未发送。

**修复：** 启用 **启用操作** 并重新连接会话。

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

***

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

**症状：** 玩家看向一个带有……的 Actor `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 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.