> 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 参考

Narrative design API 中 UConvaiChatbotComponent 上 Blueprint 函数、事件、属性和叙事结构体的参考。

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

### 异步获取节点

这些节点是独立的潜在 Blueprint 函数，不是……上的方法 `UConvaiChatbotComponent`。它们通过 HTTPS POST 向 Convai 发起请求，并通过……返回数据 **成功时** / **失败** 执行引脚。请参见 [获取叙事数据](/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 请求成功且各个 section 解析到输出数组中时触发。           |
| `失败`          | 输出（执行） | —                           | 当激活验证失败、响应指针无效，或者 HTTP 响应不在……之外时触发 `2xx` 范围内。 |
| `叙事章节`        | 输出     | `TArray<FNarrativeSection>` | 返回的章节。失败时为空。                                  |

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

| Message                                                | 当                  |
| ------------------------------------------------------ | ------------------ |
| `无法获取 world 的指针！`                                      | 激活时世界上下文无效。        |
| `无法获取 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`

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

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

***

### ……上的函数 `UConvaiChatbotComponent`

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

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

通过……发送一个命名触发器 `SendTriggerMessage` 作为 `trigger-message` 数据包，其中包含 `trigger_name`。断开连接时，会在……中排队 `PendingTriggers` 并在会话连接后重新播放。

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

返回：无。

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

| Message                                 | 当                 |
| --------------------------------------- | ----------------- |
| `调用叙事设计触发器：缺少 TriggerName`              | `TriggerName` 为空。 |
| `调用叙事设计触发器：已执行 \| 角色 ID：%s \| 会话 ID：%s` | 触发器已接受，将发送或排队。    |

***

#### 调用语音

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

通过……暂存一个动态上下文事件 `AddContextEvent` 使用 `EC_RunLLMOption::Always`。不会发送 `trigger-message` 数据包，并且不使用 `PendingTriggers`.

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

返回：无。

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

| Message                            | 当                    |
| ---------------------------------- | -------------------- |
| `调用语音：缺少 TriggerMessage`           | `TriggerMessage` 为空。 |
| `调用语音：已执行 \| 角色 ID：%s \| 会话 ID：%s` | 消息已接受，准备暂存。          |

***

### ……上的事件 `UConvaiChatbotComponent`

#### 收到叙事章节

C++ 名称： `收到叙事章节事件`\
类别： `Convai`\
访问： `BlueprintAssignable`

当 Convai 返回……时触发 `BTResponse` 数据包并透传该数据包的 `narrative_section_id`。插件会广播该事件，而不检查 ID 是否为新的或非空的。

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

***

### ……上的属性 `UConvaiChatbotComponent`

#### 叙事模板键

C++ 名称： `NarrativeTemplateKeys`\
类型： `TMap<FString, FString>`\
类别： `Convai|NarrativeDesign`\
访问： `Blueprint 可读写，任意处可编辑`\
Blueprint 设置器： `UpdateNarrativeTemplateKeys` (`仅供 Blueprint 内部使用`)

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

#### bAutoInitializeSession

C++ 名称： `bAutoInitializeSession`\
类型： `bool`\
类别： `Convai|Session`\
访问： `Blueprint 可读写，任意处可编辑`\
默认： `true`

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

***

### 叙事结构体

这些结构体是 `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>`            | 只读             | 图中父章节的 section 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` 当满足条件时要前进到的章节。 |
| `优先级`             | `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 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/narrative-design/narrative-design-blueprint-reference.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.