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

# 设置叙事设计管理器

## ConvaiNarrativeDesignManager 组件

`ConvaiNarrativeDesignManager` 是挂在角色上的永久监听点。它订阅来自 Convai 后端的分节变化信号，并将其转发到你在 Inspector 中配置的 Unity Events。每个角色一个 Manager 是标准设置；它在整个场景生命周期内驻留在角色的 GameObject 上。

## 添加该组件

{% stepper %}
{% step %}
**选择角色的 GameObject**

选择具有你的 `ConvaiCharacter` 组件的 GameObject。如果这两个组件都在同一个 GameObject 上，Manager 会自动检测该角色。
{% endstep %}

{% step %}
**添加该组件**

在 Inspector 中，点击 **添加组件** 并导航到 **Convai > Narrative Design Manager**.

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

<figure><img src="/files/9745ec7552f01c297d729ee293667d4536625b2f" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**与后端同步**

点击 **与后端同步** Inspector 中的按钮。Manager 会调用 `FetchAndSyncFromBackend()`，它会从 Convai 仪表板获取你角色的分节并填充 **叙事章节** 列表中。

只有当你在仪表板上更改了分节列表时，才需要执行此操作。分节 ID 和 Unity Event 绑定会保留在场景文件中，跨会话持续存在。

<figure><img src="/files/66cf59963a52f1f09951411e554a782d24abbe54" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

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

## 同步状态面板

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

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

同步结果也会通过 `OnSectionsSynced` 事件报告（见下方 Global Events）。该 `SectionSyncResult` 所携带的内容会准确告诉你发生了什么变化：

| 字段                    | 说明                    |
| --------------------- | --------------------- |
| `SectionsAdded`       | 本地列表中新加入的分节（之前未同步过）。  |
| `SectionsUpdated`     | 在仪表板上名称发生变化的分节。       |
| `SectionsOrphaned`    | 自上次同步以来已从仪表板移除的分节。    |
| `SectionsReactivated` | 之前已变为孤立，但已在仪表板上恢复的分节。 |

{% hint style="warning" %}
如果 **上一次获取错误** 不为空时，最常见的原因是 API key 缺失或无效（**编辑 > 项目设置 > Convai SDK**）或 `ConvaiCharacter` 组件。
{% endhint %}

## 叙事章节

中的角色 ID 为空。同步完成后，每个仪表板分节都会显示为 **叙事章节** 列表中的一项。每一项都是一个 `UnitySectionEventConfig` ，包含以下字段：

| 字段               | 类型            | 说明                                          |
| ---------------- | ------------- | ------------------------------------------- |
| **Section ID**   | `string` （只读） | 与仪表板上的分节相匹配的唯一标识符。切勿手动编辑。                   |
| **Section Name** | `string` （只读） | 来自仪表板的显示名称。如果名称发生变化，会在下一次同步时自动更新。           |
| **是否孤立**         | `bool` （只读）   | `true` 如果该分节已不再存在于仪表板上。孤立分节会显示警告徽标，其事件不会触发。 |
| **章节开始时**        | `UnityEvent`  | 当角色切换 **进入** 该分节时触发。                        |
| **章节结束时**        | `UnityEvent`  | 当角色切换 **离开** 该分节时触发。                        |

### 配置分节事件

点击 **+** 按钮位于 **章节开始时** 或 **章节结束时** 上以添加监听器。你可以调用场景中任何 GameObject 上的任何公共方法——Animator 参数、AudioSource 播放、UI 面板激活等等。

**例如：** 要在角色进入“Access Granted”分节时打开锁住的门，请将门的 `DoorController` 组件拖到监听器字段中，并选择 `DoorController.Unlock`.

<figure><img src="/files/84abc9eb2cc3fb2a21bda61839efaee0b93be858" alt=""><figcaption></figcaption></figure>

### 孤立分节

当某个分节从仪表板中删除，但仍存在于你的本地列表中时，它就会变为孤立。保留孤立条目是为了不丢失你的 Unity Event 绑定。

{% hint style="warning" %}
孤立分节在运行时绝不会触发它们的 `OnSectionStart` 或 `OnSectionEnd` 事件。如果你在仪表板上恢复了该分节，请再次点击 **与后端同步** 以重新激活它。
{% endhint %}

<figure><img src="/files/49fc912afd218bbcf0a02e5f81c1f41ac810cb06" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
点击 **清除所有分节** （可通过 `ClearAllSectionConfigs()` 在运行时访问，并且在切换角色时会在 Inspector 中显示）会永久移除所有 `UnitySectionEventConfig` 条目，包括所有 `OnSectionStart` / `OnSectionEnd` 绑定。此操作无法撤销。仅当你有意切换到其他角色且不再需要现有绑定时才使用。
{% endhint %}

## 全局事件

该 **事件** 折叠项会暴露三个全局 Unity Event，它们会在无论当前激活的是哪个具体分节时都触发。

| 事件                      | 签名                                 | 触发时机                                                                                         |
| ----------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------- |
| `OnAnySectionChanged`   | `UnityEvent<string>`               | 每当当前激活的分节发生变化时触发。接收新的分节 ID 作为字符串。                                                            |
| `OnSectionDataReceived` | `UnityEvent<NarrativeSectionData>` | 每次分节切换时触发。携带完整的 `NarrativeSectionData` 负载，包括 `BehaviorTreeCode` 是位于 `BehaviorTreeConstants`. |
| `OnSectionsSynced`      | `UnityEvent<SectionSyncResult>`    | 在每次成功调用 `FetchAndSyncFromBackend()` 或 `FetchAndSyncFromBackendAsync()`.                      |

`OnAnySectionChanged` 后触发，这对于需要反映当前故事状态、但又事先不知道分节 ID 的 UI 很有用——例如一个在分节变化时递增的进度指示器。

`OnSectionDataReceived` 提供原始的行为树负载。大多数项目不需要直接使用它；它 предназнач用于解析 `BehaviorTreeCode` 或 `BehaviorTreeConstants`.

## Inspector 参考

### 角色引用标题

| 字段     | 默认值    | 说明                                                                                 |
| ------ | ------ | ---------------------------------------------------------------------------------- |
| **角色** | 自动检测到的 | 该 `ConvaiCharacter` （或任何 `IConvaiCharacterAgent`）以便监听。如果留空，会在同一个 GameObject 上自动找到。 |

### Narrative Sections 标题

| 字段                  | 默认值  | 说明                                              |
| ------------------- | ---- | ----------------------------------------------- |
| **Section Configs** | 空    | 条目列表。由 `UnitySectionEventConfig` 填充。 **与后端同步**. |
| **当前分节数量**          | 计算得出 | 非孤立条目的数量（只读，显示在 Inspector 标题中）。                 |
| **孤立分节数量**          | 计算得出 | 孤立条目的数量（只读，显示在 Inspector 标题中）。                  |

### 模板键标题

| 字段      | 默认值 | 说明                                                                |
| ------- | --- | ----------------------------------------------------------------- |
| **模板键** | 空   | 条目列表。由 `UnityTemplateKeyConfig` 条目（键 / 值对）。完整文档请参阅 Template Keys。 |

### 同步状态标题

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

<figure><img src="/files/b54e84e7a4d3a6699acbb5a50bd7cc9497185eb2" alt=""><figcaption></figcaption></figure>

## 结论

`ConvaiNarrativeDesignManager` 是永久监听器，将 Convai 后端的分节切换桥接到你场景中的 Unity Events。一旦同步完成，每次分节变化都会自动到达正确的 `OnSectionStart` 或 `OnSectionEnd` 处理器，而无需任何轮询或手动状态跟踪。继续到 [设置 Narrative Design 触发器](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/narrative-design/setting-up-narrative-design-triggers.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/setting-up-the-narrative-design-manager.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.