内置动作处理器

四个默认 Convai 角色动作的处理程序模式参考，包括参数、完成规则和 Blueprint 流程。

每个新的 Convai 聊天机器人 组件都包含四个预配置的动作模板： 移动到, 跟随, 停止移动，以及 等待。这些模板定义了动作 名称 和 参数 ——你仍然需要在 NPC 角色 Blueprint 中实现相应的 Blueprint 事件。本页为每个动作提供了可直接复制的处理器模式。

选择合适的处理器

动作	参数	用途	完成模型
移动到	目标位置 （引用）	导航到已注册的对象或角色目标	在移动结束时完成
跟随	角色 （引用）	开始持续跟随已注册的角色	在跟随循环开始后完成
停止移动	—	取消任何正在进行的移动	立即完成
等待	秒数 （数字）	暂停动作队列一段持续时间	在延迟后完成

移动处理器模式使用 AI 移动到 并且需要 AI Controller 和 Nav Mesh Bounds Volume。 等待 不需要导航。如果你的 NPC 不使用 Unreal 的导航系统，请用你自己的方法替换移动逻辑，并保持相同的 HandleActionCompletion 模式。

移动到

将 NPC 导航到已注册的对象。 目标位置 参数是一个 引用 类型，它会根据已注册的对象名称进行解析。

参数：

名称	类型	描述
目标位置	引用（FConvaiObjectEntry)	NPC 应该走向的对象。会根据已注册的 对象 和 角色 列表（对象 优先搜索对象）。

Blueprint 处理器：

使用 Create Convai Action Handler （在 Event Graph 中右键单击）自动生成此事件，然后将占位逻辑替换为下面的模式。

// Blueprint 伪代码
// 名为 “Move To” 的自定义事件，带一个 FConvaiResultAction 输入

事件 Move To(ActionData: FConvaiResultAction)
    // 读取并解析目标
    DestEntry = GetParamAsRef(ActionData, "destination")
    ResolveGoalLocation(
          Entry = DestEntry,
          SourceActor = Self,
        // 输出：
          OutGoalActor, OutGoalComponent, OutGoalLocation,
          OutAcceptanceRadius, OutMode,
          bSuccess, bAlreadyThere, bReachable, PathEnd, PathPoints
    )

    // 防护：目标 Actor 必须仍然存在
    if not bSuccess:
        AbortActionSequence(
              EventText = "导航目标已不再存在",
              ShouldRespond = Always
        )
        return

    // 如果已经到达目标，则跳过移动
    if bAlreadyThere:
        HandleActionCompletion(IsSuccessful = true)
        return

    // 根据解析出的模式分支，并使用正确的引脚调用 AI Move To
    if OutMode == Actor:
        AIMoveTo(Target = OutGoalActor, AcceptanceRadius = OutAcceptanceRadius)
    else:
        AIMoveTo(Destination = OutGoalLocation, AcceptanceRadius = OutAcceptanceRadius)

    // 等待 OnMoveCompleted（绑定到 AIController.ReceiveMoveCompleted，或使用
    // 一个任务/延迟动作），然后调用：
    HandleActionCompletion(IsSuccessful = true)

要点：

• 始终在连接之前根据 输出模式 进行分支 AI 移动到 — Actor 模式使用 Actor 引脚， Vector 模式使用 Location 引脚。接错引脚会导致移动使用错误的目标解释。
• ResolveGoalLocation 配合一个存活的 源 Actor 还会计算 bOut Reachable 和 Out Path Points，你可以在没有导航网格路径时用它们提前退出。
• AcceptanceRadius 来自已注册的 FConvaiObjectEntry （默认 150 厘米）。对于大型对象可增大它，或对于精确的子组件目标可减小它。

跟随

启动针对已注册角色的持续跟随行为。跟随计时器或任务可以在动作完成后继续运行；在跟随循环开始后调用 HandleActionCompletion(true) ，这样后续动作就可以分发。

参数：

名称	类型	描述
角色	引用（FConvaiObjectEntry)	要跟随的角色。会根据已注册的 对象 和 角色 列表（对象 优先搜索对象）。

Blueprint 处理器：

使用 Create Convai Action Handler （在 Event Graph 中右键单击）自动生成此事件，然后将占位逻辑替换为下面的模式。

// Blueprint 伪代码
// 名为 “Follow” 的自定义事件，带一个 FConvaiResultAction 输入

事件 Follow(ActionData: FConvaiResultAction)
    TargetEntry = GetParamAsRef(ActionData, "character")

    if TargetEntry.Ref is None:
        AbortActionSequence(
              EventText = "未找到跟随目标",
              ShouldRespond = Always
        )
        return

    // 启动一个重复计时器（例如每 0.5 秒）来调用
    // AIMoveTo(Target = TargetEntry.Ref, AcceptanceRadius = 150.0)
    // 存储计时器句柄，以便 Stop Moving 可以取消它。

    // 在循环开始后完成 Follow 动作。
    // 计时器/任务会一直运行，直到稍后触发 Stop Moving。
    HandleActionCompletion(IsSuccessful = true)

实现说明 — 轮询计时器：

一种常见做法是使用 Set Timer by Function Name 节点，每 0.5–1.0 秒重新发出 AI 移动到 朝向目标 Actor 的指令。将计时器句柄存储在 Blueprint 变量中，然后在 HandleActionCompletion(true) 启动后调用 停止移动 ，稍后当

也可以实现一个 BehaviorTree 任务，让它循环直到设置外部信号，然后从 停止移动 处理器中发出该信号。

停止移动

取消任何正在进行的移动行为并完成当前动作。若 跟随 已启动计时器或任务， 停止移动 应清除该计时器或任务，然后调用 HandleActionCompletion(true) 以完成停止动作。

参数： 无

Blueprint 处理器：

使用 Create Convai Action Handler （在 Event Graph 中右键单击）自动生成此事件，然后将占位逻辑替换为下面的模式。

// Blueprint 伪代码
// 名为 “Stop Moving” 的自定义事件，带一个 FConvaiResultAction 输入

事件 Stop Moving(ActionData: FConvaiResultAction)
    // 取消重复的跟随计时器
    ClearTimer(FollowTimerHandle)

    // 立即停止当前移动
    AIController.StopMovement()

    // 完成 Stop Moving 动作
    HandleActionCompletion(IsSuccessful = true)

Blueprint 自定义事件名称必须是 停止移动 （带空格），才能与默认动作名称完全匹配。 StopMoving （不带空格）不会触发分发。

---

等待

暂停动作队列可配置秒数。延迟结束后， HandleActionCompletion 推进队列到下一个动作。

参数：

名称	类型	描述
秒数	数字（float)	要暂停的秒数。Convai 会填充此值；可用清晰的参数描述来引导它，例如 “一个简单的秒数，例如 3”.

Blueprint 处理器：

使用 Create Convai Action Handler （在 Event Graph 中右键单击）自动生成此事件，然后将占位逻辑替换为下面的模式。

// Blueprint 伪代码
// 名为 “Wait For” 的自定义事件，带一个 FConvaiResultAction 输入

事件 Wait For(ActionData: FConvaiResultAction)
    Seconds = GetParamAsNumber(ActionData, "time in seconds")

    // 防护：限制到合理范围
    Seconds = Clamp(Seconds, 0.1, 30.0)

    // 使用 Unreal 内置的 Delay 节点（延迟动作）
    Delay(Duration = Seconds)

    // 延迟完成后：
    HandleActionCompletion(IsSuccessful = true)

实现说明 — Delay 节点：

内置的 Delay Blueprint 节点是一个延迟动作，在这里可以正常工作。如果你的处理器逻辑是在函数中而不是自定义事件中，请改用 Set Timer by Event 节点（延迟动作只在事件图中有效，而不在 Blueprint 函数中有效）。

---

修改默认动作

你可以重命名、移除或扩展 Actions 数组中的任何默认动作：

• 重命名 ——在 Details 面板中更改 名称 并将 Blueprint 自定义事件重命名为匹配的名称。
• 移除 ——选中 Actions 数组中的条目并单击删除按钮。Blueprint 事件会变成死代码，但不会导致错误。
• 添加参数 ——添加一个 FConvaiActionParam 条目到模板的 参数 数组中。更新你的处理器，以使用 GetParamAs*.

如果你重命名了这些动作模板中的任何一个，也要将对应的 Blueprint 自定义事件重命名为匹配名称，包括空格。Unreal 会不区分大小写地解析处理器名称，但 “Stop Moving” 和 “StopMoving” 是不同的名称。

---

下一步

构建自定义动作处理器参数化动作角色动作示例