构建自定义动作处理器

添加自定义动作模板，使用编辑器实用工具搭建 Blueprint 处理程序，并报告完成状态以推进队列。

自定义动作处理器是 NPC Actor 上的 Blueprint 函数或事件，插件会在队列中收到匹配的动作名称时调用它们。在聊天机器人中声明该动作，在角色 Blueprint 中搭建一个处理器，运行你的逻辑，然后调用 处理动作完成 以便队列可以继续前进。

先决条件

• 角色动作已在聊天机器人中启用。参见 角色动作快速开始.
• 你知道要添加的动作名称与处理器名称完全匹配，包括空格。

声明动作模板

1

向 Actions 数组添加一项

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

将 名称 到一个唯一的动词短语，例如 "Print"。将 描述 设置为给 Convai 的一个简短提示，例如 "Print a debug message to the screen"。将 参数 留空，以表示无参数动作。

2

编译 Blueprint

点击 编译 角色 Blueprint，以便在连接处理器之前保存新动作模板。

保持动作名称和描述简短。过长的描述会增加发送给 Convai 的上下文，但不会改善行为。将 描述 留空，当动作名称已经不言自明时。

使用 Create Convai Action Handler 搭建处理器

该 ConvaiEditor 模块会添加一个 Create Convai Action Handler 条目到 Blueprint 图表的上下文菜单中。使用它来生成一个名称正确且参数类型合适的处理器。

1

打开角色 Blueprint 的 Event Graph

打开拥有该功能的 NPC Actor Blueprint Convai Chatbot 组件上。

2

创建处理器

在 事件图表 并搜索 Create Convai Action Handler.

选择你添加的动作（例如 Print），选择 事件（在 Event Graph 上） 或 函数（新函数图表），并确认创建。该工具会添加一个名称与动作完全相同的处理器，并带有一个 FConvaiResultAction 输入，并在末尾连接一个 处理动作完成 调用。

3

在事件和完成之间添加处理器逻辑

将你的行为连接在事件引脚和 处理动作完成。对于一个 Print 动作，添加一个 打印字符串 节点，并使用类似以下的字面消息： "This is the print action".

你也可以手动创建处理器：添加一个 自定义事件 ，使用完全相同的动作名称和一个 FConvaiResultAction 参数。插件按名称分发——参见 角色动作的工作方式.

处理动作完成

每个处理器都必须在动作结束、成功、失败或被中断时调用 处理动作完成 在该 Convai Chatbot 组件。若没有此调用，队列会停滞，后续动作将永远不会运行。

对于大多数处理器，只需 IsSuccessful 需要更改。其余参数属于高级选项——在你需要来自角色的语音反馈之前，将它们保持为默认值。

参数	默认	用途
IsSuccessful	true	true 会出队当前动作并开始下一个。 false 会清空剩余队列。
bAutoReport	true	当 true，会向 Convai 发送默认结果消息。
ShouldRespond	从不	控制 Convai 是否会口头说明结果。
AdditionalNote	""	附加到自动生成消息后的可选文本。高级引脚。
延迟	0.0	在下一动作开始前等待的秒数。高级引脚。

何时更改自动报告

对于不需要口头后续的简单动作，将 bAutoReport 保持默认，或将 ShouldRespond 设为 从不设为

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

• 该动作是仅用于调试或 UI 的步骤（例如 Print).
• 你希望 Convai 口头确认失败——将 ShouldRespond 设为 始终 并提供一个 AdditionalNote.

每条退出路径上的完成调用

连接 处理动作完成 在所有分支上：

• 动作完成后的成功路径。
• 当不满足前置条件时的失败路径。
• 当一个延迟动作（动画蒙太奇、计时器、移动）被取消时的中断路径。

// Blueprint 伪代码 — Print 处理器
事件 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 应如何响应。使用 始终 当角色应当口头确认失败时。

使用 On Actions Received 观察动作

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

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

将此委托用于诊断，而不是替代逐个动作的处理器。

示例：Open Door 处理器

// Blueprint 伪代码
事件 Open Door(ActionData: FConvaiResultAction)
    TargetEntry = GetParamAsRef(ActionData, "target")
    DoorActor = TargetEntry.Ref

    如果 DoorActor 无效：
        AbortActionSequence(
            EventText = "门的目标缺失",
            ShouldRespond = Always
        )
        return

    在 DoorActor 上调用 OpenAnimation
    延迟 1.5 秒

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

下一步

参数化动作动作 Blueprint 参考角色动作示例