> 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/building-custom-action-handlers.md).

# 构建自定义动作处理器

添加自定义动作模板，使用编辑器实用工具脚手架创建 Blueprint 处理器，并报告完成以推进队列。

自定义动作处理程序是 NPC Actor 上的 Blueprint 函数或事件。插件会在队列中收到匹配的动作名称时调用它们。先在聊天机器人上声明动作，再在角色 Blueprint 中生成处理程序，然后运行你的逻辑，最后调用 `Handle Action Completion` 以便队列继续执行。

### 前提条件

* 角色动作已在聊天机器人上启用。请参阅 [角色动作快速入门](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/character-actions-quick-start.md).
* 确认要添加的动作名称与处理程序名称完全一致，包括空格。

### 声明动作模板

{% stepper %}
{% step %}

#### 向 Actions 数组添加一个条目

选择 NPC Actor。在 **Convai | Actions > Environment > Actions**下，点击 **+**.

Set **Name** ，将其设为唯一的动词短语，例如 `"Print"`。将 **Description** 设为对 Convai 的简短提示，例如 `"Print a debug message to the screen"`。对于不带参数的动作，将 **Parameters** 留空。
{% endstep %}

{% step %}

#### 编译 Blueprint

点击角色 Blueprint 上的 **Compile** ，以便在连接处理程序之前保存新的动作模板。
{% endstep %}
{% endstepper %}

{% hint style="info" %}
动作名称和描述应简短。冗长的描述会增加发送给 Convai 的上下文，却不会改善行为。如果动作名称含义明确，可以将 **Description** 留空。
{% endhint %}

### 使用 Create Convai Action Handler 生成处理程序

ConvaiEditor `ConvaiEditor` 模块会在 Blueprint 图表的上下文菜单中添加 **Create Convai Action Handler** 选项。使用该选项可生成名称正确且参数类型匹配的处理程序。

{% stepper %}
{% step %}

#### 打开角色 Blueprint 事件图表

打开拥有 `Convai Chatbot` 组件的 NPC Actor Blueprint。
{% endstep %}

{% step %}

#### 创建处理程序

在 **Event Graph** 中右键单击并搜索 **Create Convai Action Handler**.

选择你添加的动作（例如 `Print`），然后选择 **Event (on Event Graph)** 或 **Function (new function graph)**，并确认创建。该工具会添加一个与操作同名的处理程序，并带有一个 `FConvaiResultAction` 输入，并在末尾连接一个 `Handle Action Completion` 调用。
{% endstep %}

{% step %}

#### 在事件与完成调用之间添加处理程序逻辑

在事件引脚与 `Handle Action Completion`之间连接你的行为逻辑。对于 `Print` 操作，添加一个 **Print String** 节点，并填写一条字面消息，例如 `"This is the print action"`.
{% endstep %}
{% endstepper %}

你也可以手动创建处理程序：添加一个 **Custom Event** ，名称必须与操作完全一致，并带有一个 `FConvaiResultAction` 参数。插件会按名称分发——请参阅 [角色操作的工作方式](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/how-character-actions-work.md).

### 处理操作完成

每个处理程序都必须在操作完成、成功、失败或被中断时，调用 `Handle Action Completion` （位于 `Convai Chatbot` 组件上）。如果不调用此函数，队列就会停滞，后续操作也不会运行。

{% hint style="info" %}
对于大多数处理程序，只需更改 `IsSuccessful` 即可。其余参数属于高级选项——在需要角色提供语音反馈之前，请保留默认值。
{% endhint %}

| 参数               | 默认值     | 用途                                            |
| ---------------- | ------- | --------------------------------------------- |
| `IsSuccessful`   | `true`  | `true` 会将当前操作出队并启动下一项操作。 `false` 会清空队列中的其余操作。 |
| `bAutoReport`    | `true`  | 当设为 `true`时，会向 Convai 发送默认的结果消息。              |
| `ShouldRespond`  | `Never` | 控制 Convai 是否会针对结果进行语音反馈。                      |
| `AdditionalNote` | `""`    | 可选文本，会附加到自动生成的消息中。高级引脚。                       |
| `Delay`          | `0.0`   | 启动下一项操作前的等待秒数。高级引脚。                           |

#### 何时更改 Auto Report

对于无需语音后续反馈的简单操作，请将 `bAutoReport` 保留默认值，或将其设为 `ShouldRespond` 设为 `Never`。角色仍会静默接收有关结果的上下文信息。

在以下情况下禁用或调整 `bAutoReport` ：

* 该操作是调试步骤或仅用于 UI 的步骤（例如 `Print`).
* 你希望 Convai 大声回应失败时——将 `ShouldRespond` 设为 `Always` 并提供一个 `AdditionalNote`.

#### 确保所有退出路径都处理完成

在所有分支中连接 `Handle Action Completion` ：

* 成功路径：操作完成后。
* 失败路径：不满足前置条件时。
* 中断路径：潜在操作（动画蒙太奇、计时器、移动）被取消时。

```
// 蓝图伪代码 — Print 处理程序
Event Print(ActionData: FConvaiResultAction)
    Print String("This is the print action")
    HandleActionCompletion(
        IsSuccessful = true,
        bAutoReport = true,
        ShouldRespond = Never
    )
```

### AbortActionSequence

当处理程序无法恢复时——例如目标 Actor 已被销毁、动画蒙太奇播放失败或前置条件始终无法满足——请调用 `AbortActionSequence` ，而不是使用 `Handle Action Completion(false)`.

| 参数              | 默认值    | 用途                                     |
| --------------- | ------ | -------------------------------------- |
| `EventText`     | `""`   | 对失败情况的描述。留空则会静默中止。                     |
| `ShouldRespond` | `Auto` | Convai 应如何响应。若角色应大声回应失败，请使用 `Always` 。 |

### 使用 On Actions Received 观察操作

在聊天机器人组件上绑定 **On Actions Received** ，以记录或调试原始操作序列。此委托不能取代基于名称的分发——插件仍会自动调用匹配的处理程序。

```
// 蓝图伪代码
On Actions Received(
    ChatbotComponent: UConvaiChatbotComponent,
    InteractingPlayerComponent: UConvaiPlayerComponent,
    SequenceOfActions: TArray<FConvaiResultAction>
)
```

此委托用于诊断，不应替代每个操作对应的处理程序。

### 示例：Open Door 处理程序

```
// 蓝图伪代码
事件 Open Door（ActionData: FConvaiResultAction）
    TargetEntry = GetParamAsRef(ActionData, "target")
    DoorActor = TargetEntry.Ref

    如果 DoorActor 无效：
        AbortActionSequence(
            EventText = "The door target is missing",
            ShouldRespond = Always
        )
        return

    在 DoorActor 上调用 OpenAnimation
    延迟 1.5 秒

    HandleActionCompletion(
        IsSuccessful = true,
        bAutoReport = true,
        ShouldRespond = Never
    )
```

### 后续步骤

{% 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/8e18d509947b40274dca96b384f432486348198f" %}
[动作 Blueprint 参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/actions-blueprint-reference.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/building-custom-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.
