参数化动作

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

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

参数化动作演练

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

前提条件

• 你已完成 构建自定义动作处理器 ，用于无参数动作。
• 在你以 Play 模式测试之前，会先在角色 Blueprint 上编译该动作模板。

选择参数类型

使用 字符串 用于自由格式文本， 角色引用 用于已注册的对象或角色， 编号 用于数值，且 字符串 与 选项 当只有少数几个值有效时（例如固定的舞蹈风格列表）。完整类型列表见下面的参考表。

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

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

从无参数 Print 动作开始，并添加一个类型化输入，以便 Convai 可以提供消息。

声明参数

在 Print 动作条目，展开 参数 并点击 +:

字段	值
名称	text
类型	字符串
描述	留空，或者使用一个简短提示，例如 "要打印的文本".

编译 Blueprint。

在处理器中读取该值

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

在 Play 模式下测试： "把你的名字打印到屏幕上" 或 "打印 breathe"。Convai 会填充 text 参数，而处理器会打印解析后的字符串。

示例：使用动画蒙太奇进行舞蹈

对于播放骨骼动画的动作，请使用 Anim Montage 并在两个 Handle Action Completion 上调用 On Completed 和 On Interrupted 蒙太奇引脚。

准备蒙太奇

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

声明动作

添加一个名为 舞蹈 的无参数动作，用于单风格舞蹈；或者添加一个 type 参数，并带有 选项 ，用于多个风格共享同一个动作时（见下一节）。

带 Play Montage 的处理器

// Blueprint 伪代码 — 单个蒙太奇
事件 Dance(ActionData: FConvaiResultAction)
    Play Montage(
        Mesh = BodySkeletalMesh,
        Montage = GrooveDanceMontage,
        OnCompleted → HandleActionCompletion(IsSuccessful = true),
        OnInterrupted → HandleActionCompletion(IsSuccessful = true)
    )

如果 Handle Action Completion 在该 On Interrupted 引脚上，新的蒙太奇或移动动作可能会使队列停滞，因为插件仍然认为舞蹈动作正在进行中。

示例：使用选项和兜底的舞蹈

当一个动作覆盖多个动画变体时，请添加一个 字符串 参数，并带有一个 选项 数组，而不是复制动作模板。

声明

动作 舞蹈，一个参数：

字段	值
名称	type
类型	字符串
选项	groove, disco, g-style （每个受支持的蒙太奇一项）

线格式包含 [groove|disco|g-style] ，因此 Convai 会从列表中选择。

带 String 上 Switch 的处理器

// Blueprint 伪代码
事件 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)

当玩家请求的风格超出 选项 （例如 "芭蕾"）时， default 分支会报告失败。Convai 可以使用 AdditionalNote 上下文进行响应，而不是播放不受支持的蒙太奇。

连接符

使用 连接符 用于将参数连接到前面的文本。例如 "将 <object> 放在 <surface> 上":

• 参数 1： Name = "object"，无连接符。
• 参数 2： Name = "surface", Connector = "on".

枚举参数

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

1. 设置 类型 到 枚举.
2. 设置 EnumType 指向该枚举资源。
3. 保持 选项 留空——显示名称来自枚举。

使用 Get Param As Byte读取匹配值，然后使用 Byte to Enum.

在 Blueprint 中读取参数

使用 UConvaiActions 函数库（Convai | Action API):

节点	返回	适用于
Get First Param	FConvaiResultParam	恰好一个参数。
Get Param	FConvaiResultParam	指定参数的完整结构体。
Get Param As String	FString	字符串 或 自动.
Get Param As Number	float	编号.
Get Param As Bool	bool	布尔值.
Get Param As Ref	FConvaiObjectEntry	引用 或 自动.
Get Param As Byte	uint8	枚举.
Has Param	bool	读取前先保护。

当必需参数为空时中止

// Blueprint 伪代码
RefEntry = GetParamAsRef(ActionData, "destination")
if RefEntry.Ref is None:
    AbortActionSequence(
        EventText = "在场景中找不到目的地",
          ShouldRespond = Always
    )
    return

FConvaiActionParam 字段参考

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

字段	类型	用途
名称	FString	"destination" "text" 或 可选提示，供 Convai 使用。保持简短或留空，以减少上下文大小。.
描述	FString	可选提示，供 Convai 使用。保持简短或留空，以减少上下文大小。
类型	EConvaiActionParamType	声明的类型。控制线格式提示和解析器行为。
连接符	FString	该参数前的连接文本，例如 "on" 在 "将球放在桌子上".
选项	TArray<FString>	固定选项列表在 [choice1|choice2|...] 中以线格式呈现。
EnumType	UEnum*	当 Type == Enum.

完整类型行为：

枚举值	显示名称	值如何被解析
自动	自动	推断：引用，其次数字，其次布尔；最后回退为字符串。
引用	角色引用	按精确名称解析到已注册的 对象 和 角色 。
字符串	字符串	原始字符串。
编号	编号	解析为 float.
布尔值	布尔值	"true", "yes"，或 "1" → true；否则 false.
枚举	枚举	匹配 EnumType的显示名称；值存储在 ByteValue.

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

下一步

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