> 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 角色动作的参考处理器模式，包括参数、完成规则和 Blueprint 流程。

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

### 选择合适的处理器

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

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

### 移动到

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

**参数：**

| 名称    | 类型                       | 说明                                                    |
| ----- | ------------------------ | ----------------------------------------------------- |
| `目的地` | 引用（`FConvaiObjectEntry`) | NPC 应该走向的对象。根据已注册的 `对象` 和 `Characters` 列表（`对象` 优先搜索）。 |

**Blueprint 处理器：**

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

```
// Blueprint 伪代码
// 名为“Move To”的自定义事件，带有一个 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 必须存活
    if not bSuccess:
        AbortActionSequence(
            EventText = "导航目标已不再存在",
            ShouldRespond = Always
        )
        返回

    // 如果已经在目标点，则跳过移动
    if bAlreadyThere:
        HandleActionCompletion(IsSuccessful = true)
        返回

    // 将两个引脚都接入同一个 AI Move To —— 不需要分支
    AIMoveTo(
        Target = TargetActor,
        Destination = Destination,
        AcceptanceRadius = OutAcceptanceRadius
    )

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

**要点：**

* 连接 `目标 Actor` 和 `目的地` 直接进入一个 `AI Move To` 节点。不需要分支： `目标 Actor` 是 `null` 当目标是固定位置时——某个 Movement Point 胜出，或者条目引用的是一个组件——正是如此，所以 `AI Move To` 会自然落到 `目的地` 。
* `解析目标位置` 配合一个有效的 `源 Actor` 还会计算 `bOut Reachable`, `Out Path Points`，以及 `Out Goal Travel Distance`，当不存在 NavMesh 路径时，你可以用它提前退出。 `Out Movement Point Index` 会报告哪个 `移动点` 条目胜出，或者 `-1` 当对象引用改为解析到目标时。
* `接受半径` 来自已注册的 `FConvaiObjectEntry` （默认 `150` 厘米）。对大型对象增大该值，或对精确的子组件目标减小该值。

### 跟随

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

**参数：**

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

**Blueprint 处理器：**

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

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

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

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

    // 启动一个重复计时器（例如每 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 Move To` 指向目标 Actor。将计时器句柄存储到蓝图变量中，然后在 `HandleActionCompletion(true)` 在计时器启动后调用。 `停止移动` 稍后触发时，清除计时器并完成停止操作。

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

### 停止移动

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

**参数：** 无

**Blueprint 处理器：**

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

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

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

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

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

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

***

### 等待

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

**参数：**

| 名称        | 类型          | 说明                                                     |
| --------- | ----------- | ------------------------------------------------------ |
| `持续时间（秒）` | 数字（`float`) | 要暂停的秒数。Convai 会填充此值；请用清晰的参数描述来引导它，例如 `“一个简单的秒数，例如 3”`. |

**Blueprint 处理器：**

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

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

Event 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 节点：**

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

***

### 修改默认操作

你可以在 `操作` 数组中重命名、移除或扩展任何默认操作：

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

如果你重命名了这些操作模板中的任何一个，请将相应的 Blueprint 自定义事件也重命名为匹配的名称，包括空格。Unreal 会不区分大小写地解析处理器名称，但 `“停止移动”` 和 `“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 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/built-in-action-handlers.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.