> 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/convai-unity-sdk/features/narrative-design/quick-start.md).

# 叙事设计快速入门

本指南将带你走完最快速的流程，完成一个可工作的 Narrative Design 设置。到最后，角色会在玩家穿过触发区域时对章节变更作出反应——全程都通过检视器完成，无需任何代码。

### 先决条件

开始前，请确认：

* [ ] A `ConvaiCharacter` 已在场景中，并且其 Character ID 已在检视器中设置
* [ ] 该角色至少在……上定义了一个章节和一个触发器 [Convai 仪表板](https://convai.com)

{% stepper %}
{% step %}

#### 添加 Narrative Design Manager

选择包含你的 `ConvaiCharacter` 组件的 GameObject。在检视器中，点击 **添加组件** 并搜索 **叙事设计管理器** （路径： **Convai > Narrative Design Manager**).

管理器会自动检测 `ConvaiCharacter` 同一 GameObject 上的……。如果你的角色位于另一个 GameObject 中，请将其拖到 **角色** 字段中。

<figure><img src="/files/9745ec7552f01c297d729ee293667d4536625b2f" alt="ConvaiNarrativeDesignManager added to the character GameObject in the Unity Inspector"><figcaption><p>角色 GameObject 上的 ConvaiNarrativeDesignManager 中。</p></figcaption></figure>
{% endstep %}

{% step %}

#### 从仪表板同步章节

在管理器的检视器中，点击 **与后端同步**。SDK 会获取你的叙事章节并填充 **叙事章节** 列表。每一项都会显示来自仪表板的章节名称。

如果列表仍为空，请确认已在 `ConvaiCharacter` 上设置角色 ID，并且你的 API 密钥有效——请参阅 [配置 API 密钥](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/configure-api-key.md)。该 **上一次获取错误** 字段会在出错时显示具体错误。

<figure><img src="/files/105a6a1ff1bc1b3c2ed387dd1451be66a6c2fad1" alt="Narrative Sections list populated after clicking Sync with Backend"><figcaption><p>成功同步后的 Narrative Sections 列表。</p></figcaption></figure>
{% endstep %}

{% step %}

#### 连接章节事件

展开 **叙事章节** 列表中的第一个章节条目。你会看到两个 Unity 事件： **章节开始时** 是位于 **章节结束时**.

单击 **+** on **章节开始时**，将任意 GameObject 拖到对象字段中，并选择要调用的方法。用于测试的最简单选项是 `NarrativeDesignDebugLogger` 下面的辅助工具——将其添加到任意 GameObject，将该 GameObject 拖到监听器字段，然后选择 `NarrativeDesignDebugLogger.LogSectionStarted`.

<details>

<summary>NarrativeDesignDebugLogger.cs</summary>

```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);
    }
}
```

</details>

<figure><img src="/files/62c12ce32340c9e4b525d939352694a1d60f8a51" alt="On Section Start Unity Event wired to a debug logger component"><figcaption><p>已将 On Section Start 连接到 NarrativeDesignDebugLogger。</p></figcaption></figure>
{% endstep %}

{% step %}

#### 添加 Narrative Design Trigger

在场景中创建一个新的空 GameObject，并将其放置在玩家会经过的位置。点击 **添加组件** 并搜索 **Convai 叙事设计触发器** （路径： **Convai > Convai Narrative Design Trigger**).

将你的 `ConvaiCharacter` 到 **角色** 字段中，或者留空以让 **自动查找角色** 自动定位它。

<figure><img src="/files/4741dada36f0ef24f2fb4f50b9379db4e05daa13" alt="ConvaiNarrativeDesignTrigger added to an empty GameObject in the scene"><figcaption><p>位于世界空间触发 GameObject 上的 ConvaiNarrativeDesignTrigger。</p></figcaption></figure>
{% endstep %}

{% step %}

#### 获取并选择一个触发器

在 Trigger 组件的检视器中，点击 **获取** 以从仪表板加载命名触发器。将出现下拉菜单——选择应将图谱推进到第一个章节的触发器。

<figure><img src="/files/fd46e8f0697313cf3efb9fcd2a656be7b996b08c" alt="Trigger Selection dropdown populated after clicking Fetch"><figcaption><p>从 Convai 仪表板填充的触发器下拉菜单。</p></figcaption></figure>
{% endstep %}

{% step %}

#### 添加碰撞体

默认激活模式是 **碰撞**，它使用 Unity 的 `OnTriggerEnter`。在同一个触发器 GameObject 上，点击 **添加组件 > Box Collider**。在 Box Collider 的设置中，启用 **触发器**.

调整碰撞体大小，以覆盖你希望触发器触发的区域。在场景视图中，绿色线框盒显示检测区域。

<figure><img src="/files/beb0e4f34852b5768d0c9dcc504c02f35e745d74" alt="Box Collider with Is Trigger enabled on the trigger zone GameObject"><figcaption><p>已启用 Is Trigger 的 Box Collider。</p></figcaption></figure>
{% endstep %}

{% step %}

#### 按下 Play，并穿过

{% hint style="warning" %}
**玩家设置检查清单——在按下 Play 之前验证这三项：**

* **标签：** 玩家 GameObject 的标签必须设置为 `玩家`。Trigger 组件会通过标签匹配来识别玩家。
* **碰撞体：** 玩家必须拥有 Collider 组件。没有它， `OnTriggerEnter` 将永远不会触发。
* **刚体：** 触发区域或玩家必须拥有一个 `Rigidbody`。将其添加到玩家上——如果你将其添加到触发区域，那么你必须对场景中的每个触发对象都重复这样做。

缺少其中任何一项，都是触发器在 Play 模式下看起来毫无反应的最常见原因。
{% endhint %}

进入 Play 模式，并让玩家穿过碰撞体区域。

{% hint style="success" %}
当玩家进入该区域时，章节 ID 会出现在 Console 中。角色的下一次回复将反映新章节的目标。
{% endhint %}
{% endstep %}
{% endstepper %}

### 刚刚发生了什么

穿过碰撞体区域后，完整的 Narrative Design 流程被激活：

该 `ConvaiNarrativeDesignTrigger` 通过 `OnTriggerEnter` 检测到了玩家，并调用了 `InvokeTrigger()` ，使用你选择的触发器名称。SDK 会将触发器排队，直到角色的实时会话开启，然后发送一个 `触发消息` 通过 RTVI 连接发送到 Convai。Convai 沿匹配的边推进叙事图，并返回一个 `behavior-tree-response` ，其中包含新的章节 ID。 `ConvaiNarrativeDesignManager` 将该章节 ID 与其本地列表进行匹配，并触发了 `OnSectionStart` 在匹配条目上的……

有关此流程的完整说明，请参阅 [叙事设计如何工作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/narrative-design/how-narrative-design-works.md).

### 下一步

{% content-ref url="/pages/59d31b624a51d8790cd9e50732a32794dcfd69f1" %}
[配置叙事设计管理器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/narrative-design/setting-up-the-narrative-design-manager.md)
{% endcontent-ref %}

{% content-ref url="/pages/87ddb3e30dd1b009eb7bf39b583b5a654f486dbb" %}
[配置叙事设计触发器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/narrative-design/setting-up-narrative-design-triggers.md)
{% endcontent-ref %}

{% content-ref url="/pages/630c1743293b81e62f2237b571dcf928c0d73285" %}
[配置叙事模板键](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/narrative-design/template-keys-dynamic-narrative-variables.md)
{% endcontent-ref %}


---

# 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/convai-unity-sdk/features/narrative-design/quick-start.md?ask=<question>
```

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.