> 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).
# 快速开始
通过完整的 Inspector 优先设置演练——Manager、Trigger 和碰撞器区域——追踪从玩家交互到 Play 模式中确认章节变更的完整信号路径。
## 使用叙事设计让你的第一个场景运行起来
本指南将带你走完搭建一个可用的叙事设计配置的最快路径。到最后，你将拥有一个角色：当玩家穿过触发区域时，它会对章节变更做出反应——无需代码，完全通过 Inspector 完成。
{% hint style="info" %}
**前置条件**
* 一个 `ConvaiCharacter` 组件位于你的场景中，并且具有有效的角色 ID。
* 你的角色至少定义了一个章节和一个触发器，位于 [Convai 仪表板](https://convai.com).
* 你的 Convai API 密钥已在 **工具 → Convai → 配置**.
{% endhint %}
## 步骤
{% stepper %}
{% step %}
**添加叙事设计管理器**
选择带有你的 `ConvaiCharacter` 组件的 GameObject。在 Inspector 中，点击 **添加组件** 中搜索 **叙事设计管理器** （路径： **Convai > Narrative Design Manager**).
管理器会自动检测 `ConvaiCharacter` 同一个 GameObject 上的组件。如果你的角色位于不同的 GameObject 上，请将其拖入 **Character** 字段。
{% endstep %}
{% step %}
**从仪表板同步章节**
在管理器的 Inspector 中，点击 **与后端同步**。SDK 会获取你的叙事章节并填充 **Narrative Sections** 列表。
每个条目都会显示来自仪表板的章节名称。下一步，你将为这些条目连接事件。
{% hint style="warning" %}
如果列表仍然为空，请检查你的角色 ID 是否设置在 `ConvaiCharacter` 并且你的 API 密钥在 **项目设置 > Convai SDK**。 **上次获取错误** 字段会在出错时显示具体错误。
{% endhint %}
{% endstep %}
{% step %}
**连接章节事件**
展开以下内容中的第一个章节条目： **Narrative Sections** 列表。你会看到两个 Unity 事件： **章节开始时** 和 **章节结束时**.
点击 **+** 在 **章节开始时**，将任何 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 %}
**添加叙事设计触发器**
在你的场景中创建一个新的空 GameObject（将其放在玩家会经过的位置）。点击 **添加组件** 中搜索 **Convai 叙事设计触发器** （路径： **Convai > Convai 叙事设计触发器**).
将你的 `ConvaiCharacter` 到 **Character** 字段，或者将其留空以便让 **自动查找角色** 自动定位它。
{% endstep %}
{% step %}
**获取并选择触发器**
在触发器组件的 Inspector 中，点击 **获取** 以从仪表板加载命名触发器。会出现一个下拉菜单——选择应将图推进到第一个章节的触发器。
{% endstep %}
{% step %}
**添加碰撞器**
默认激活模式是 **碰撞**，它使用 Unity 的 `OnTriggerEnter`。在同一个触发器 GameObject 上，点击 **添加组件 > Box Collider**。在 Box Collider 的设置中，启用 **Is Trigger**.
调整碰撞器大小，使其覆盖你希望触发器触发的区域。在 Scene 视图中，绿色线框盒表示检测区域。
{% endstep %}
{% step %}
**按下 Play 并穿过**
{% hint style="warning" %}
**玩家设置检查清单——在按下 Play 之前请确认这三项：**
* **标签：** 玩家 GameObject 的标签必须设置为 `Player` （Unity 的默认标签）。Trigger 组件通过标签匹配来识别玩家。
* **碰撞器：** 玩家必须具有 Collider 组件。没有它， `OnTriggerEnter` 无论是否重叠，都不会触发。
* **刚体：** 触发区域或玩家必须拥有一个 `Rigidbody`。将其添加到 **玩家** ——如果你改为将其添加到触发区域，那么你需要对场景中的每个触发器对象都重复这一操作。
缺少其中任何一项，都是触发器在 Play 模式下看起来毫无反应的最常见原因。
{% endhint %}
进入 Play 模式，让玩家穿过碰撞器区域。当触发器触发时：
1. SDK 会将触发器名称发送到 Convai 后端。
2. 后端会推进图，并返回新的章节 ID。
3. `ConvaiNarrativeDesignManager` 接收章节更改并触发 **章节开始时** 匹配章节条目上的
4. 你的 `Debug.Log` 调用会出现在 Console 中，确认该章节现在已激活。
{% hint style="success" %}
当玩家进入区域时，你应该会在 Console 中看到记录的章节 ID。角色的下一次回复将体现新章节的目标。
{% endhint %}
{% endstep %}
{% endstepper %}
## 刚刚发生了什么
穿过碰撞器区域会在整个叙事设计栈中触发一连串事件：
1. 该 `ConvaiNarrativeDesignTrigger` 通过 `OnTriggerEnter` 并调用了 `InvokeTrigger()` 以及你选择的触发器名称。
2. SDK 会将触发器排队，直到角色的实时会话打开，然后发送一个 `trigger-message` 通过 RTVI 连接发送到 Convai 后端。
3. 后端会沿着与该触发器名称匹配的边推进叙事图，并返回一个 `behavior-tree-response` 包含新章节 ID 的消息。
4. `ConvaiNarrativeDesignManager` 将传入的章节 ID 与其本地的 `UnitySectionEventConfig` 列表进行匹配，并触发了 `OnSectionStart` 匹配条目上的
5. 你的 `Debug.Log` 监听器已运行，在 Console 中确认了章节更改。
从此刻起，角色的目标和对话行为将反映新章节的配置。
## 结论
你现在已经拥有一个完全通过 Inspector 驱动的可用叙事设计配置。此配置对所有内容都使用默认设置。若要进一步深入：
* [设置叙事设计管理器](/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 by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/narrative-design/quick-start.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.
