参数化动作

声明类型化动作参数，并在 Blueprint 处理器中读取文本、引用、选择和动画的解析值。

参数化动作让 Convai 在选择动作时填入类型化的值。一个 移动到 动作需要一个目的地；一个 打印 动作可以携带动态文本；一个 舞蹈 动作可以从固定的动画风格列表中选择。参数为 Convai 提供结构化指引，并为你的处理器提供可读取的类型化值。

以下示例展示了最常见的参数模式。完整字段参考在本页末尾。

自定义与参数化动作演练

先决条件

• 你已完成 构建自定义动作处理程序 用于无参数动作。
• 动作模板会在你在播放模式下测试之前，在角色 Blueprint 上编译。

选择参数类型

在每个阶段加载时，对聊天机器人组件使用 String 用于自由形式文本， Actor 引用 用于已注册的对象或角色， Number 用于数值，且 String 使用 Choices 当只有少数几个值有效时（例如固定的舞蹈风格列表）。完整类型列表见下方参考表。

类型	适用于
String	该值是开放式文本。
Actor 引用	该值必须解析为场景中已注册的对象或角色。
Number	该值是一个数字（距离、时长、数量）。
Bool	该值是真/假标志。
String + 选项	该值必须是固定选项列表中的一个。
Enum	一个 UENUM 已存在于你的项目中，并且你希望 Convai 根据其显示名称进行匹配。

示例：使用字符串参数打印

从一个无参数的 打印 动作开始，再添加一个类型化输入，这样 Convai 就能提供消息。

声明参数

在 打印 动作条目，展开 Parameters 并点击 +:

字段	值
名称	文本
类型	String
描述	留空，或使用简短提示，例如 “要打印的文本”.

编译 Blueprint。

在处理器中读取该值

// Blueprint 伪代码
Event Print(ActionData: FConvaiResultAction)
    Message = GetParamAsString(ActionData, "text")
    Print String(Message)
    HandleActionCompletion(IsSuccessful = true, ShouldRespond = Never)

在播放模式下测试： “把你的名字打印到屏幕上” 或 “打印呼吸”。Convai 会填充 文本 参数，而处理器会打印解析后的字符串。

示例：使用动画蒙太奇跳舞

对于播放骨骼动画的动作，请使用一个 Anim Montage 并调用 处理动作完成 在两个 On Completed 和 已中断 蒙太奇引脚上。

准备蒙太奇

1. 导入或定位位于 内容浏览器.
2. 右键单击一个动画，选择 创建 > 创建 Anim Montage.
3. 打开蒙太奇并调整 混入 和 混出 时间（例如 1.0 秒），这样过渡看起来更平滑。
4. 对你想支持的每种舞蹈风格重复此步骤。

声明动作

添加一个名为 舞蹈 的无参数动作，用于单风格舞蹈，或者添加一个 类型 参数，并使用 Choices 当多个风格共用一个动作时（见下一节）。

使用 Play Montage 的处理器

// Blueprint 伪代码 — 单个蒙太奇
Event Dance(ActionData: FConvaiResultAction)
    播放蒙太奇(
        网格体 = BodySkeletalMesh,
        蒙太奇 = GrooveDanceMontage,
        OnCompleted → HandleActionCompletion(IsSuccessful = true),
        OnInterrupted → HandleActionCompletion(IsSuccessful = true)
    )

如果 处理动作完成 缺失于 已中断 引脚上，则新的蒙太奇或移动动作可能会使队列卡住，因为插件仍认为舞蹈动作正在进行。

示例：使用选项和回退进行舞蹈

当一个动作涵盖多个动画变体时，添加一个 String 参数，并使用一个 Choices 数组，而不是复制动作模板。

声明

Action 舞蹈，一个参数：

字段	值
名称	类型
类型	String
Choices	律动, 迪斯科, g 风格 （每个受支持的蒙太奇一项）

传输格式中包含 [律动|迪斯科|g 风格] ，这样 Convai 就会从列表中选择。

带有字符串切换的处理器

// Blueprint 伪代码
Event Dance(ActionData: FConvaiResultAction)
    DanceType = GetParamAsString(ActionData, "type")

    Switch on String(DanceType):
        case "groove":  PlayMontage(GrooveMontage, onComplete, onInterrupted)
        case "disco":   PlayMontage(DiscoMontage, onComplete, onInterrupted)
        case "g-style": PlayMontage(GStyleMontage, onComplete, onInterrupted)
        default:
            HandleActionCompletion(
                IsSuccessful = false,
                bAutoReport = true,
                ShouldRespond = Always,
                AdditionalNote = "这种舞蹈风格不可用",
                Delay = 1.5
            )
            return

    // onComplete 和 onInterrupted 都会调用：
    HandleActionCompletion(IsSuccessful = true, ShouldRespond = Never)

当玩家请求一个超出 Choices （例如 "ballet"的风格时， 默认 分支会报告失败。Convai 可以使用 附加说明 上下文进行响应，而不是播放不受支持的蒙太奇。

连接词

在每个阶段加载时，对聊天机器人组件使用 连接词 将参数链接到前面的文本。例如， “将 <object> 放到 <surface> 上”:

• 参数 1： 名称 = "object"，无连接词。
• 参数 2： 名称 = "surface", 连接词 = "on".

枚举参数

当一个 UENUM 已存在于你的项目中：

1. 设置 类型 为 Enum.
2. 设置 EnumType 到该枚举资源。
3. 保留 Choices 留空 — 显示名称来自枚举。

使用 按字节获取参数读取匹配到的值，然后用 字节转枚举.

在 Blueprint 中读取参数

请使用 UConvaiActions 函数库（Convai | 动作 API):

节点	返回值	适用于
Get First Param	FConvaiResultParam	恰好一个参数。
获取参数	FConvaiResultParam	命名参数的完整结构体。
按字符串获取参数	FString	String 或 Auto.
Get Param As Number	float	Number.
按布尔值获取参数	bool	Bool.
Get Param As Ref	FConvaiObjectEntry	Reference 或 Auto.
按字节获取参数	uint8	Enum.
是否有参数	bool	读取前先进行保护。

当必需参数为空时中止

// Blueprint 伪代码
RefEntry = GetParamAsRef(ActionData, "destination")
如果 RefEntry.Ref 为 None：
    AbortActionSequence(
        EventText = "未在场景中找到目的地",
        ShouldRespond = Always
    )
    return

FConvaiActionParam 字段参考

模板上的每个参数都是一个 FConvaiAction 结构体： FConvaiActionParam 占位符名称，例如

字段	类型	目的
名称	FString	给 Convai 的可选提示。保持简短或留空，以减少上下文大小。 "destination" 或 “text”.
描述	FString	声明的类型。控制传输格式提示和解析器行为。
类型	EConvaiActionParamType	此参数前的连接文本，例如
连接词	FString	“将球放在桌子上” "on" 在 固定选项列表，显示为.
Choices	TArray<FString>	[选项1|选项2|...] 在传输格式中。 完整类型行为：
EnumType	UEnum*	时必需 类型 == 枚举.

枚举值

值如何解析	显示名称	推断：引用、数字、布尔；最后回退到字符串。
Auto	Auto	推断为：先引用，然后数字，再布尔；最后回退到字符串。
Reference	Actor 引用	解析为已注册的 对象 和 角色 按精确名称。
String	String	原始字符串。
Number	Number	解析为 float.
Bool	Bool	"true", "是"，或 "1" → true；否则 false.
Enum	Enum	匹配 EnumType的显示名称；值存储在 ByteValue.

无论声明的类型如何， FConvaiResultParam 上的所有值字段都会尽力填充。

下一步

动作 Blueprint 参考注意力与引用锚定角色动作示例