> 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/unreal-engine-plugin-beta-overview/convai-actions/phase-3-parameterized-actions.md).

# 第 3 阶段：参数化动作

第 2 阶段新增了一个无参数的自定义动作。大多数真实动作都需要携带数据—— *“等待 5 秒”*, *“拿起立方体”*, *“把球放到桌子上”*。本阶段将讲解：

1. 一个简单的数值参数（`Wait For` 的回顾）。
2. 一个角色引用（单个参数解析为一个 `AActor*`).
3. 一个带两个参数 + 一个连接词的复合动作（`Put ... on ...`).
4. 通过以下方式约束值： `Choices` （手动列表）和 `Enum` （取自一个 `UENUM`).
5. 实时编辑器预览——既可作为调试辅助，也可直接用于编写模板。

### 参数类型矩阵

每个 `FConvaiActionParam` 都有一个 **`Type`** 字段，它同时决定发送给 LLM 的线协议提示以及解析器如何解释响应：

| Type          | 线协议提示     | 解析器                                                     |
| ------------- | --------- | ------------------------------------------------------- |
| **Auto**      | （无）       | 按 Reference → Number → Bool 的顺序尝试，最后回退到 String。新参数的默认值。 |
| **Reference** | `：ref`    | 根据以下内容查找该值： `Environment.Objects` 然后 `.Characters`.     |
| **String**    | `：string` | 按文本处理。                                                  |
| **Number**    | `：number` | `Atof`.                                                 |
| **Bool**      | `：bool`   | `true` 用于“true”/“yes”/“1”，否则为 false。                    |
| **Enum**      | `：enum`   | 约束为你选择的一个 `UEnum` （自动填充 `Choices`).                     |

> 无论声明的类型是什么， **上所有值字段 `FConvaiResultParam` 都会尽力填充。**一个 `String`类型的参数，即使其值刚好是场景中某个对象的名称，也仍然会有 `RefValue` 被设置。读取你觉得方便的字段即可—— `Type` 它只表示 LLM 期望填入的是哪个槽位。

### 示例 A——数值参数

我们重新来过 `Wait For` ，展示 typed-param 流程的完整端到端过程。

#### 声明模板

1. 选择 Convai 聊天机器人，打开 **Environment → Actions**.
2. 随附的 **`Wait For`** 条目已经有一个参数 `秒数` 已类型化 `Number` ，描述为 *“等待多长时间，单位为秒”*。可直接使用，或添加你自己的。

渲染后的预览（在结构化字段下方自动填充）如下：

```
Wait For "<time in seconds: number>" — 等待一段时长。time in seconds：等待多长时间，单位为秒。
```

该 `：number` 提示会告诉 LLM 返回一个数值。 `"<...>"` 加上引号包装则会让它用双引号输出响应值，这样即使值中包含空格，解析器也能明确无歧义地拆分。

#### 在 BP 中读取参数

在你的 `OnActionReceivedEvent_V2` 处理器中的 `Wait For` switch 分支：

1. 拖一个 **`Get Param As Number`** 节点从聊天机器人引用上拉出。
   * **Action**：当前的 `FConvaiResultAction` ，来自循环。
   * **Name**: `秒数`.
2. 把返回的 `float` 连接到一个 **`Delay (Duration)`** 节点。
3. 延迟结束后，调用 `Handle Action Completion(true, 0, EventText="Done waiting", ShouldRespond=Auto)`.

该 `EventText` 参数可让你告诉机器人 *“这已经完成了”* ，并且在同一次调用中完成——这对于在不单独调用 `Add Context Event`.

#### 测试

提问： *“等待 3 秒。”* 机器人应当暂停，然后说 *“Done waiting”* 或类似的话（取决于 `ShouldRespond` 以及 LLM 的情绪）。

### 示例 B——角色引用

`Move To` 默认随附配置已经这么做了，但这里给出一个自定义配置的配方。

#### 声明

添加一个动作 `Greet` ，带一个参数：

* **Name**: `target`
* **Type**: `Reference`
* **描述**: `要问候谁`

预览变为：

```
Greet "<target: ref>" — <action description if any>. target：要问候谁。
```

#### 在 BP 中读取

1. **`Get Param As Ref`** ，使用 `Name = "target"` 会返回一个 `FConvaiObjectEntry`。该 `Ref` 字段是解析出的 `AActor*` （因为该值匹配到了 `Environment.Objects` 中的某个内容，自动设置） `.Characters`).
2. 或 `Greet` 使用该角色——让他们转向、播放动画，或者取决于你的

### 意思。

*示例 C——带连接词的复合动作* 可以用两个 `Reference` 参数和一个用于第二个参数的连接词来清晰表达：

#### 声明

Action `Put`，两个参数：

| Name    | Type      | 连接词        | 描述    |
| ------- | --------- | ---------- | ----- |
| `ball`  | Reference | （空——第一个参数） | 要拿起什么 |
| `table` | Reference | `on`       | 放置到哪里 |

预览：

```
Put "<ball: ref>" on "<table: ref>" — 将一个物体放到另一个物体上。ball：要拿起什么。table：放置到哪里。
```

该 `连接词` 字段 **不是** 仅限于介词——它可以是“任何将参数与前文关联起来的文本”。 `到`, `，使用`, `使用`, `用于`，等等，都可以。

#### 在 BP 中读取

```
Get Param As Ref(action, "ball")  → FConvaiObjectEntry（球）
Get Param As Ref(action, "table") → FConvaiObjectEntry（桌子）
```

只要 LLM 选择的名称与你的 `Ref` 匹配，两者的 `Environment.Objects`.

### 都会被填充。

示例 D——受约束的值（Choices） **如果你希望 LLM 从一个**固定列表 `Choices`:

#### 声明

Action `中选择，请填充`，一个参数：

* **Name**: `mood`
* **Type**: `String`
* **描述**: `机器人应该呈现的状态`
* **Choices**: `happy`, `sad`, `angry`

预览：

```
Set Mood "<mood [happy|sad|angry]: string>" — 设置机器人情绪。mood：机器人应该呈现的状态。
```

该 `[choices]` 在线协议格式中的这个块会约束 LLM。解析器在接收时也会根据该列表进行验证——不在集合中的值仍会进入结果，但会记录警告。

### 示例 E——Enum 类型的值

当你的 Blueprint 已经有一个 `UENUM` 想要使用的时，将该参数 **Type** 到 **`Enum`**&#x5207;换过去。Details 面板会隐藏手动的 `Choices` 字段，并显示一个 **`Enum Type`** 选择器。

#### 声明

```cpp
UENUM(BlueprintType)
enum class EBotMood : uint8 { Happy, Sad, Angry };
```

Action `中选择，请填充`，一个参数：

* **Type**: `Enum`
* **Enum Type**: `EBotMood`
* **Name** / **描述**：与之前一样。

预览：

```
Set Mood "<mood [Happy|Sad|Angry]: enum>" — 设置机器人情绪。mood：机器人应该呈现的状态。
```

Choice 块会根据枚举的显示名称自动派生。如果你忘记设置 `Enum Type`，预览会内联嵌入 `[ERROR: EnumType not set]` ，这样配置错误在编辑时就会非常明显。

#### 在 BP 中读取

`Get Param As String(action, "mood")` 返回 `“Happy”` / `“Sad”` / `“Angry”`。使用以下方式把它转换为枚举值： **`Convert String to Byte`** 或 UE 为 `EBotMood`.

### 渲染字符串——调试 + 编写

该 **`Rendered String`** 字段在每个 `FConvaiAction` 上都是一个支持双向同步的多行文本框：

* **读取它** 即可准确看到发送给 LLM 的内容。适用于：
  * 在连接之前检查你的描述是否合理。
  * 粘贴到其他工具中测试提示词变体。
  * 并排比较两个角色的动作契约。
* **写入它** ，结构化字段就会更新。插件会把该格式解析 `Name <connector> "<param: type>"… — Description. param: desc.` 回 Name / Description / Parameters。适用于：
  * 在角色之间粘贴模板。
  * 快速编辑长描述，而无需在嵌套结构字段中滚动。

> **如果你的编辑无法被干净地解析** （括号损坏、无法识别的类型词等），预览会在下一次刷新时静默回退为结构化字段的规范渲染。只要遵守格式规则，就不会有问题。

这种双向同步是保守的：只有当渲染字符串实际上与结构化字段生成的内容不同时，才会重新解析，因此偶发提交（焦点变化、误点击）不会降低类型。

### 从旧字段迁移

如果你有较旧的处理器图在读取 `FConvaiResultAction.RelatedObjectOrCharacter` 中的某个内容，自动设置） `.ConvaiExtraParams.Number/Text`，它们仍然可以编译——这些字段作为新 `Parameters` 映射的已弃用镜像而被填充。BP 节点提示会显示指向替代项的弃用信息：

| 旧版                                    | 新版                                                              |
| ------------------------------------- | --------------------------------------------------------------- |
| `Result.RelatedObjectOrCharacter.Ref` | `Get Param As Ref(action, "<name>").Ref` （或 `Get First Param`). |
| `Result.ConvaiExtraParams.Number`     | `Get Param As Number(action, "<name>")`.                        |
| `Result.ConvaiExtraParams.Text`       | `Get Param As String(action, "<name>")`.                        |
| `Get Action Param(extraParams, name)` | `Get Param As String(action, name)`.                            |

你可以按处理器逐个迁移，按自己的节奏来；没有任何东西强制你立即重写。

### 下一步去哪

你现在已经知道：

* 参数类型矩阵以及它生成的线协议格式。
* 如何使用连接词来构建复合动作。
* 如何通过 `Choices` 中的某个内容，自动设置） `Enum`.
* 如何通过类型化访问器在 Blueprint 中读取参数。
* 如何使用渲染预览进行调试或直接编写。

这就是完整的动作编写界面。关于驱动一切的运行时契约（四条服务器提示通道、动态上下文管线、场景元数据更新、对话伙伴、注视目标），请参见插件内参考： **`Convai/Docs/ActionsAndEnvironment.md`** 以及更深入的 V2 参考： **`Convai/Docs/ActionsV2.md`**.


---

# 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/unreal-engine-plugin-beta-overview/convai-actions/phase-3-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.