> 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/setting-up-the-narrative-design-manager.md).

# 配置叙事设计管理器

介绍如何为角色添加叙事设计管理器、从 Convai 同步故事章节，以及在 Inspector 中连接每个章节的事件。

`ConvaiNarrativeDesignManager` 是角色上常驻的监听器。它会订阅来自 Convai 的区段变更信号，并将这些信号转发给你在 Inspector 中配置的 Unity Events。标准设置是每个角色使用一个 Manager；它会在整个场景生命周期内挂载在角色的 GameObject 上。

### 添加组件

{% stepper %}
{% step %}

#### 选择角色的 GameObject

选择包含  `ConvaiCharacter`  组件的 GameObject。如果两个组件位于同一个 GameObject 上，管理器会自动检测到该角色。
{% endstep %}

{% step %}

#### 添加组件

在 Inspector 中，点击 **添加组件** ，然后找到 **Convai > 叙事设计管理器**.

如果同一个 GameObject 上有  **角色** 字段会自动填充，前提是同一个 GameObject 上有  `ConvaiCharacter` 。否则，请手动将角色拖入该字段。

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FFwSbVyP7YFCNjTUn0dCE%2Fimage.png?alt=media&amp;token=709232fe-2eb5-4a09-adc8-8aad87697595" alt="ConvaiNarrativeDesignManager added to the character GameObject with Character field auto-populated"><figcaption><p>角色 GameObject 上的 ConvaiNarrativeDesignManager。</p></figcaption></figure>
{% endstep %}

{% step %}

#### 与后端同步

在 Inspector 中点击 **与后端同步** 按钮。管理器会调用  `FetchAndSyncFromBackend()`，从 Convai 控制面板获取角色的章节并填充 **叙事章节** 列表。

只有在控制面板上的章节列表发生变化时才需要执行此操作。章节 ID 和 Unity 事件连接会保存在场景文件中，跨会话持久保留。

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FSoEbWhHxS9UEKDDexnFL%2Fimage.png?alt=media&amp;token=7b96dacd-5703-4119-89c8-2124b4f2ad66" alt="Narrative Sections list populated after Sync with Backend"><figcaption><p>成功同步后的 Narrative Sections 列表。</p></figcaption></figure>
{% endstep %}
{% endstepper %}

```mermaid
flowchart TD
    A[点击与后端同步] --> B[FetchSectionsAsync]
    B --> C{成功？}
    C -- 是 --> D[SyncSectionConfigs]
    D --> E[更新 _sectionConfigs 列表]
    E --> F[OnSectionsSynced.Invoke]
    C -- 否 --> G[设置 _lastFetchError]
    G --> H[在 Inspector 中显示错误]
```

### 同步状态

Inspector 中的 **同步状态** 标题区域显示最近一次获取操作的当前状态。所有字段均为只读。

| 字段             | 说明                                     |
| -------------- | -------------------------------------- |
| **正在获取**       | `true` 表示获取操作正在进行。此期间同步按钮不可用。          |
| **上次同步时间**     | 上次成功同步的时间戳（格式： `yyyy-MM-dd HH:mm:ss`). |
| **上次同步的角色 ID** | 上次成功同步时使用的角色 ID。可用于验证配置的角色是否正确。        |
| **上次获取错误**     | 最近一次获取失败时的错误消息（如果有）。如果上次获取成功，则为空。      |

{% hint style="warning" %}
如果 **Last Fetch Error** 不为空，最常见的原因是 API 密钥缺失或无效——请参阅 [配置 API 密钥](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/configure-api-key.md) 或者 `ConvaiCharacter` 组件上的角色 ID 为空。
{% endhint %}

同步结果也会通过 `OnSectionsSynced` 事件报告（见下方的“全局事件”）。其中携带的 `SectionSyncResult` 会准确告知发生了哪些变化：

| 字段                    | 说明                       |
| --------------------- | ------------------------ |
| `SectionsAdded`       | 本地列表中新增的分区（之前未同步过）。      |
| `SectionsUpdated`     | 名称在控制面板上发生更改的分区。         |
| `SectionsOrphaned`    | 自上次同步以来从控制面板中移除的分区。      |
| `SectionsReactivated` | 先前已成为孤立分区、但已在控制面板上恢复的分区。 |

### 叙事区段

同步后，控制面板上的每个分区都会作为一个条目显示在 **叙事分区** 列表中。每个条目都是一个 `UnitySectionEventConfig` ，包含以下字段：

| 字段        | 类型            | 说明                                           |
| --------- | ------------- | -------------------------------------------- |
| **分区 ID** | `string` （只读） | 唯一标识符，与控制面板上的分区相对应。切勿手动编辑。                   |
| **分区名称**  | `string` （只读） | 控制面板中的显示名称。名称更改后会在下次同步时自动更新。                 |
| **已孤立**   | `bool` （只读）   | `true` 表示此分区已不再存在于控制面板中。孤立分区会显示警告标记，其事件不会触发。 |
| **分区开始时** | `UnityEvent`  | 在角色切换 **进入** 此分区时调用。                         |
| **分区结束时** | `UnityEvent`  | 在角色切换 **离开** 此分区时调用。                         |

#### 配置区段事件

点击 **+** 上的按钮 **分区开始时** 或 **分区结束时** 即可添加侦听器。你可以调用场景中任何游戏对象的任意公共方法，例如设置 Animator 参数、播放 AudioSource、激活 UI 面板等。

**示例：** 要在角色进入“Access Granted”区段时解锁一扇门，请将门的 `DoorController` 组件拖到监听器字段中，然后选择 `DoorController.Unlock`.

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FdskQJcKoJwimtigck5zr%2Fimage.png?alt=media&amp;token=7b28b6da-6bde-48de-a72d-59e6e7247eeb" alt="On Section Start Unity Event wired to a DoorController Unlock method"><figcaption><p>已将 On Section Start 连接到 DoorController 组件。</p></figcaption></figure>

#### 孤立区段

如果某个区段已从控制面板中删除，但仍存在于本地列表中，它就会成为孤立区段。孤立条目会保留下来，以免丢失 Unity Event 连线。其中的 `OnSectionStart` 和 `OnSectionEnd` 事件在运行时不会触发。如果你在控制面板中恢复了该区段，请再次点击 **与后端同步** 以重新启用它。

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FHcYSpYUOrvvDNjegzaBP%2Fimage.png?alt=media&amp;token=19160d1a-ac40-47cf-b44c-123c5370c874" alt="Inspector showing an orphaned section entry with a warning badge"><figcaption><p>Narrative Sections 列表中的孤立区段条目。</p></figcaption></figure>

{% hint style="danger" %}
**清除所有区段** 会永久移除所有 `UnitySectionEventConfig` 条目，包括所有 `OnSectionStart` / `OnSectionEnd` 连线。此操作无法撤销。仅当切换到其他角色且不再需要现有连线时才使用。等效的运行时调用为 `ClearAllSectionConfigs()`.
{% endhint %}

### 全局事件

“ **事件** ”折叠面板提供三个全局 Unity 事件，无论当前激活的是哪个分区，它们都会触发。

| 事件                      | 签名                                 | 触发时机                                                                                         |
| ----------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------- |
| `OnAnySectionChanged`   | `UnityEvent<string>`               | 每当活动分区发生变化时触发。以字符串形式接收新分区 ID。                                                                |
| `OnSectionDataReceived` | `UnityEvent<NarrativeSectionData>` | 每次分区切换时触发。携带完整的 `NarrativeSectionData` 负载，其中包括 `BehaviorTreeCode` 和 `BehaviorTreeConstants`. |
| `OnSectionsSynced`      | `UnityEvent<SectionSyncResult>`    | 每次成功调用 `FetchAndSyncFromBackend()` 或 `FetchAndSyncFromBackendAsync()`.                       |

`OnAnySectionChanged` 适用于需要反映当前故事状态、但无需预先知道分区 ID 的 UI，例如每次分区变化时递增的进度指示器。

`OnSectionDataReceived` 会提供原始行为树负载。大多数项目无需直接使用它；它面向需要解析 `BehaviorTreeCode` 或 `BehaviorTreeConstants`.

### Inspector 参考

#### Character Reference 标题

| 字段     | 默认值  | 说明                                                                         |
| ------ | ---- | -------------------------------------------------------------------------- |
| **角色** | 自动检测 | 要监听的 `ConvaiCharacter` （或任何 `IConvaiCharacterAgent`）。如果留空，则会在同一个游戏对象上自动查找。 |

#### Narrative Sections 标题

| 字段        | 默认值  | 说明                                                       |
| --------- | ---- | -------------------------------------------------------- |
| **章节配置**  | 空    | 列表，其中包含 `UnitySectionEventConfig` 条目。由以下内容填充： **与后端同步**. |
| **活动章节数** | 计算得出 | 非孤立条目的数量（只读，显示在检查器标题中）。                                  |
| **孤立章节数** | 计算得出 | 孤立条目的数量（只读，显示在检查器标题中）。                                   |

#### Template Keys 标题

| 字段      | 默认值 | 说明                                                                                                                                                                                                                        |
| ------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **模板键** | 空   | 列表包含 `UnityTemplateKeyConfig` 条目（Key / Value 键值对）。请参阅 [配置叙事模板键](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/narrative-design/template-keys-dynamic-narrative-variables.md) 查看完整文档。 |

#### 同步状态标头

| 字段             | 默认值     | 说明                     |
| -------------- | ------- | ---------------------- |
| **正在获取**       | `false` | 只读。 `true` 表示正在进行数据获取。 |
| **上次同步时间**     | 空       | 只读。上次成功同步的时间戳。         |
| **上次同步的角色 ID** | 空       | 只读。上次同步时使用的角色 ID。      |
| **上次获取错误**     | 空       | 只读。上次的错误消息；成功时为空。      |

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FLWXVaqBRtYqinjDXnRQW%2Fimage.png?alt=media&amp;token=1e72b484-06f8-4bc0-a6d7-0d2df44f7e0d" alt="ConvaiNarrativeDesignManager Inspector showing all header sections"><figcaption><p>ConvaiNarrativeDesignManager 的完整检查器视图。</p></figcaption></figure>

### 后续步骤

{% content-ref url="/pages/87ddb3e30dd1b009eb7bf39b583b5a654f486dbb" %}
[配置叙事设计触发器](https://docs.convai.com/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" %}
[配置叙事模板键](https://docs.convai.com/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 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/convai-unity-sdk/features/narrative-design/setting-up-the-narrative-design-manager.md?ask=<question>&goal=<user_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.
