叙事设计脚本化

叙事设计完整的 C# 接口——IConvaiNarrativeDesign 事件、InvokeTrigger、带 speak 标签的 InvokeSpeech、异步部分获取以及运行时触发器重新配置。

以程序化方式控制叙事设计

Inspector 工作流覆盖了大多数用例。本页记录了完整的 C# 接口，适用于你需要程序化控制的场景——动态角色切换、运行时异步数据获取、运行时生成的叙事流程，或与自有游戏系统的深度集成。

此处描述的所有功能都可通过 IConvaiNarrativeDesign访问，它暴露在每个 ConvaiCharacter 中，可通过 NarrativeDesign 属性访问。 ConvaiNarrativeDesignManager 是位于 ConvaiNarrativeDesignTrigger 这两者内部都委托给此接口，因此你在 Inspector 中配置的一切也都可以通过代码访问。

访问角色 API

每个 ConvaiCharacter 暴露了一个 NarrativeDesign 属性，它返回一个 IConvaiNarrativeDesign 实现：

ConvaiCharacter character = GetComponent<ConvaiCharacter>();
IConvaiNarrativeDesign narrative = character.NarrativeDesign;

属性

属性	类型	说明
TemplateKeys	IReadOnlyDictionary<string, string>	当前为该角色跟踪的所有模板键的快照。
CurrentSectionId	string	最近一次从后端接收到的章节 ID。如果尚未接收任何章节，则为空字符串。
CurrentSectionData	NarrativeSectionData	完整章节负载。包含 SectionId, BehaviorTreeCode，以及 BehaviorTreeConstants. null 直到收到第一次章节变更。

监听章节变化

请在 OnEnable 中订阅这些事件，并在 OnDisable 中取消订阅，以避免在组件被禁用或销毁后留下过期监听器。

private void OnEnable()
{
    character.NarrativeDesign.OnSectionChanged     += HandleSectionChanged;
    character.NarrativeDesign.OnSectionDataReceived += HandleSectionData;
}

private void OnDisable()
{
    character.NarrativeDesign.OnSectionChanged     -= HandleSectionChanged;
    character.NarrativeDesign.OnSectionDataReceived -= HandleSectionData;
}

private void HandleSectionChanged(string previousId, string newId)
{
    Debug.Log($"章节：{previousId} → {newId}");
}

private void HandleSectionData(NarrativeSectionData data)
{
    Debug.Log($"章节 ID：{data.SectionId}");
    // 此处可用 data.BehaviorTreeCode 和 data.BehaviorTreeConstants
}

事件

事件	签名	说明
OnSectionChanged	Action<string, string>	在每次章节切换时触发。参数： previousId, newId.
OnSectionDataReceived	Action<NarrativeSectionData>	在每次章节切换时触发，并携带完整负载。
OnTriggerInvoked	Action<ConvaiNarrativeTriggerInvocation>	在触发器或语音请求被本地接受后触发（在后端确认之前）。

OnSectionChanged 是位于 OnSectionDataReceived 通过 SDK 内部的 EventHub传递。如果你的订阅代码会调用 Unity API（例如 GameObject.SetActive），请确保 ConvaiNarrativeDesignManager 在场景中——它会自动使用主线程传递。对 IConvaiNarrativeDesign 的原始订阅可能会根据配置在后台线程中到达事件。

从代码中调用触发器

// 命名触发器——沿特定边推进图谱
bool accepted = character.NarrativeDesign.InvokeTrigger("CheckpointReached");

// 带可选消息负载的命名触发器
character.NarrativeDesign.InvokeTrigger("ItemInspected", "灭火器缺少插销。");

InvokeTrigger 返回 false 如果 triggerName 是位于 triggerMessage 都为空，或者触发器在内部被拒绝，则返回。否则它返回 true ；如果会话尚未打开，则将触发器排队。

控制角色说什么

InvokeSpeech 让你可以直接控制角色的下一句发言，而不会推进叙事图谱。根据你是否将消息包裹在 <speak> 标签中，它有两种不同模式。

上下文注入（纯文本）

传入纯字符串，可让角色 知晓 一条信息。角色会吸收上下文，并用自己的话作出回应——具体措辞由 AI 决定。

// 角色会知晓这一事实，并自然地回应
character.NarrativeDesign.InvokeSpeech("受训者刚刚完成了疏散演练。");

当你希望角色以自然、对话式的方式对游戏事件作出反应，而不是照本宣科时，请使用此方式。

逐字语音（speak 标签）

将消息包裹在 <speak> 标签中，可让角色逐字逐句说出该文本。

// 角色会逐字说出这句话
character.NarrativeDesign.InvokeSpeech("<speak>注意：二楼的消防出口现已解锁。</speak>");

适用于公告、脚本台词、安全警报，或任何需要精确措辞的时刻。

比较

模式	角色的行为
InvokeSpeech("text")	知晓上下文，并用自己的话回应
InvokeSpeech("<speak>text</speak>")	逐字说出该精确文本

InvokeSpeech 无论你使用哪种模式，它都不会推进叙事图谱。若要在发送消息的同时推进图谱，请使用 InvokeTrigger 配合命名触发器。

监听触发器调用

character.NarrativeDesign.OnTriggerInvoked += invocation =>
{
    Debug.Log($"触发器：{invocation.TriggerName}，已排队：{invocation.Queued}");
};

ConvaiNarrativeTriggerInvocation 字段：

字段	类型	说明
TriggerName	string	发送的触发器名称（语音时为空）。
TriggerMessage	string	可选的消息负载。
Queued	bool	true 如果因为会话尚未打开而延迟了触发器。

通过代码使用模板键

// 设置单个键
character.NarrativeDesign.SetTemplateKey("PlayerName", "Alex");

// 设置多个键
character.NarrativeDesign.SetTemplateKeys(new Dictionary<string, string>
{
    { "PlayerName",  "Alex" },
    { "ScoreLevel",  "Intermediate" }
});

如果会话已打开，这两种方法会立即发送；如果没有，则会排队到下一次连接。

角色级 API 和 ConvaiNarrativeDesignManager的各方法在内部汇聚到同一传输层。当你希望这些键在 Inspector 中可见且可编辑时，请使用 Manager 的方法；当你只需要纯代码驱动、无需 Inspector 可见性时，请使用角色 API。

以编程方式获取章节和触发器

通过角色 API

NarrativeFetchResult<List<NarrativeSectionInfo>> result =
    await character.NarrativeDesign.FetchSectionsAsync();

if (result.Success)
{
    foreach (NarrativeSectionInfo section in result.Data)
        Debug.Log($"{section.SectionId}：{section.SectionName}");
}
else
{
    Debug.LogError(result.Error);
}

NarrativeFetchResult<List<NarrativeTriggerInfo>> result =
    await character.NarrativeDesign.FetchTriggersAsync();

foreach (NarrativeTriggerInfo trigger in result.Data)
    Debug.Log($"{trigger.TriggerName} → {trigger.DestinationSection}");

NarrativeSectionInfo 字段： SectionId, SectionName.

NarrativeTriggerInfo 字段： TriggerId, TriggerName, TriggerMessage, DestinationSection.

通过静态获取器

NarrativeDesignFetcher 提供相同的数据，而无需角色组件引用——这在编辑器工具或加载界面中很有用：

// 获取章节
FetchResult<List<SectionData>> sections =
    await NarrativeDesignFetcher.FetchSectionsAsync(characterId);

// 获取触发器
FetchResult<List<TriggerData>> triggers =
    await NarrativeDesignFetcher.FetchTriggersAsync(characterId);

// 并行获取两者
var (sectionsResult, triggersResult) =
    await NarrativeDesignFetcher.FetchAllAsync(characterId);

FetchResult<T> 字段：

字段	类型	说明
Success	bool	true 如果请求成功。
Data	T	获取到的数据。 默认 如果 Success 为 false.
错误	string	错误消息。 null 如果 Success 为 true.

重置状态

// 仅重置控制器状态（清除 CurrentSectionID 和 CurrentSectionData）
// 不会触及章节配置列表或 Unity Event 绑定
narrativeManager.ResetController();

// 永久清除所有章节配置（移除所有 UnitySectionEventConfig 条目）
// 仅在切换到完全不同的角色时使用
narrativeManager.ClearAllSectionConfigs();

ClearAllSectionConfigs() 移除所有 UnitySectionEventConfig 条目以及所有 Unity Event 绑定。此操作在运行时无法撤销。仅当你已确认要切换到其他角色，并且不再需要现有章节事件绑定时，才调用它。

从代码重新配置 ConvaiNarrativeDesignTrigger

所有可在 Inspector 中配置的设置都有对应的 setter 方法：

ConvaiNarrativeDesignTrigger trigger = GetComponent<ConvaiNarrativeDesignTrigger>();

// 覆盖触发器选择
trigger.SetTrigger("trigger-uuid", "CheckpointA", "Player reached checkpoint A");

// 在运行时更改激活模式
trigger.SetActivationMode(TriggerActivationMode.Proximity);
trigger.SetProximityRadius(5f);

// 提供一个已知的玩家 Transform（在自动查找不足时很有用）
trigger.SetPlayerTransform(playerController.transform);

// 切换目标角色
trigger.SetCharacter(otherCharacter.GetComponent<IConvaiCharacterAgent>());

// 在关键触发前进行验证
if (!trigger.ValidateConfiguration())
{
    foreach (string warning in trigger.ValidationWarnings)
        Debug.LogWarning(warning);
}

架构概览

结论

IConvaiNarrativeDesign 在代码中暴露完整的 Narrative Design 功能——触发器调用、语音注入、模板键控制、异步数据获取以及实时章节变化事件——因此你可以将其集成到任何架构中，而不必受限于 Inspector 组件。有关将这些 API 组合到真实场景中的完整示例，请参见 使用示例。如需诊断问题，请参见故障排除与诊断。