> 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/parameterized-actions.md).

# 参数化动作

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

参数化动作允许 Convai 在选择动作时填入指定类型的值。一个 `Move To` 动作需要一个目的地；一个 `Print` 动作可以携带动态文本；一个 `Dance` 动作可以从固定列表中选择动画样式。参数为 Convai 提供结构化指引，也为你的处理程序提供可读取的类型化值。

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

{% embed url="<https://youtu.be/gNILGcnjgck>" %}
自定义动作与参数化动作演练
{% endembed %}

### 前提条件

* 你已完成 [构建自定义动作处理程序](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/building-custom-action-handlers.md) ，了解了无参数动作。
* 在 Play 模式下测试之前，请先在角色蓝图中编译动作模板。

### 选择参数类型

使用 `String` 表示自由格式文本， **Actor Reference** 表示已注册的对象或角色， `Number` 表示数值，以及 `String` 并搭配 **Choices** 表示仅有少数有效值的情况（例如固定的舞蹈风格列表）。完整类型列表见下方参考表。

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

### 示例：使用字符串参数的 Print

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

#### 声明参数

在 `Print` 动作条目中，展开 **Parameters** 并点击 **+**:

| 字段            | 值                                |
| ------------- | -------------------------------- |
| `Name`        | `text`                           |
| `Type`        | `String`                         |
| `Description` | 留空，或使用简短提示，例如 `"Text to print"`. |

编译蓝图。

#### 在处理程序中读取该值

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

在播放模式下测试： `"Print your name on the screen"` 或 `"Print breathe"`。Convai 会填入 `text` 参数，处理程序会打印解析后的字符串。

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

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

#### 准备蒙太奇

1. 在 **内容浏览器**.
2. 中导入或找到动画序列。右键单击动画，选择 **创建 > 创建动画蒙太奇**.
3. 打开蒙太奇并调整 **混合进入** 和 **混合退出** 时长（例如 `1.0` 秒），使过渡效果平滑。
4. 为你希望支持的每种舞蹈风格重复以上步骤。

#### 声明操作

添加一个名为 `Dance` 的操作。单一风格的舞蹈无需参数；如果多个风格共用一个操作，则添加一个 `type` 参数，并设置 **选项** （参见下一节）。

#### 使用 Play Montage 的处理程序

```cpp
// 蓝图伪代码 — 单个蒙太奇
Event Dance(ActionData: FConvaiResultAction)
    Play Montage(
        Mesh = BodySkeletalMesh,
        Montage = GrooveDanceMontage,
        OnCompleted → HandleActionCompletion(IsSuccessful = true),
        OnInterrupted → HandleActionCompletion(IsSuccessful = true)
    )
```

{% hint style="warning" %}
如果 `Handle Action Completion` 未连接到 **On Interrupted** 引脚，新的蒙太奇或移动动作可能导致队列停滞，因为插件仍会认为舞蹈动作正在进行。
{% endhint %}

### 示例：带选项和回退方案的舞蹈

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

#### 声明

Action `Dance`，包含一个参数：

| 字段        | 值                                           |
| --------- | ------------------------------------------- |
| `Name`    | `type`                                      |
| `Type`    | `String`                                    |
| `Choices` | `groove`, `disco`, `g-style` （每种受支持的蒙太奇各一项） |

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

#### 使用 Switch on String 的处理程序

```cpp
// 蓝图伪代码
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 = "That dance style is not available",
                Delay = 1.5
            )
            return

    // onComplete and onInterrupted both call:
    HandleActionCompletion(IsSuccessful = true, ShouldRespond = Never)
```

当玩家请求的风格不在 **Choices** 中时（例如 `"ballet"`）， **default** 分支会报告失败。Convai 可以利用 `AdditionalNote` 上下文进行回复，而不是播放不受支持的蒙太奇。

### 连接器

使用 **连接词** 将参数关联到前面的文本。例如， `"Put <object> on <surface>"`:

* 参数 1： `Name = "object"`，无需连接词。
* 参数 2： `Name = "surface"`, `Connector = "on"`.

### 枚举参数

如果你的项目中已经存在 `UENUM` ：

1. 将 `Type` 设为 `Enum`.
2. 将 `EnumType` 设为对应的枚举资源。
3. 将 `Choices` 留空 — 显示名称取自枚举。

使用 `Get Param As Byte`读取匹配的值，然后使用 **Byte 转 Enum**.

### 在蓝图中读取参数

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

| 节点                      | 返回                   | 适用情况                  |
| ----------------------- | -------------------- | --------------------- |
| **Get First Param**     | `FConvaiResultParam` | 恰好一个参数。               |
| **Get Param**           | `FConvaiResultParam` | 获取指定名称参数的完整结构体。       |
| **Get Param As String** | `FString`            | `String` 或 `Auto`.    |
| **Get Param As Number** | `float`              | `Number`.             |
| **Get Param As Bool**   | `bool`               | `Bool`.               |
| **Get Param As Ref**    | `FConvaiObjectEntry` | `Reference` 或 `Auto`. |
| **获取参数（字节）**            | `uint8`              | `Enum`.               |
| **是否具有参数**              | `bool`               | 读取前进行检查。              |

### 必需参数为空时中止

```cpp
// 蓝图伪代码
RefEntry = GetParamAsRef(ActionData, "destination")
if RefEntry.Ref is None:
    AbortActionSequence(
        EventText = "Destination not found in scene",
        ShouldRespond = Always
    )
    return
```

### FConvaiActionParam 字段参考

每个 `FConvaiAction` 模板中的参数都是一个 `FConvaiActionParam` 结构体：

| 字段            | 类型                       | 用途                                           |
| ------------- | ------------------------ | -------------------------------------------- |
| `Name`        | `FString`                | 占位符名称，例如 `"destination"` 或 `"text"`.         |
| `Description` | `FString`                | 提供给 Convai 的可选提示。请保持简短或留空，以减少上下文大小。          |
| `Type`        | `EConvaiActionParamType` | 声明的类型。控制线格式提示和解析器行为。                         |
| `Connector`   | `FString`                | 此参数前的连接文本，例如 `"on"` 在 `"Put ball on table"`. |
| `Choices`     | `TArray<FString>`        | 固定选项列表，在 `[choice1\|choice2\|...]` 线格式中呈现。   |
| `EnumType`    | `UEnum*`                 | 当 `Type == Enum`.                            |

完整类型行为：

| 枚举值         | 显示名称            | 值的解析方式                                                   |
| ----------- | --------------- | -------------------------------------------------------- |
| `Auto`      | 自动              | 推断：先尝试 Reference，再尝试 Number，然后尝试 Bool；若均不匹配，则回退为 String。 |
| `Reference` | Actor Reference | 按精确名称从已注册的 `Objects` 和 `Characters` 中解析。                 |
| `String`    | 字符串             | 原始字符串。                                                   |
| `Number`    | 数值              | 解析为 `float`.                                             |
| `Bool`      | 布尔值             | `"true"`, `"yes"`，或 `"1"` → `true`；否则 `false`.           |
| `Enum`      | 枚举              | 匹配……的显示名称 `EnumType`；值存储在 `ByteValue`.                   |

无论声明的类型是什么， `FConvaiResultParam` 上的所有值字段都会尽力填充。

### 后续步骤

{% 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/4708b5833bcb3c0d451ce191750fc5274326e217" %}
[注意力与引用锚定](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/attention-and-reference-grounding.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/parameterized-actions.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.
