> 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/narrative-design/narrative-design-blueprint-reference.md).

# 叙事设计 Blueprint 参考

叙事设计 API 涵盖两个部分：实例函数和位于 `UConvaiChatbotComponent` （Blueprint 显示名称 **Convai 聊天机器人**），以及位于下方的独立异步获取节点 **Convai|REST API** 用于从 Convai 查询叙事数据。以下结构体描述了这两个部分中使用的数据形状。

### 异步获取节点

这些节点是独立的潜在 Blueprint 函数，不是 `UConvaiChatbotComponent`上的方法。它们向 Convai 发起 HTTPS POST 请求，并通过 **成功时** / **失败时** 执行引脚。参见 [获取叙事数据](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/fetching-narrative-data.md) 以获取使用指南。

#### Convai 获取叙事章节

C++ 类： `UFetchNarrativeSectionsProxy`\
Blueprint 显示名称： **Convai 获取叙事章节**\
类别： `Convai|REST API`\
访问权限： `BlueprintCallable` （潜在异步代理）\
端点： `character/narrative/list-sections`

| 引脚            | 方向     | 类型                          | 说明                                      |
| ------------- | ------ | --------------------------- | --------------------------------------- |
| `CharacterId` | 输入     | `FString`                   | 要查询的角色 ID。                              |
| `成功时`         | 输出（执行） | —                           | 当 HTTP 请求成功且各章节被解析到输出数组中时触发。            |
| `失败时`         | 输出（执行） | —                           | 当激活验证失败、响应指针无效，或 HTTP 响应超出 `2xx` 范围时触发。 |
| `叙事章节`        | 输出     | `TArray<FNarrativeSection>` | 返回的章节。失败时为空。                            |

**日志类别：** `ConvaiNarrativeHTTP`

| 消息                                                     | 当                |
| ------------------------------------------------------ | ---------------- |
| `无法获取世界指针！`                                            | 激活时世界上下文无效。      |
| `无法获取 HTTP 模块指针！`                                      | HTTP 模块不可用。      |
| `UFetchNarrativeSectionsProxy::Activate 无效的角色或 API 密钥` | 认证密钥或角色 ID 验证失败。 |
| `HTTP 请求失败，代码为 %d`                                     | 非 2xx HTTP 响应。   |

如果 HTTP 请求成功，但响应数组无法解析为 `FNarrativeSection` 条目，则代理可能在不触发 **成功时** 或 **失败时**.

***

#### Convai 获取叙事触发器

C++ 类： `UFetchNarrativeTriggersProxy`\
Blueprint 显示名称： **Convai 获取叙事触发器**\
类别： `Convai|REST API`\
访问权限： `BlueprintCallable` （潜在异步代理）\
端点： `character/narrative/list-triggers`

| 引脚            | 方向     | 类型                          | 说明                                      |
| ------------- | ------ | --------------------------- | --------------------------------------- |
| `CharacterId` | 输入     | `FString`                   | 要查询的角色 ID。                              |
| `成功时`         | 输出（执行） | —                           | 当 HTTP 请求成功且触发器被解析到输出数组中时触发。            |
| `失败时`         | 输出（执行） | —                           | 当激活验证失败、响应指针无效，或 HTTP 响应超出 `2xx` 范围时触发。 |
| `叙事触发器`       | 输出     | `TArray<FNarrativeTrigger>` | 返回的触发器。失败时为空。                           |

**日志类别：** `ConvaiNarrativeHTTP`

| 消息                                                     | 当                |
| ------------------------------------------------------ | ---------------- |
| `无法获取世界指针！`                                            | 激活时世界上下文无效。      |
| `无法获取 HTTP 模块指针！`                                      | HTTP 模块不可用。      |
| `UFetchNarrativeTriggersProxy::Activate 无效的角色或 API 密钥` | 认证密钥或角色 ID 验证失败。 |
| `HTTP 请求失败，代码为 %d`                                     | 非 2xx HTTP 响应。   |

如果 HTTP 请求成功，但响应数组无法解析为 `FNarrativeTrigger` 条目，则代理可能在不触发 **成功时** 或 **失败时**.

***

### 位于 `UConvaiChatbotComponent`

#### 调用叙事设计触发器

C++ 名称： `InvokeNarrativeDesignTrigger`\
类别： `Convai`\
访问权限： `BlueprintCallable`

通过 `SendTriggerMessage` 作为 `触发消息` 数据包，其中包含 `trigger_name`。在断开连接时，会排队到 `PendingTriggers` 并在会话连接后回放。

| 参数                     | 类型        | 说明                           |
| ---------------------- | --------- | ---------------------------- |
| `TriggerName`          | `FString` | 触发器名称。必须与仪表板配置完全一致。          |
| `InGenerateActions`    | `bool`    | 存在于 Blueprint 签名中。当前插件源码未应用。 |
| `InReplicateOnNetwork` | `bool`    | 存在于 Blueprint 签名中。当前插件源码未应用。 |

返回：无。

**日志类别：** `ConvaiChatbotComponentLog`

| 消息                                                      | 当                 |
| ------------------------------------------------------- | ----------------- |
| `调用叙事设计触发器：缺少 TriggerName`                              | `TriggerName` 为空。 |
| `调用叙事设计触发器：已执行 \| Character ID : %s \| Session ID : %s` | 触发器已接受，准备发送或入队。   |

***

#### 调用语音

C++ 名称： `ExecuteNarrativeTrigger`\
类别： `Convai`\
访问权限： `BlueprintCallable`

通过 `AddContextEvent` 其带有 `EC_RunLLMOption::Always`。不发送 `触发消息` 数据包，也不使用 `PendingTriggers`.

| 参数                     | 类型        | 说明                           |
| ---------------------- | --------- | ---------------------------- |
| `TriggerMessage`       | `FString` | 作为上下文事件暂存的消息字符串。             |
| `InGenerateActions`    | `bool`    | 存在于 Blueprint 签名中。当前插件源码未应用。 |
| `InReplicateOnNetwork` | `bool`    | 存在于 Blueprint 签名中。当前插件源码未应用。 |

返回：无。

**日志类别：** `ConvaiChatbotComponentLog`

| 消息                                                 | 当                    |
| -------------------------------------------------- | -------------------- |
| `调用语音：缺少 TriggerMessage`                           | `TriggerMessage` 为空。 |
| `调用语音：已执行 \| Character ID : %s \| Session ID : %s` | 消息已接受，准备暂存。          |

***

### 位于 `UConvaiChatbotComponent`

#### 收到叙事章节时触发

C++ 名称： `OnNarrativeSectionReceivedEvent`\
类别： `Convai`\
访问权限： `BlueprintAssignable`

当 Convai 返回一个 `BTResponse` 数据包并传递该数据包的 `narrative_section_id`。插件广播事件时不会检查 ID 是否为新的或非空。

| 参数                   | 类型                         | 说明                                            |
| -------------------- | -------------------------- | --------------------------------------------- |
| `ChatbotComponent`   | `UConvaiChatbotComponent*` | 接收章节更新的组件。                                    |
| `NarrativeSectionID` | `FString`                  | 该 `narrative_section_id` 来自 `BTResponse` 数据包。 |

***

### 上的属性 `UConvaiChatbotComponent`

#### 叙事模板键

C++ 名称： `NarrativeTemplateKeys`\
类型： `TMap<FString, FString>`\
类别： `Convai|NarrativeDesign`\
访问权限： `BlueprintReadWrite, EditAnywhere`\
Blueprint 设置器： `UpdateNarrativeTemplateKeys` (`BlueprintInternalUseOnly`)

通过 `update-template-keys` 当会话已连接时。分配该属性会触发 `UpdateNarrativeTemplateKeys`，它会存储该映射，并在会话代理处于活动状态时发送它。

#### bAutoInitializeSession

C++ 名称： `bAutoInitializeSession`\
类型： `bool`\
类别： `Convai|Session`\
访问权限： `BlueprintReadWrite, EditAnywhere`\
默认值： `true`

当 `true`，调用 `StartSession` on **开始游戏**.

***

### 叙事结构体

这些结构体是 `BlueprintType`。标记为 `BlueprintReadOnly` 在 Blueprint 中可见。它们描述了 Convai 仪表板中定义的章节、触发器和决策的数据模型。

#### FNarrativeSection

表示叙事图中的一个章节（故事节拍）。

| 字段                       | 类型                           | Blueprint 访问 | 说明                                  |
| ------------------------ | ---------------------------- | ------------ | ----------------------------------- |
| `section_id`             | `FString`                    | 只读           | 此章节的唯一标识符。                          |
| `section_name`           | `FString`                    | 只读           | 在仪表板中显示的人类可读名称。                     |
| `目标`                     | `FString`                    | 只读           | 此章节的行为目标。                           |
| `character_id`           | `FString`                    | 只读           | 此章节所属的角色。                           |
| `behavior_tree_code`     | `FString`                    | 只读           | 用于高级自动化的行为树代码（可能为空）。                |
| `bt_constants`           | `FString`                    | 只读           | 所引用的常量 `behavior_tree_code` （可能为空）。 |
| `决策`                     | `TArray<FNarrativeDecision>` | 只读           | 此章节的外发决策规则。                         |
| `parents`                | `TArray<FString>`            | 只读           | 图中父章节的章节 ID。                        |
| `updated_character_data` | `TMap<FString, FString>`     | 只读           | 当此章节变为活动状态时应用的角色数据覆盖。               |

***

#### FNarrativeTrigger

表示章节之间的一个命名触发器边。

| 字段                    | 类型        | Blueprint 访问 | 说明                               |
| --------------------- | --------- | ------------ | -------------------------------- |
| `trigger_id`          | `FString` | 只读           | 此触发器的唯一标识符。                      |
| `trigger_name`        | `FString` | 只读           | 由 **调用叙事设计触发器**.                 |
| `trigger_message`     | `FString` | 只读           | 与该触发器关联的消息内容。                    |
| `destination_section` | `FString` | 只读           | 该 `section_id` 当此触发器触发时，图前进到的章节。 |

***

#### FNarrativeDecision

表示章节中的一条外发决策规则。

| 字段                | 类型        | Blueprint 访问 | 说明                              |
| ----------------- | --------- | ------------ | ------------------------------- |
| `criteria`        | `FString` | 只读           | 此决策适用的条件。                       |
| `next_section_id` | `FString` | 只读           | 该 `section_id` 在满足条件时前进到的章节 ID。 |
| `priority`        | `int32`   | 只读           | 此决策规则的数值优先级。默认： `0`.            |

***

### 相关页面

{% content-ref url="/pages/ff19704aac20f7d6e4bf5c3214636ccbe4248151" %}
[叙事触发器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/narrative-triggers.md)
{% endcontent-ref %}

{% content-ref url="/pages/453cd3ea71434b9c4a8a7da307779eeb39996f99" %}
[模板键](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/template-keys.md)
{% endcontent-ref %}

{% content-ref url="/pages/01a30a9c684189ac16deee8b6b420f60eb8252f8" %}
[获取叙事数据](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/fetching-narrative-data.md)
{% endcontent-ref %}

{% content-ref url="/pages/78fce7020677f54bda05ede0262a6996390ed909" %}
[叙事设计使用示例](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/narrative-design-usage-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/narrative-design/narrative-design-blueprint-reference.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.