> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/narrative-design/quick-start.md).
# 快速开始
## 使用叙事设计让你的第一个场景运行起来
本指南将带你走完实现一个可用的叙事设计配置的最快路径。到最后，你将拥有一个角色：当玩家穿过触发区域时会对章节变化做出反应——无需编写代码，完全通过检查器完成。
{% hint style="info" %}
**先决条件**
* A `ConvaiCharacter` 组件已在你的场景中，且角色 ID 有效。
* 你的角色至少定义了一个章节和一个触发器，位于 [Convai 仪表板](https://convai.com).
* 你的 Convai API 密钥配置在 **工具 → Convai → 配置**.
{% endhint %}
## 步骤
{% stepper %}
{% step %}
**添加 Narrative Design Manager**
选择包含你的 `ConvaiCharacter` 组件的 GameObject。在检视器中，点击 **添加组件** 并搜索 **叙事设计管理器** （路径： **Convai > Narrative Design Manager**).
管理器会自动检测 `ConvaiCharacter` 同一 GameObject 上的……。如果你的角色位于另一个 GameObject 中，请将其拖到 **角色** 字段中。
{% endstep %}
{% step %}
**从控制面板同步章节**
在管理器的检视器中，点击 **与后端同步**。SDK 会获取你的叙事章节并填充 **叙事章节** 列表中。
每个条目都会显示来自控制面板的章节名称。下一步你将把事件绑定到这些条目上。
{% hint style="warning" %}
如果列表仍为空，请检查你的角色 ID 是否已设置在 `ConvaiCharacter` 并且你的 API 密钥在 **项目设置 > Convai SDK**。该 **上一次获取错误** 字段会在出错时显示具体错误。
{% endhint %}
{% endstep %}
{% step %}
**绑定章节事件**
展开 **叙事章节** 列表中的第一个章节条目。你会看到两个 Unity 事件： **章节开始时** 是位于 **章节结束时**.
单击 **+** on **章节开始时**，将任意 GameObject 拖到对象字段中，并选择要调用的方法。最简单的选项是使用下面的 `NarrativeDesignDebugLogger` 辅助脚本——把它添加到任意 GameObject，然后将该 GameObject 拖到监听器字段，并选择 `NarrativeDesignDebugLogger.LogSectionStarted`.
NarrativeDesignDebugLogger.cs
```csharp
using UnityEngine;
public class NarrativeDesignDebugLogger : MonoBehaviour
{
[SerializeField] private string _label = "章节";
/// 连接到 UnitySectionEventConfig.OnSectionStart Unity 事件。
public void LogSectionStarted()
{
Debug.Log($"[NarrativeDesign] {_label} 已开始。", this);
}
/// 连接到 ConvaiNarrativeDesignManager.OnAnySectionChanged Unity 事件。
/// 接收新的章节 ID，类型为字符串。
public void LogSectionChanged(string sectionId)
{
Debug.Log($"[NarrativeDesign] 章节已更改 → {sectionId}", this);
}
}
```
{% endstep %}
{% step %}
**添加 Narrative Design Trigger**
在场景中创建一个新的空 GameObject（将其放在玩家会经过的位置）。点击 **添加组件** 并搜索 **Convai 叙事设计触发器** （路径： **Convai > Convai Narrative Design Trigger**).
将你的 `ConvaiCharacter` 到 **角色** 字段中，或者留空以让 **自动查找角色** 自动定位它。
{% endstep %}
{% step %}
**获取并选择一个触发器**
在 Trigger 组件的检视器中，点击 **获取** 以从仪表板加载命名触发器。将出现下拉菜单——选择应将图谱推进到第一个章节的触发器。
{% endstep %}
{% step %}
**添加一个碰撞体**
默认激活模式是 **碰撞**，它使用 Unity 的 `OnTriggerEnter`。在同一个触发器 GameObject 上，点击 **添加组件 > Box Collider**。在 Box Collider 的设置中，启用 **触发器**.
调整碰撞体大小，以覆盖你希望触发器触发的区域。在场景视图中，绿色线框盒显示检测区域。
{% endstep %}
{% step %}
**点击播放并走过去**
{% hint style="warning" %}
**玩家设置检查清单——在按下 Play 之前验证这三项：**
* **标签：** 玩家 GameObject 的标签必须设置为 `玩家` （Unity 的默认标签）。Trigger 组件通过标签匹配来识别玩家。
* **碰撞体：** 玩家必须拥有 Collider 组件。没有它， `OnTriggerEnter` 无论是否重叠，都不会触发。
* **刚体：** 触发区域或玩家必须拥有一个 `Rigidbody`。将其添加到 **玩家** ——如果你把它添加到触发区域，那么你需要对场景中的每个触发对象重复此操作。
缺少其中任何一项，都是触发器在 Play 模式下看起来毫无反应的最常见原因。
{% endhint %}
进入播放模式并将玩家移动穿过碰撞体区域。当触发器触发时：
1. SDK 会将触发器名称发送到 Convai 后端。
2. 后端会推进图谱并返回新的章节 ID。
3. `ConvaiNarrativeDesignManager` 接收章节变更并触发 **章节开始时** 对应章节条目上的
4. 你的 `Debug.Log` 调用会出现在控制台中，确认该章节现已激活。
{% hint style="success" %}
当玩家进入区域时，你应该会在控制台中看到章节 ID 日志。角色的下一次回复将反映新章节的目标。
{% endhint %}
{% endstep %}
{% endstepper %}
## 刚刚发生了什么
穿过碰撞体区域会在整个叙事设计栈中触发一连串事件：
1. 该 `ConvaiNarrativeDesignTrigger` 通过 `OnTriggerEnter` 检测到了玩家，并调用了 `InvokeTrigger()` 使用你所选择的触发器名称。
2. SDK 会先将触发器加入队列，直到角色的实时会话开启，然后发送一个 `触发消息` 通过 RTVI 连接发送到 Convai 后端。
3. 后端会沿着与该触发器名称匹配的边推进叙事图谱，并返回一个 `behavior-tree-response` 包含新章节 ID 的消息。
4. `ConvaiNarrativeDesignManager` 将传入的章节 ID 与其本地的 `UnitySectionEventConfig` 列表进行匹配，并触发 `OnSectionStart` 在匹配条目上的……
5. 你的 `Debug.Log` 监听器运行，确认控制台中的章节变更。
从这一刻起，角色的目标和对话行为将反映新章节的配置。
## 结论
现在你已经拥有一个完全通过检查器驱动的可用叙事设计配置。该配置对所有内容都使用默认设置。若要进一步深入：
* [设置叙事设计管理器](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/narrative-design/setting-up-the-narrative-design-manager.md) ——配置章节事件、了解同步状态面板，并探索全局事件。
* [设置 Narrative Design 触发器](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/narrative-design/setting-up-narrative-design-triggers.md) ——切换激活模式、配置队列行为，并绑定触发器事件。
* [模板键：动态叙事变量](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/narrative-design/template-keys-dynamic-narrative-variables.md) ——将玩家姓名或场景参数注入角色的目标中。
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/narrative-design/quick-start.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.