叙事设计

面向 Convai AI 角色的结构化叙事图——章节、触发器和模板键如何在运行时汇聚，以创建可感知状态的体验，并根据每个玩家动作进行适应。

什么是叙事设计？

叙事设计为你的 Convai AI 角色提供一个可遵循的结构化故事。你在 Convai 仪表板中编写一个由 章节 （故事节拍）和 触发器 （它们之间的边）组成的图。在运行时，SDK 会监听服务器的章节变更信号，并触发你配置的 Unity 事件——无需轮询，也无需手动状态机。

角色的行为、知识和对话目标会自动适应当前章节，因此同一个角色可以在开场章节中扮演一名中立的接待员，而在评估章节中扮演一名严厉的考官，全部都在同一次会话中完成。

运行时的工作方式

当玩家激活某个触发器时，SDK 会向 Convai 后端发送一个命名信号。后端推进故事图，并返回一个 behavior-tree-response 消息，其中携带新的章节 ID 和任何相关的行为树数据。SDK 会将此消息转换为一个 NarrativeSectionChanged 领域事件，并将其传递给 ConvaiNarrativeDesignManager，后者会触发你在 Inspector 中连接的按章节 Unity 事件。

三个构建模块

组件	所在位置	它的作用
ConvaiNarrativeDesignManager	在角色 GameObject 上	监听章节变更，触发按章节的 OnSectionStart / OnSectionEnd Unity 事件，管理模板键
ConvaiNarrativeDesignTrigger	在任意世界 GameObject 上	在激活时向角色发送一个命名触发器（碰撞、接近、计时器或手动）
IConvaiNarrativeDesign	通过以下方式访问 convaiCharacter.NarrativeDesign	面向角色作用域的 C# API，用于通过代码触发触发器、控制模板键以及异步获取数据

你可以任意组合这三者。大多数项目都需要全部三者；简单的线性叙事可能只需要 Manager 和一两个 Trigger。

关键概念

术语	定义
分区	在 Convai 仪表板中定义的一个命名故事节拍。角色的目标和行为会根据当前章节自动调整。
触发器	故事图中的一个命名边。发送触发器会将图从一个章节推进到下一个章节。
模板键	一个运行时键值对（例如 PlayerName = "Alex"），用于填充仪表板中叙事目标里的占位符。
孤立章节	一个在本地同步后又从仪表板中删除的章节。它的 Unity 事件会被保留，但在该章节恢复并重新同步之前，永远不会触发。
行为树响应	携带新 SectionId 以及可选的 BehaviorTreeCode 和 BehaviorTreeConstants 供高级集成使用。

先决条件

在项目中使用叙事设计之前，请确保：

• 已导入 Convai Unity SDK，并且场景中存在一个 ConvaiCharacter 组件。
• 你已经在 Convai 仪表板 中创建了一个叙事图，至少包含一个章节和一个触发器。
• 你的角色 ID 已设置在 ConvaiCharacter 组件上——没有它，SDK 无法获取或响应章节。

放在哪里

弄清楚哪个组件该放在哪个 GameObject 上，可以避免最常见的设置错误。

组件	放置位置	每个场景中的典型数量
ConvaiNarrativeDesignManager	在 角色的 GameObject 上，旁边还有 ConvaiCharacter	每个角色一个
ConvaiNarrativeDesignTrigger	开启 任何世界 GameObject ——一扇门、一个展品、一个 UI 事件目标	每个图转换点一个
IConvaiNarrativeDesign	不放置——通过 convaiCharacter.NarrativeDesign 在代码中	不适用

本节内容

快速入门

只需几分钟，无需代码，即可让角色对章节变化做出响应。

设置 Narrative Design Manager

添加、同步并配置 Manager 组件——它是章节转换的监听站。

设置 Narrative Design 触发器

放置带有碰撞、接近、计时器或手动激活的世界触发器。

模板键：动态叙事变量

从 Inspector 或代码中将运行时值注入角色的叙事目标。

编写 Narrative Design 脚本

IConvaiNarrativeDesign、NarrativeDesignFetcher 以及程序化控制的完整 C# API 参考。

使用示例

四个随复杂度递增的示例——从简单的欢迎流程到自适应的多章节场景。

故障排查与诊断

诊断每一种 TriggerStatus 状态、常见配置错误以及获取失败。

结论

叙事设计为你的 Convai 角色提供一个结构化、可响应的故事，无需任何自定义状态机代码。三个组件——Manager、Trigger 和 IConvaiNarrativeDesign 接口——涵盖了从单按钮信息亭到完全自适应的多步骤场景的一切需求。先从快速开始入手，在几分钟内完成可用配置，然后随着需求增长再深入探索更详细的配置指南。