获取叙事数据

使用 Convai Fetch Narrative Sections 和 Convai Fetch Narrative Triggers，在运行时查询角色的叙事章节和触发器。

Convai Unreal Engine 插件在……下提供两个异步 Blueprint 节点 Convai|REST API 用于从 Convai 获取角色的叙事章节和触发器。使用这些节点可以在调用触发器之前验证触发器名称、填充动态 UI，或在加载界面期间预缓存叙事数据。

这些节点是可选的。正常的剧情推进路径是 调用叙事设计触发器 on UConvaiChatbotComponent，而不是先获取再调用。

先决条件

• Convai Unreal Engine 插件已安装，并且 API 密钥已配置。参见 配置您的 API 密钥.
• 一个有效的 CharacterId ，与……匹配的 CharacterID 在目标上 UConvaiChatbotComponent.
• 在获取节点执行时需要网络访问。获取节点会向 Convai 发起 HTTPS POST 请求。

获取叙事章节

Convai 获取叙事章节 是由……实现的异步潜伏式 Blueprint 节点 UFetchNarrativeSectionsProxy。它会 POST 到 character/narrative/list-sections 并返回在控制台中为该角色配置的章节。

引脚	方向	类型	说明
CharacterId	输入	FString	要查询的角色 ID。必须与……匹配 CharacterID 在目标上 UConvaiChatbotComponent.
成功时	输出（执行）	—	当 HTTP 请求成功且响应被解析为……时触发 FNarrativeSection 条目的数组。
失败时	输出（执行）	—	当激活验证失败、响应指针无效，或 HTTP 响应超出 2xx 范围时触发。
叙事章节	输出	TArray<FNarrativeSection>	成功时返回的章节。失败时为空。

要在 Blueprint 中添加该节点：

1. 右键单击事件图并搜索 获取叙事章节.
2. 选择 Convai 获取叙事章节 位于 Convai|REST API.
3. 将 CharacterId 输入设置为与……使用的值相同 UConvaiChatbotComponent 你正在使用的那个。
4. 将节点连接到两个 成功时 是位于 失败时 执行引脚。

获取叙事触发器

Convai 获取叙事触发器 是由……实现的异步潜伏式 Blueprint 节点 UFetchNarrativeTriggersProxy。它会 POST 到 character/narrative/list-triggers 并返回该角色叙事图中配置的触发器。

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

每个 FNarrativeTrigger 结果中的……会暴露 trigger_name, trigger_id, trigger_message，以及 destination_section 作为 BlueprintReadOnly 字段。 trigger_name 字段是你传递给……的内容 调用叙事设计触发器.

何时调用获取节点

在加载时调用获取节点，不要在游戏过程中重复调用：

• 开始游戏 — 在任何触发器被调用之前先获取，这样游戏开始时数据就已就绪。
• 加载界面 — 在玩家无法与角色交互时，与其他加载工作并行获取。
• 编辑器实用 Blueprint — 无需打开 Convai 控制台即可在 Unreal Editor 中检查角色的叙事图。

每次执行时，获取节点都会向 Convai 发起一次 HTTPS 请求。不要在 Tick 中或响应重复的游戏事件时调用它们。将结果缓存到 Blueprint 变量中并重复使用。

处理结果

在 成功时 的引脚 Convai 获取叙事触发器，遍历 叙事触发器 数组并提取每个 trigger_name 到一个 TSet<FString> 或 Map 变量中。在调用 调用叙事设计触发器之前，检查目标名称是否在集合中。

在 成功时 的引脚 Convai 获取叙事章节，遍历 叙事章节 并使用每个 section_id 是位于 section_name 来填充下拉菜单或调试覆盖层。

有关完整的触发器验证步骤，请参阅 叙事设计使用示例.

验证获取结果

在 Play In Editor 中运行获取节点后：

1. 确认 成功时 执行引脚已触发（而不是 失败时).
2. 检查 叙事章节 或 叙事触发器 — 数组应包含你查询的角色对应的条目。
3. 如果 失败时 触发时，检查 输出日志 用于 ConvaiNarrativeHTTP 消息。请参阅 排查叙事设计问题.

如果 HTTP 请求成功，但响应数组无法解析为叙事结构体，获取代理可能会在不触发 成功时 或 失败时。如果潜伏节点似乎卡住了，请检查 输出日志 用于 ConvaiNarrativeHTTP 并在确认该角色在控制台中已有叙事数据后重试。

下一步

叙事触发器叙事设计 Blueprint 参考排查叙事设计问题