> 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` 报告来自 `Resolve Goal Location`的目标解析和环境进入警告。要提高详细程度，请将以下内容添加到 `DefaultEngine.ini`:

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

{% endhint %}

### 动作未触发

#### 角色会说话但在 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).

**验证：** 该蓝图具有一个移动组件（`浮动 Pawn 移动` 或 `角色移动`）以及一个 **AI Controller Class** 已分配。

***

**原因 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 **打印字符串** 为每个处理器顶部添加的节点，在你说出匹配的命令时会触发。

***

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

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

**原因 A：** `bEnableActions` 为 `false` 在聊天机器人的 `环境` 属性访问。

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

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

***

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

**修复：** 确保 `名称` 字段在 `FConvaiAction` 模板中与 NPC Actor 蓝图里的自定义事件或函数名称完全一致，包括空格和标点。Unreal 会不区分大小写地解析处理器名称，但 `"Stop Moving"` 是位于 `"StopMoving"` 是不同的名称。例如，如果模板名称是 `"Move To"`，那么蓝图事件必须命名为 `Move To` （带空格）。

**验证：** 添加一个 **打印字符串** 处理器顶部的节点。如果它没有触发，说明名称不匹配是原因。检查输出日志（`ConvaiChatbotComponentLog`）中是否有包含 `TriggerNamedBlueprintAction: Could not find a valid function '<name>' on the owning actor or the component (self).`

***

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

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

**验证：** 检查输出日志（`ConvaiChatbotComponentLog`）中是否有包含 `确保它接受 'FConvaiResultAction' 或者不带参数。`

***

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

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

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

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

* 当守卫条件失败时过早返回（应改为调用 `AbortActionSequence` 或 `HandleActionCompletion(false)` ）。
* 异步操作（委托回调、计时器）中，完成调用位于不可达分支。
* 动画蒙太奇，其中 **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 动作后角色不移动

**症状：** 该 `Move To` 处理器触发了，但 NPC 仍停留在原地。

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

**修复：** 设置 **AI Controller Class** 在 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` 来自 `Resolve Goal Location` 为 `false` 但处理器仍调用了 `AI 移动到` 。

**修复：** 始终基于 `bOut Success`。当 `false`，则 `Ref` Actor 为空或已销毁时，AI Move To 会无操作（Actor 模式）或把 pawn 发送到过期位置（Vector 模式）。请改为调用 `AbortActionSequence` 并附带有信息量的消息。

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

***

**原因 D：** 该 `接受半径` 比 AI 在给定 navmesh 分辨率下实际能达到的范围更小。

**修复：** 增加 `接受半径` 在 `FConvaiObjectEntry` （默认是 `150` 厘米）。对于按钮或杠杆等小物体，请使用 `将组件作为目标` 模式来定位特定点，而不是整个 Actor 边界。

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

***

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

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

**原因：** `bOut Mode` 来自 `Resolve Goal Location` 为 `Vector` （例如， `bStepOntoBounds` 已设置），但处理器连接了 `OutGoalActor` 到 `AI Move To · Target Actor` 而不是 `OutGoalLocation` 到 `AI Move To · Destination`.

**修复：** 始终基于 `Out Mode`。在 `Actor` 模式下，将 `OutGoalActor` 连接到 actor 引脚。在 `Vector` 模式下，将 `OutGoalLocation` 连接到 destination 引脚。

**验证：** 打印 `Out Mode` 并确认对应的 `AI 移动到` 引脚是该分支中唯一连接的目标引脚。

***

### 引用和参数解析

#### GetParamAsRef 返回空条目

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

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

**修复：** 将对象添加到 `Objects` 或 `Characters` 数组中（在详情面板里），或者调用 `AddObject` / `AddCharacter` 在需要目标的响应之前。使用一个简短的已注册名称，这样 Convai 才能准确返回。

**验证：** 打印返回的 `FConvaiObjectEntry.Name` 是位于 `FConvaiObjectEntry.Ref` 在 `GetParamAsRef`。该名称应与已注册条目相匹配，并且 `Ref` 应当有效。

***

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

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

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

***

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

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

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

**修复：** 添加一个 **Switch on String** 默认分支调用 `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

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

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

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

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

***

### 注意力和引用问题

#### SetObjectInAttention 没有效果

**症状：** 调用 `SetObjectInAttention` 似乎什么也没做——角色仍在引用其他对象。

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

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

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

***

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

**症状：** 玩家看着一个带有 `UConvaiObjectComponent`的 Actor，但 `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" %}
[Actions 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:

```
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>
```

The question should be specific, self-contained, and written in natural language.
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.