> 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) 用于无参数动作。
* 在你进行 Play 模式测试之前，动作模板会先在角色蓝图中编译。

### 选择参数类型

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

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

### 示例：带字符串参数的 Print

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

#### 声明参数

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

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

编译蓝图。

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

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

在 Play 模式中测试： `“把你的名字打印到屏幕上”` 或 `“打印 breathe”`。Convai 会填充 `文本` 参数，处理器会打印解析后的字符串。

### 示例：使用动画蒙太奇的 Dance

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

#### 准备蒙太奇

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

#### 声明动作

添加一个名为 `舞蹈` 的动作，不带参数用于单一风格舞蹈，或者添加一个 `类型` 参数，使用 **选项** 当多种风格共用一个动作时（见下一节）。

#### 使用 Play Montage 的处理器

```
// 蓝图伪代码 — 单个蒙太奇
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 %}

### 示例：使用选项和回退的 Dance

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

#### 声明

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

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

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

#### 使用 Switch on String 的处理器

```
// 蓝图伪代码
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)
        默认：
            HandleActionCompletion(
                IsSuccessful = false,
                bAutoReport = true,
                ShouldRespond = Always,
                AdditionalNote = "该舞蹈风格不可用",
                Delay = 1.5
            )
            return

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

当玩家请求一个超出 **选项** （例如 `“ballet”`）的风格时， **默认** 分支会报告失败。Convai 可以使用 `AdditionalNote` 上下文作出回应，而不是播放不受支持的蒙太奇。

### 连接词

使用 **连接词** 用于将参数与前面的文本连接起来。例如 `“把 <object> 放在 <surface> 上”`:

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

### 枚举参数

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

1. 将 `类型` 到 `枚举`.
2. 将 `EnumType` 到枚举资源。
3. 保持 `选项` 留空——显示名称来自枚举。

使用以下方式读取匹配的值 `Get Param As Byte`，然后使用以下方式转换 **Byte to Enum**.

### 在蓝图中读取参数

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

| 节点                      | 返回                   | 何时使用          |
| ----------------------- | -------------------- | ------------- |
| **Get First Param**     | `FConvaiResultParam` | 恰好一个参数。       |
| **Get Param**           | `FConvaiResultParam` | 命名参数的完整结构体。   |
| **Get Param As String** | `FString`            | `字符串` 或 `自动`. |
| **Get Param As Number** | `浮点数`                | `数值`.         |
| **Get Param As Bool**   | `布尔值`                | `布尔`.         |
| **Get Param As Ref**    | `FConvaiObjectEntry` | `引用` 或 `自动`.  |
| **Get Param As Byte**   | `uint8`              | `枚举`.         |
| **Has Param**           | `布尔值`                | 读取前进行检查。      |

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

```
// 蓝图伪代码
RefEntry = GetParamAsRef(ActionData, "destination")
if RefEntry.Ref is None:
    AbortActionSequence(
        EventText = "场景中未找到目标",
        ShouldRespond = Always
    )
    return
```

### FConvaiActionParam 字段参考

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

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

完整类型行为：

| 枚举值   | 显示名称     | 值的解析方式                                          |
| ----- | -------- | ----------------------------------------------- |
| `自动`  | 自动       | 推断：先引用，再数值，再布尔；最后回退到字符串。                        |
| `引用`  | Actor 引用 | 解析匹配已注册的 `对象` 和 `角色` 通过精确名称。                    |
| `字符串` | 字符串      | 原始字符串。                                          |
| `数值`  | 数值       | 解析为 `浮点数`.                                      |
| `布尔`  | 布尔       | `"true"`, `"yes"`，或者 `"1"` → `true`；否则 `false`. |
| `枚举`  | 枚举       | 匹配以下项的显示名称 `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.