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

{% embed url="<https://www.youtube.com/watch?v=cOiG863n3lA>" %}
参数化动作演练
{% endembed %}

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

### 前提条件

* 你已完成 [构建自定义动作处理器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/building-custom-action-handlers.md) ，用于无参数动作。
* 在你以 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)
    )
```

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

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

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

#### 声明

动作 `舞蹈`，一个参数：

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

### 下一步

{% content-ref url="/pages/8e18d509947b40274dca96b384f432486348198f" %}
[Actions 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:

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

The question should be specific, self-contained, and written in natural language.
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.