> 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 在选择操作时填入已类型化的值。一个 `移动到` 操作需要一个目的地；一个 `Print` 操作可以携带动态文本；一个 `舞蹈` 操作可以从固定的动画风格列表中选择。参数为 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 可以提供消息。

#### 声明参数

在 `Print` 操作条目，展开 **参数** 并点击 **+**:

| 字段   | 值                        |
| ---- | ------------------------ |
| `名称` | `text`                   |
| `类型` | `字符串`                    |
| `说明` | 留空或使用简短提示，例如 `“要打印的文本”`. |

编译蓝图。

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

```cpp
// Blueprint 伪代码
事件 Print(ActionData: FConvaiResultAction)
    Message = GetParamAsString(ActionData, "text")
    打印字符串(Message)
    HandleActionCompletion(IsSuccessful = true, ShouldRespond = Never)
```

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

### 示例：使用动画 Montage 进行舞蹈

对于播放骨骼动画的操作，请使用 `动画 Montage` 并调用 `处理动作完成` 在两个 **On Completed** 和 **中断时** Montage 引脚。

#### 准备 Montage

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

#### 声明操作

添加一个名为 `舞蹈` 的无参数操作用于单一风格舞蹈，或者添加一个 `类型` 带有 **选择** 当多个风格共享一个操作时（见下一节）。

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

```cpp
// 蓝图伪代码 — 单个 Montage
事件 Dance(ActionData: FConvaiResultAction)
    播放 Montage(
        Mesh = BodySkeletalMesh,
        Montage = GrooveDanceMontage,
        OnCompleted → HandleActionCompletion(IsSuccessful = true),
        OnInterrupted → HandleActionCompletion(IsSuccessful = true)
    )
```

{% hint style="warning" %}
如果 `处理动作完成` 在……上缺少 **中断时** 引脚时，新的 Montage 或移动操作可能会使队列停滞，因为插件仍将舞蹈操作视为正在进行中。
{% endhint %}

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

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

#### 声明

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

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

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

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

```cpp
// 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
            )
            返回

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

当玩家请求某个超出范围的风格时 **选择** （例如 `“芭蕾”`）， **默认值** 分支会报告失败。Convai 可以使用 `AdditionalNote` 上下文进行响应，而不是播放不受支持的 Montage。

### 连接词

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

* 参数 1： `名称 = "object"`，无连接词。
* 参数 2： `名称 = "surface"`, `连接词 = "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** | `float`              | `数字`.         |
| **Get Param As Bool**   | `bool`               | `布尔值`.        |
| **Get Param As Ref**    | `FConvaiObjectEntry` | `引用` 或 `自动`.  |
| **Get Param As Byte**   | `uint8`              | `枚举`.         |
| **Has Param**           | `bool`               | 读取前进行检查。      |

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

```cpp
// Blueprint 伪代码
RefEntry = GetParamAsRef(ActionData, "destination")
如果 RefEntry.Ref 为 None：
    AbortActionSequence(
        EventText = "场景中未找到目的地",
        ShouldRespond = Always
    )
    返回
```

### FConvaiActionParam 字段参考

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

| 字段         | 类型                       | 作用                                         |
| ---------- | ------------------------ | ------------------------------------------ |
| `名称`       | `FString`                | 占位符名称，例如 `“destination”` 或 `“text”`.       |
| `说明`       | `FString`                | 给 Convai 的可选提示。保持简短或留空，以减少上下文大小。           |
| `类型`       | `EConvaiActionParamType` | 声明的类型。控制线格式提示和解析器行为。                       |
| `连接词`      | `FString`                | 在此参数前连接的文本，例如 `“on”` 在 `“将球放在桌子上”`.        |
| `选择`       | `TArray<FString>`        | 固定选项列表显示为 `[choice1\|choice2\|...]` 在线格式中。 |
| `EnumType` | `UEnum*`                 | 在以下情况下必需 `Type == Enum`.                   |

完整类型行为：

| 枚举定义的七个可见类别 | 显示名称     | 值的解析方式                                         |
| ----------- | -------- | ---------------------------------------------- |
| `自动`        | 自动       | 推断：引用，其次数字，然后布尔；最后回退到字符串。                      |
| `引用`        | Actor 引用 | 根据已注册的 `对象` 和 `Characters` 按精确名称解析。            |
| `字符串`       | 字符串      | 原始字符串。                                         |
| `数字`        | 数字       | 解析为 `float`.                                   |
| `布尔值`       | 布尔值      | `"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 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.