> 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/built-in-action-handlers.md).

# 内置动作处理器

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

### 选择合适的处理器

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

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

### 移动到

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

{% hint style="warning" %}
Blueprint 自定义事件名称必须是 `停止移动` （带空格），才能与默认动作名称完全匹配。 `StopMoving` （不带空格）不会触发分发。
{% endhint %}

***

### 等待

暂停动作队列可配置秒数。延迟结束后， `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”` 是不同的名称。

***

### 下一步

{% content-ref url="/pages/4034933484ffa13478584311631f11ea8d503bb4" %}
[构建自定义动作处理器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/building-custom-action-handlers.md)
{% endcontent-ref %}

{% content-ref url="/pages/e29ff52f0d30b08b7f190e5b10f7b84aa21c7ff4" %}
[参数化动作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/parameterized-actions.md)
{% endcontent-ref %}

{% content-ref url="/pages/667b43e0827e11f62e187182ca1631dcc064fb61" %}
[角色动作示例](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/character-actions-examples.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/built-in-action-handlers.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.