> 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` 组件都包含四个预配置的动作模板： `Move To`, `Follow`, `Stop Moving`，以及 `Wait For`。这些模板定义了动作 *名称* 和 *参数* ——你仍需在 NPC 角色蓝图中实现相应的 Blueprint 事件。本页为每个动作提供可直接复制的处理程序模式。

### 选择合适的处理程序

| 操作        | 参数                 | 用途             | 完成方式      |
| --------- | ------------------ | -------------- | --------- |
| `Move To` | `destination` （引用） | 导航至已注册的对象或角色目标 | 移动结束时完成   |
| `跟随`      | `character` （引用）   | 开始持续跟随已注册的角色   | 跟随循环启动后完成 |
| `停止移动`    | —                  | 取消所有正在进行的移动    | 立即完成      |
| `等待`      | `秒数` （数字）          | 让动作队列暂停指定时长    | 延迟结束后完成   |

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

### 移动到

将 NPC 导航至已注册的对象。 `destination` 参数的类型为 `Reference` ，会根据已注册对象的名称解析。

**参数：**

| 名称            | 类型                              | 说明                                                                 |
| ------------- | ------------------------------- | ------------------------------------------------------------------ |
| `destination` | Reference（`FConvaiObjectEntry`) | NPC 应前往的对象。根据已注册的 `Objects` 和 `Characters` 列表进行解析（`Objects` 优先搜索）。 |

**Blueprint 处理程序：**

使用 **Create Convai Action Handler** （在事件图表中右键单击）可自动生成此事件的框架，然后将占位逻辑替换为以下模式。

```
// 蓝图伪代码
// 名为 "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 = "Navigation target no longer exists",
            ShouldRespond = Always
        )
        return

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

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

    // 等待 OnMoveCompleted（绑定到 AIController.ReceiveMoveCompleted，或使用
    // 任务/潜在操作），然后调用：
    HandleActionCompletion(IsSuccessful = true)
```

**要点：**

* 将 `目标 Actor` 和 `Destination` 直接连接到一个 `AI Move To` 节点。无需分支： `目标 Actor` 仅当目标是固定位置时才为 `null` ——例如，Movement Point 命中，或条目引用了一个组件。因此 `AI Move To` 会自动传递到 `Destination` 。
* `Resolve Goal Location` 在提供有效的 `Source Actor` 时还会计算 `bOut Reachable`, `Out Path Points`和 `Out Goal Travel Distance`；如果不存在 NavMesh 路径，你可以利用这些值提前退出。 `Out Movement Point Index` 报告哪个 `Movement Points` 条目获胜，或者 `-1` 对象引用解析出目标时。
* `AcceptanceRadius` 来自已注册的 `FConvaiObjectEntry` （默认值为 `150` 厘米）。大型对象可增大此值；若要精确定位子组件，则可减小此值。

### 跟随

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

**参数：**

| 名称          | 类型                              | 说明                                                          |
| ----------- | ------------------------------- | ----------------------------------------------------------- |
| `character` | Reference（`FConvaiObjectEntry`) | 要跟随的角色。从已注册的 `Objects` 和 `Characters` 列表中解析（`Objects` 先搜索）。 |

**Blueprint 处理程序：**

使用 **Create Convai Action Handler** （在事件图表中右键单击）可自动生成此事件的框架，然后将占位逻辑替换为以下模式。

```
// 蓝图伪代码
// 名为 "Follow" 且带有一个 FConvaiResultAction 输入的自定义事件

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

    if TargetEntry.Ref is None:
        AbortActionSequence(
            EventText = "Follow target not found",
            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)` 稍后触发 `Stop Moving` 时，清除计时器并完成停止动作。

或者，也可以实现一个 `BehaviorTree` 任务，使其循环运行直到收到外部信号，并从 `Stop Moving` 处理程序发送该信号。

### 停止移动

取消任何正在进行的移动行为，并完成当前动作。如果 `Follow` 启动了计时器或任务， `Stop Moving` 应清除该计时器或任务，然后调用 `HandleActionCompletion(true)` 用于停止操作。

**参数：** 无

**Blueprint 处理程序：**

使用 **Create Convai Action Handler** （在事件图表中右键单击）可自动生成此事件的框架，然后将占位逻辑替换为以下模式。

```
// 蓝图伪代码
// 名为 "Stop Moving" 的自定义事件，包含一个 FConvaiResultAction 输入

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

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

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

{% hint style="warning" %}
Blueprint 自定义事件的名称必须为 `Stop Moving` （中间有空格），才能与默认操作名称完全匹配。 `StopMoving` （中间没有空格）将不会触发该事件。
{% endhint %}

***

### 等待时长

让操作队列暂停指定的秒数。延迟结束后， `HandleActionCompletion` 会推进队列，执行下一个操作。

**参数：**

| 名称                | 类型          | 说明                                                     |
| ----------------- | ----------- | ------------------------------------------------------ |
| `time in seconds` | 数字（`float`) | 暂停的秒数。Convai 会填入此值；请使用清晰的参数描述来引导它，例如 `"一个普通的秒数，例如 3"`. |

**Blueprint 处理程序：**

使用 **Create Convai Action Handler** （在事件图表中右键单击）可自动生成此事件的框架，然后将占位逻辑替换为以下模式。

```
// 蓝图伪代码
// 名为 "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 节点：**

内置的 **Delay** Blueprint 节点属于潜在操作，在这里可以正常工作。如果处理逻辑位于函数而非自定义事件中，请改用 `Set Timer by Event` 节点（潜在操作只能在事件图表中使用，不能在 Blueprint 函数中使用）。

***

### 修改默认操作

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

* **重命名** — 在 Details 面板中更改 `Name` ，并将 Blueprint 自定义事件重命名为与之匹配的名称。
* **移除** — 在 `Actions` 数组中选中该项，然后点击删除按钮。对应的 Blueprint 事件会成为无效代码，但不会导致错误。
* **添加参数** —添加一个 `FConvaiActionParam` 条目到模板的 `Parameters` 数组中。更新处理程序，以便使用以下方法读取新参数： `GetParamAs*`.

如果重命名这些操作模板中的任何一个，请将对应的 Blueprint 自定义事件也重命名为相同名称，包括空格。Unreal 不区分大小写地解析处理程序名称，但 `"停止移动"` 和 `"停止移动"` 是不同的名称。

***

### 后续步骤

{% content-ref url="/pages/4034933484ffa13478584311631f11ea8d503bb4" %}
[构建自定义动作处理器](https://docs.convai.com/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" %}
[参数化动作](https://docs.convai.com/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" %}
[角色动作示例](https://docs.convai.com/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.
