叙事触发器

在 Convai chatbot 组件上调用命名叙事触发器或动态上下文消息，以推进故事图并处理章节变更事件。

叙事触发器会将角色的故事图从一个章节推进到下一个章节。 UConvaiChatbotComponent 提供两个用于触发触发器的 Blueprint 函数，以及一个用于响应章节变化的事件。如果你之前还没有调用过触发器，请先完成 叙事设计快速开始 第一步。

选择合适的函数

目标	函数	它发送什么
使用仪表板触发器名称推进图表	调用叙事设计触发器	触发消息 其带有 trigger_name
将运行时消息作为对话上下文暂存	调用语音	通过动态上下文事件 AddContextEvent

使用 调用叙事设计触发器 当过渡目标在设计时已知，并且触发器名称是仪表板中的固定字符串时使用。使用 调用语音 当消息在运行时组装、当角色应说出脚本台词，或者当你希望 Convai 将游戏状态文本作为对话上下文处理，而不是匹配仪表板触发器名称时使用。

收到叙事章节时 仅在 Convai 通过一个 BTResponse 数据包。调用任一函数时都不会触发。

调用命名触发器

调用叙事设计触发器 (InvokeNarrativeDesignTrigger) 发送一个 TriggerName 字符串通过 SendTriggerMessage发送给 Convai。Convai 会将该名称与仪表板中为当前章节配置的外发触发器进行匹配。

输入	类型	说明
TriggerName	FString	触发器名称。必须与仪表板配置完全一致（区分大小写）。
InGenerateActions	bool	存在于 Blueprint 签名中。当前插件源代码中未应用。
InReplicateOnNetwork	bool	存在于 Blueprint 签名中。当前插件源代码中未应用。

如果 TriggerName 为空时，插件会记录 调用叙事设计触发器：缺少 TriggerName 并返回，不发送触发器。

从仪表板逐字符复制触发器名称。Blueprint 字符串与仪表板之间的不匹配 trigger_name 不会产生章节更改。

调用动态上下文消息

调用语音 (ExecuteNarrativeTrigger) 通过动态上下文事件暂存 AddContextEvent 其带有 EC_RunLLMOption::Always。它不会发送一个 触发消息 数据包，也不会在 PendingTriggers.

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

使用普通的 TriggerMessage 当角色应将消息作为上下文处理时，例如 玩家以 82% 的准确率完成了疏散演练。将消息包裹在 <speak> 标签中，当角色应直接说出文本时，例如 <speak>注意：疏散路线现已开放。</speak>.

如果 Convai 判定需要进行章节更改， 收到叙事章节时 仍会通过相同的 BTResponse 路径触发。

如果 TriggerMessage 为空时，插件会记录 调用语音：缺少 TriggerMessage 并返回，不暂存事件。

处理章节更改事件

Bind 收到叙事章节时 (OnNarrativeSectionReceivedEvent) 在聊天机器人组件上，以便在 Convai 进入新章节时作出响应。

输出引脚	类型	说明
ChatbotComponent	UConvaiChatbotComponent*	接收到章节更新的组件。
NarrativeSectionID	FString	该 section_id 新活动章节的。

在 Blueprint 中绑定：将 UConvaiChatbotComponent 引用拖到事件图中，然后选择 分配“收到叙事章节时” 从上下文菜单中。

当某个特定章节应运行自定义 Blueprint 逻辑时，复制该章节的 section_id 来自 叙事设计 在 Convai 仪表板中。使用 ID 值，而不是图中显示的章节名称。在绑定的事件中，比较传入的 NarrativeSectionID 与复制的值。如果字符串匹配，则运行该章节的 Blueprint 逻辑，例如打开门、启用小部件或启动评估计时器。

待处理的命名触发器

当 调用叙事设计触发器 被调用且会话未连接时，插件会将该调用存储在 PendingTriggers。待处理触发器会在会话连接且动态上下文刷新完成后按顺序重新执行。

调用 重置动态上下文 清除 PendingTriggers。如果组件在会话重新连接之前被销毁，排队的触发器也会被丢弃。 调用语音 不使用待处理触发器队列。

会话就绪

bAutoInitializeSession on UConvaiChatbotComponent 默认为 true。启用后，组件会调用 StartSession on 开始游戏。在会话连接之前调用的命名触发器会排队到 PendingTriggers 中，并在连接打开后重新执行。

如果 bAutoInitializeSession 为 false，则调用 StartSession 请在预期触发器立即发送之前显式执行。你也可以绑定 角色数据加载完成时 (OnCharacterDataLoadEvent_V2) 并在该事件中调用触发器，当你需要确认角色数据已加载时。

下一步

模板键叙事设计 Blueprint 参考叙事设计使用示例