使用示例

四个复杂度递增的完整示例——从单触发欢迎序列到自适应多章节场景——展示如何在实践中组合叙事设计组件。

构建完整的 Narrative Design 配置

以下示例展示如何组合 ConvaiNarrativeDesignManager, ConvaiNarrativeDesignTrigger，以及 IConvaiNarrativeDesign 组成完整、可运行的配置。它们按从简单到高级排序，并覆盖不同领域，以展示 Narrative Design 所支持的广度——从单按钮欢迎终端到完全自适应的多步骤场景。

每个示例都是独立的。请从最符合你当前复杂度的示例开始。如果某一步不熟悉，相关详情页已在文中链接。

---

示例 1 — 简单：脚本化欢迎流程

复杂度： 初级 | 激活模式： 手动 | 使用的功能： 管理器、触发器（手动）、一个模板键

场景： 一位访客来到接待台。界面中的“开始”按钮通过发送一个单一触发器启动体验，使角色从待机状态切换到活动欢迎环节。

设置

1

准备场景

Add ConvaiNarrativeDesignManager 将其添加到角色 GameObject，并从仪表板同步各个区段。你至少需要两个区段：一个待机区段（角色在此等待）和一个欢迎区段（角色在此开始体验）。

2

在会话开始前设置访客姓名

在开始会话前，发送一个模板键，这样角色就可以按姓名称呼访客：

public class ReceptionController : MonoBehaviour
{
    [SerializeField] private ConvaiNarrativeDesignManager _narrativeManager;
    [SerializeField] private string _visitorName;

    private void Start()
    {
        _narrativeManager.UpdateAndSendTemplateKey("VisitorName", _visitorName);
    }
}

3

添加一个手动触发器

Add ConvaiNarrativeDesignTrigger 到任意 GameObject（它不会出现在世界中——它由 UI 驱动）。设置 激活模式 到 手动 并从仪表板中获取/选择欢迎触发器。

4

连接 UI 按钮

在 Button 组件的 On Click () 事件中，指定 ConvaiNarrativeDesignTrigger 并选择 ConvaiNarrativeDesignTrigger.InvokeTrigger.

5

连接区段事件

在 Manager 的 Narrative Sections 列表中，找到欢迎区段条目并添加一个 OnSectionStart 监听器。将其指向欢迎开始时场景中应发生变化的内容——例如启用姓名牌 UI 或开始环境动画。

运行时会发生什么： 玩家点击开始 → InvokeTrigger() 将触发器发送到后端 → 图表切换到欢迎区段 → OnSectionStart 在进入欢迎区段时触发 → 角色开始欢迎。

---

示例 2 — 中级：分支对话

复杂度： 中级 | 激活模式： 手动（代码驱动）| 使用的功能： 管理器、 IConvaiNarrativeDesign, InvokeSpeech，多个模板键

场景： 一个导览助手可以引导用户浏览三个独立主题领域（例如设施、系统访问、政策）。主题选择由 UI 按钮驱动，用户可以在主题之间自由切换。每个主题之后都支持开放式追问。

设置

在 Manager 中同步所有主题区段。不 ConvaiNarrativeDesignTrigger 需要组件——触发器直接通过 IConvaiNarrativeDesign.

public class OrientationController : MonoBehaviour
{
    [SerializeField] private ConvaiCharacter _character;
    [SerializeField] private TextMeshProUGUI _activeTopicLabel;

    private void OnEnable()
    {
        _character.NarrativeDesign.OnSectionChanged += OnSectionChanged;
    }

    private void OnDisable()
    {
        _character.NarrativeDesign.OnSectionChanged -= OnSectionChanged;
    }

    // 由 UI 按钮调用
    public void SelectTopic(string triggerName)
    {
        _character.NarrativeDesign.InvokeTrigger(triggerName);
    }

    // 由自由文本输入框的提交事件调用——纯文本上下文注入
    // 角色会用自己的话自然回应
    public void AskFollowUp(string userQuestion)
    {
        _character.NarrativeDesign.InvokeSpeech(userQuestion);
    }

    // 当需要脚本化公告时调用——角色逐字说出这段内容
    public void AnnounceToUser(string announcement)
    {
        _character.NarrativeDesign.InvokeSpeech("<speak>{announcement}</speak>");
    }

    private void OnSectionChanged(string previous, string next)
    {
        // 更新面包屑 UI——从 Manager 中查找人类可读名称
        if (_narrativeManager.FindSectionConfig(next) is { } cfg)
            _activeTopicLabel.text = cfg.SectionName;
    }
}

在 Inspector 中为按钮指定触发器名称： "TopicFacilities", "TopicSystemsAccess", "TopicPolicies".

设置 TriggerOnce = false 在所有触发器上设置为 false，这样用户就可以重新访问任意主题。发送模板键（UserName, Department）在会话开始前通过表单发送，使用 UpdateTemplateKeys.

InvokeSpeech 有两种模式： 纯文本会让角色用自己的话自然回应（适合自由文本追问）；将消息包裹在 <speak> 标签中会让角色逐字说出该文本（适合脚本化公告或精确提示）。这两种模式都不会推进图表。完整参考请参见“控制角色说什么”。

---

示例 3 — 中级：邻近触发的展品导览

复杂度： 中级 | 激活模式： 邻近 | 使用的功能： 管理器、触发器（邻近）、区域事件、批量模板键

场景： 一个产品展示厅有五个展示站。随着访客走向每个站点，一位主讲角色会开始讲解该产品。每个站点都是独立的，可按任意顺序参观。

设置

创建一个 ConvaiNarrativeDesignTrigger 每个站点一个。对于每个站点：

• 激活模式： 接近
• 邻近半径： 根据站点大小调整（在 Scene 视图中显示为绿色球体 gizmo）
• 仅触发一次： true
• 场景加载时重置： true （这样每次访问时导览都会重置）

通过模板键连接每个站点的特定上下文。从一个 ScriptableObject 在 Start():

[CreateAssetMenu(menuName = "展厅/站点数据")]
public class StationData : ScriptableObject
{
    public string ProductName;
    public string LaunchYear;
    public string KeyFeature;
}

public class StationController : MonoBehaviour
{
    [SerializeField] private ConvaiNarrativeDesignManager _narrativeManager;
    [SerializeField] private StationData _data;

    private void Start()
    {
        _narrativeManager.UpdateTemplateKeys(new Dictionary<string, string>
        {
            { "ProductName", _data.ProductName },
            { "LaunchYear",  _data.LaunchYear  },
            { "KeyFeature",  _data.KeyFeature  }
        });
    }
}

使用 OnPlayerEnterZone 用于高亮产品模型（例如启用轮廓着色器）。使用 OnPlayerExitZone 用于移除高亮。

如果站点的邻近半径重叠，两个触发器可能会在同一帧触发，在后端响应第一个之前就发送两次图表切换。请将站点间距拉开，确保邻近区域不相交，或者使用碰撞模式并让触发碰撞体物理分离。

---

示例 4 — 高级：带动态反馈的自适应场景

复杂度： 高级 | 激活模式： 代码驱动 | 使用的功能： 管理器、 IConvaiNarrativeDesign, OnSectionDataReceived, BehaviorTreeConstants，动态模板键、重测流程

场景： 一位技术技能评估员运行一个多步骤场景。每完成一步，都会对学习者的表现进行评分。角色提供的引导程度和场景的难度会根据当前累计分动态调整。该场景可以重新进行，且会重置所有状态。

会话生命周期

实现

public class ScenarioController : MonoBehaviour
{
    [SerializeField] private ConvaiNarrativeDesignManager _narrativeManager;
    [SerializeField] private ConvaiCharacter _character;

    private int _totalScore;
    private int _stepCount;

    private void OnEnable()
    {
        _character.NarrativeDesign.OnSectionDataReceived += OnSectionDataReceived;
    }

    private void OnDisable()
    {
        _character.NarrativeDesign.OnSectionDataReceived -= OnSectionDataReceived;
    }

    public void StartScenario(string learnerName)
    {
        _totalScore = 0;
        _stepCount  = 0;
        _narrativeManager.UpdateTemplateKeys(new Dictionary<string, string>
        {
            { "LearnerName",    learnerName   },
            { "DifficultyLevel", "Foundation" }
        });
        _narrativeManager.SendTemplateKeysUpdate();
    }

    public void OnStepCompleted(int stepScore)
    {
        _totalScore += stepScore;
        _stepCount++;

        string level = (_totalScore / _stepCount) > 80 ? "Advanced" : "Foundation";
        _narrativeManager.UpdateAndSendTemplateKey("DifficultyLevel", level);
        _character.NarrativeDesign.InvokeTrigger("StepCompleted");
    }

    private void OnSectionDataReceived(NarrativeSectionData data)
    {
        if (string.IsNullOrEmpty(data.BehaviorTreeConstants)) return;

        // BehaviorTreeConstants 是在 Convai 仪表板中编写的 JSON 字符串
        // 包含该区段的场景特定参数
        var constants = JsonUtility.FromJson<ScenarioConstants>(data.BehaviorTreeConstants);
        ApplyScenarioParameters(constants);
    }

    public async void RetakeScenario()
    {
        _narrativeManager.ResetController();
        await _narrativeManager.FetchAndSyncFromBackendAsync();
        StartScenario("LearnerName");
    }

    private void ApplyScenarioParameters(ScenarioConstants constants)
    {
        // 将仪表板中编写的常量值应用到场景中
    }

    [Serializable]
    private class ScenarioConstants
    {
        public float TimeLimit;
        public int   RequiredScore;
        public bool  ShowHints;
    }
}

什么 BehaviorTreeConstants 提供： 一个你在 Convai 仪表板中为每个区段编写的 JSON 字符串。它携带你希望从图表注入到 Unity 的任何数据——时间限制、评分阈值、提示标志或其他场景参数。SDK 会在每个 NarrativeSectionData 载荷中传递。

BehaviorTreeCode 和 BehaviorTreeConstants 从 SDK 侧看是只读的。它们携带在 Convai 仪表板中编写的数据，不能在 Unity 运行时修改。

---

结论

这四个示例涵盖了 Narrative Design 用例的完整范围——从完全在 Inspector 中连接的单触发欢迎流程，到一个角色行为会根据表现数据动态变化的完全自适应场景。每种模式都建立在相同的三个组件之上：Manager、Trigger，以及 IConvaiNarrativeDesign API。若要帮助诊断这些配置中的问题，请参见“故障排除与诊断”。