> 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).

# 参数化动作

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

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

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

### 先决条件

* 你已完成 [构建自定义动作处理程序](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/building-custom-action-handlers.md) 用于无参数动作。
* 动作模板会在你在播放模式下测试之前，在角色 Blueprint 上编译。

### 选择参数类型

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

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

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

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

#### 声明参数

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

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

编译 Blueprint。

#### 在处理器中读取该值

```cpp
// 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 的处理器

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

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

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

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

#### 声明

Action `舞蹈`，一个参数：

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

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

#### 带有字符串切换的处理器

```cpp
// 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`               | 读取前先进行保护。             |

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

```cpp
// 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` 上的所有值字段都会尽力填充。

### 下一步

{% content-ref url="/pages/8e18d509947b40274dca96b384f432486348198f" %}
[动作 Blueprint 参考](/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" %}
[注意力和引用锚定](/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" %}
[角色动作示例](/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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
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=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.