> 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 事件。本页为每个动作提供可直接复制的处理器模式。

### 选择合适的处理器

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

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

### 移动到

将 NPC 导航到已注册的对象。 `destination` 参数是一个 `Reference` 类型，它会根据已注册的对象名称进行解析。

**参数：**

| 名称            | 类型                       | 描述                                            |
| ------------- | ------------------------ | --------------------------------------------- |
| `destination` | 引用（`FConvaiObjectEntry`) | NPC 应该前往的对象。根据已注册的 `对象` 和 `角色` 列表（`对象` 优先搜索）。 |

**Blueprint 处理器：**

在每个阶段加载时，对聊天机器人组件使用 **Create Convai Action Handler** （在 Event Graph 中右键单击）即可自动生成此事件，然后用下面的模式替换占位逻辑。

```
// Blueprint 伪代码
// 名为“Move To”的 Custom Event，带一个 FConvaiResultAction 输入

Event Move To(ActionData: FConvaiResultAction)
    // 读取并解析目标位置
    DestEntry = GetParamAsRef(ActionData, "destination")
    ResolveGoalLocation(
        Entry = DestEntry,
        SourceActor = Self,
        // 输出：
        TargetActor, ObjectActor, OutGoalComponent, Destination,
        OutAcceptanceRadius, UsesDestination,
        bSuccess, bAlreadyThere, bReachable,
        PathEnd, PathPoints, GoalTravelDistance, MovementPointIndex
    )

    // 保护：目标 Actor 必须存活
    如果不是 bSuccess：
        AbortActionSequence(
            EventText = "导航目标已不再存在"，
            ShouldRespond = Always
        )
        return

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

    // 将两个引脚接到一个 AI Move To 上——无需分支
    AIMoveTo(
        Target = TargetActor,
        Destination = Destination,
        AcceptanceRadius = OutAcceptanceRadius
    )

    // 等待 OnMoveCompleted（绑定到 AIController.ReceiveMoveCompleted，或使用
    // 一个 task/latent action），然后调用：
    HandleActionCompletion(IsSuccessful = true)
```

**要点：**

* 连接 `目标 Actor` 和 `目标` 直接连接到一个 `AI Move To` 节点。无需分支： `目标 Actor` 为 `为空` 恰好在目标是固定位置时——一个 Movement Point 获胜，或者该条目引用了某个组件——因此 `AI Move To` 会落入 `目标` 本身。
* `解析目标位置` 在存在有效的 `源 Actor` 还会计算 `bOut 可达`, `输出路径点`，以及 `输出目标行进距离`，当不存在 NavMesh 路径时，你可以用它来提前退出。 `输出 Movement Point 索引` 会报告哪个 `移动点` 条目获胜，或者 `-1` 当对象引用反而解析为目标时。
* `AcceptanceRadius` 来自已注册的 `FConvaiObjectEntry` （默认 `150` 厘米）。对于大型对象可增大它，若要精确定位到子组件则可减小它。

### 跟随

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

**参数：**

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

**Blueprint 处理器：**

在每个阶段加载时，对聊天机器人组件使用 **Create Convai Action Handler** （在 Event Graph 中右键单击）即可自动生成此事件，然后用下面的模式替换占位逻辑。

```
// Blueprint 伪代码
// 名为“Follow”的 Custom Event，带一个 FConvaiResultAction 输入

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

    如果 TargetEntry.Ref 为空：
        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` 节点，它会重新发出 `AI Move To` 每隔 0.5–1.0 秒朝目标 Actor 发送一次。将计时器句柄存储在 Blueprint 变量中，然后调用 `HandleActionCompletion(true)` 在计时器启动后。 当 `停止移动` 之后触发时，清除计时器并完成停止动作。

或者，实现一个 `BehaviorTree` 任务，使其循环直到设置了外部信号，并从 `停止移动` 处理器中发出该信号。

### 停止移动

取消任何进行中的移动行为并完成当前动作。如果 `跟随` 启动了计时器或任务， `停止移动` 应清除该计时器或任务，然后调用 `HandleActionCompletion(true)` 来完成停止动作。

**参数：** 无

**Blueprint 处理器：**

在每个阶段加载时，对聊天机器人组件使用 **Create Convai Action Handler** （在 Event Graph 中右键单击）即可自动生成此事件，然后用下面的模式替换占位逻辑。

```
// Blueprint 伪代码
// 名为“Stop Moving”的 Custom Event，带一个 FConvaiResultAction 输入

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

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

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

{% hint style="warning" %}
Blueprint Custom Event 名称必须是 `停止移动` （包含空格），才能与默认动作名称完全匹配。 `StopMoving` （不含空格）将不会触发分发。
{% endhint %}

***

### 等待

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

**参数：**

| 名称   | 类型          | 描述                                                    |
| ---- | ----------- | ----------------------------------------------------- |
| `秒数` | 数字（`float`) | 暂停的秒数。Convai 会填写此值；请用清晰的参数说明来引导它，例如 `“一个纯粹的秒数，例如 3”`. |

**Blueprint 处理器：**

在每个阶段加载时，对聊天机器人组件使用 **Create Convai Action Handler** （在 Event Graph 中右键单击）即可自动生成此事件，然后用下面的模式替换占位逻辑。

```
// Blueprint 伪代码
// 名为“Wait For”的 Custom Event，带一个 FConvaiResultAction 输入

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

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

    // 使用 Unreal 内置的 Delay 节点（latent action）
    Delay(Duration = Seconds)

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

**实现说明——Delay 节点：**

内置的 **延迟** Blueprint 节点是一个 latent action，在这里可以正常工作。如果你的处理器逻辑位于函数中而不是 Custom Event 中，请改用 `Set Timer by Event` 节点（latent actions 只能在事件图中使用，不能在 Blueprint 函数中使用）。

***

### 修改默认动作

你可以在其中重命名、移除或扩展任何默认动作 `动作` 数组中添加一个自定义动作：

* **重命名** ——更改 `名称` 在 Details 面板中的名称，并将 Blueprint Custom Event 重命名以匹配它。
* **移除** ——在 `动作` 数组中选择该条目并点击删除按钮。Blueprint 事件会变成死代码，但不会导致错误。
* **添加参数** ——添加一个 `FConvaiActionParam` 条目到 `Parameters` 模板上的数组中。更新你的处理器以使用以下方式读取新参数： `GetParamAs*`.

如果你重命名了这些动作模板中的任何一个，请将相应的 Blueprint Custom Event 也重命名以匹配，包括空格。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, 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/built-in-action-handlers.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.