叙事设计 Blueprint 参考

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

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

异步获取节点

这些节点是独立的潜在 Blueprint 函数，不是 UConvaiChatbotComponent上的方法。它们向 Convai 发起 HTTPS POST 请求，并通过 成功时 / 失败时 执行引脚。参见 获取叙事数据 以获取使用指南。

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.

---

相关页面

叙事触发器模板键获取叙事数据叙事设计使用示例