> 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/getting-started/scene-components.md).

# 场景组件参考

了解每个核心 Convai 场景组件——管理器、房间管理器、角色和玩家——的作用，以及它们彼此之间的依赖关系。

每个由 Convai 驱动的场景都由四个核心组件构成。了解每个组件的作用以及它们之间的关系，可以让搭建和调试配置变得简单明了。

### 组件概览

下图展示了这些组件在运行时的依赖关系。

```mermaid
graph TD
    A[ConvaiManager] --> B[ConvaiRoomManager]
    A --> C[ConvaiPlayer]
    A --> D[ConvaiCharacter]
    D --> E[ConvaiAudioOutput]
    E --> F[AudioSource]
```

`ConvaiManager` 是根组件。它负责启动 SDK，通过 `ConvaiRoomManager`管理房间连接，并持有场景中所有 `ConvaiCharacter` 和 `ConvaiPlayer` 实例的引用。

### ConvaiManager

`ConvaiManager` 是 SDK 的入口点。每个使用 Convai 的场景中都必须包含它。它会初始化所有内部服务，并自动向其他组件注入依赖项。

**添加方式：** 使用 **GameObject > Convai > Setup Required Components** 一次性添加 `ConvaiManager` 及其配套组件。请勿通过 Add Component 手动添加；该向导会确保配置正确。

**主要行为：**

* 单例。每个场景中只能有一个 `ConvaiManager` 实例。
* 执行顺序为 `-1100` ——它会先于所有其他组件初始化。
* 启动时自动查找场景中的 `ConvaiCharacter` 和 `ConvaiPlayer` 实例。
* 启用 `_autoInject` 时，会自动向查找到的组件注入依赖项（默认启用）。

**运行时常用属性：**

| 属性                            | 类型                               | 说明              |
| ----------------------------- | -------------------------------- | --------------- |
| `IsBootstrapped`              | `bool`                           | SDK 内部服务已初始化    |
| `IsInitialized`               | `bool`                           | 启动流程已完成，事件中心已就绪 |
| `IsConnected`                 | `bool`                           | 房间连接处于活动状态      |
| `Characters`                  | `IReadOnlyList<ConvaiCharacter>` | 此管理器持有的所有角色     |
| `Player`                      | `ConvaiPlayer`                   | 此场景中的玩家组件       |
| `ActiveConversationCharacter` | `ConvaiCharacter`                | 当前处于活动状态的对话目标   |

### ConvaiRoomManager

`ConvaiRoomManager` 管理场景与 Convai 之间的连接生命周期。它负责连接、断开连接以及重新连接音频会话。它与 `ConvaiManager`.

**主要行为：**

* 在 `Start()` 时自动连接，前提是 `ConnectOnStart` 为 `true` （默认值： `true`).
* 发生暂时性故障时自动重新连接，最多尝试 `_maxReconnectAttempts` 次（默认值： `3`).
* 管理麦克风——开始采集音频 `_autoMicStartDelaySeconds` （默认值： `0.5s`）连接建立后。

**检查器字段：**

| 字段                          | 默认值         | 说明                             |
| --------------------------- | ----------- | ------------------------------ |
| `ConnectOnStart`            | `true`      | 场景启动时自动连接到 Convai              |
| `_connectionType`           | `Audio`     | `Audio` 仅语音； `Video` 还会发送摄像头画面 |
| `_pushToTalkKey`            | `KeyCode.T` | 用于按键通话输入模式的键盘按键                |
| `_maxReconnectAttempts`     | `3`         | 放弃重新连接前的尝试次数                   |
| `_autoMicStartDelaySeconds` | `0.5`       | 连接后等待多少秒再开启麦克风                 |
| `_roomRejoinTtlSeconds`     | `60`        | 断开连接后会话仍可恢复的时长（秒）              |

此处还可配置轮流发言设置。请参阅 [配置对话输入模式](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/configure-conversation-input-mode.md).

### ConvaiCharacter

`ConvaiCharacter` 代表场景中的一个 AI 角色。每个与玩家交谈的 NPC 或虚拟讲师都需要各自的 `ConvaiCharacter` 组件。完全支持多个角色：包含两个或更多已注册角色的场景会连接为一个共享的多角色会话，而恰好包含一个角色的场景则会连接为单角色会话。有关房间的构建方式以及玩家输入如何一次路由给一个角色，请参阅 [多角色会话](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/multi-character-sessions.md) 。

**Character ID（角色 ID）字段为必填项。** 请从角色在 [Convai 控制面板](https://convai.com).

**检查器字段：**

| 字段                              | 默认值     | 说明                         |
| ------------------------------- | ------- | -------------------------- |
| `_characterId`                  | *（空）*   | **必填。** Convai 控制面板中的唯一 ID |
| `_characterName`                | *（空）*   | 在转录文本和日志中显示的名称             |
| `_nameTagColor`                 | 白色      | 用于在转录文本 UI 中标识此角色的颜色       |
| `_autoConnect`                  | `false` | 场景加载后立即开始对话                |
| `_enableRemoteAudio`            | `true`  | 播放角色的语音音频                  |
| `_enableSessionResume`          | `false` | 重新连接时恢复上一个会话               |
| `_characterReadyTimeoutSeconds` | `30`    | 等待角色就绪信号的秒数（0 = 不限时）       |

**运行时常用属性：**

| 属性                   | 类型             | 说明                   |
| -------------------- | -------------- | -------------------- |
| `IsCharacterReady`   | `bool`         | 角色已收到 Convai 发出的就绪信号 |
| `IsSessionConnected` | `bool`         | 已连接到房间（可能尚未收到就绪信号）   |
| `IsInConversation`   | `bool`         | 已连接且就绪——处于真实对话状态     |
| `IsSpeaking`         | `bool`         | 角色当前正在输出音频           |
| `SessionState`       | `SessionState` | 完整的连接状态枚举            |

**组件依赖项：** `ConvaiAudioOutput` （处理此角色的音频播放）必须位于同一个 GameObject 上。 `ConvaiAudioOutput` 需要在同一个 GameObject 上有一个 `AudioSource` 。

### ConvaiPlayer

`ConvaiPlayer` 用于在对话中标识用户。它会向转录文本 UI 提供玩家的显示名称和颜色，并让 Convai 将玩家的发言归属于正确的参与者。

**每个场景 `ConvaiPlayer` 组件一个。** 不支持在同一场景中添加多个玩家组件。

**检查器字段：**

| 字段              | 默认值    | 说明                                  |
| --------------- | ------ | ----------------------------------- |
| `_playerName`   | `"玩家"` | 在转录界面中显示的名称                         |
| `_playerId`     | *（空）*  | 用于转录归属的本地 ID（为空 = 使用 `_playerName`) |
| `_nameTagColor` | 绿色     | 用于在转录界面中标识玩家的颜色                     |

{% hint style="info" %}
`PlayerId` 仅是转录界面的本地显示标识符。它不是用于长期记忆的服务器生成说话者 ID。服务器分配的说话者 ID 会在连接后解析，无需手动设置。
{% endhint %}

**实用方法：**

```csharp
// 在运行时覆盖显示名称（例如，玩家登录后）
GetComponent<ConvaiPlayer>().SetRuntimeDisplayName("Dr. Reyes");

// 同时设置名称和 ID
GetComponent<ConvaiPlayer>().Configure("Dr. Reyes", "user-123");
```

### 可选组件

#### ConvaiAudioOutput

处理单个角色的音频播放。将其添加到与 `ConvaiCharacter`相同的 GameObject 上。需要同一 GameObject 上存在 `AudioSource` 。

| 字段             | 默认值     | 说明         |
| -------------- | ------- | ---------- |
| `Volume`       | `1.0`   | 播放音量（0–1）  |
| `IsMuted`      | `false` | 静音此角色的音频输出 |
| `_use3DAudio`  | `true`  | 启用空间（3D）音频 |
| `_minDistance` | `1`     | 空间音频最小距离   |
| `_maxDistance` | `50`    | 空间音频最大距离   |

#### ConvaiSceneConfig

可选的 ScriptableObject（**Assets > Create > Convai > Scene Config**），可让你在可复用资源中定义角色 ID、预制件和自动连接行为，而不必在 Inspector 中逐项配置。适用于管理多个场景中的多个角色。详情请参阅“高级主题”。

### Convai 自动添加的具身化基础设施

角色的 GameObject 上可能会出现五个额外组件，无需你手动添加。每当某个具身化模块（注视、身体动画、肢体语言或情绪）需要在该角色上使用某个组件时，Convai 都会首次自动添加该组件；通常是在添加上述模块后首次进入 Play Mode 时。看到这些组件出现是正常现象，并不表示发生了故障。

| 组件                               | 添加时机                 | 功能                                                                                                |
| -------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------- |
| `EmbodimentContext`              | 任何具身化模块解析其角色时        | 角色级组合根，具身化模块用它来查找角色的骨架以及彼此共享的数据                                                                   |
| `StandardRigBinding`             | 某个模块需要角色的骨骼或面部网格时    | 检测骨架规范（`ARKit`, `ReallusionCC3`, `ReallusionCC4Extended`, `MetaHuman`或 `Custom`），并解析骨骼和混合形状，供模块读取 |
| `AnimatorConductor`              | 模块需要驱动 `Animator` 参数 | 对 `Animator` 参数采用单一写入者机制，因此两个模块绝不会覆盖同一个参数                                                         |
| `EmbodimentTickScheduler`        | 任何具身模块都可以注册逐帧更新      | 每帧按固定顺序运行具身模块：认知 → 表现 → 收尾                                                                        |
| `FacialBlendshapeCompositorHost` | 模块需要写入面部混合形状         | 面部混合形状输出的单一写入者，每帧将口型同步、情绪和其他来源合并为一个结果                                                             |

{% hint style="info" %}
这些组件都不会显示在 **添加组件** 菜单中。 `StandardRigBinding` 是唯一可以自行添加的组件——路径为 **添加组件 > Convai > Embodiment > Character Rig** ——如果你想在播放模式前配置骨架检测。其他四个组件是 SDK 内部组件，无需手动添加。
{% endhint %}

### 后续步骤

现在你已了解这些组件，可以从头开始构建自己的场景了。

{% content-ref url="/pages/2c636c36fad522854df1a097c056f4a12f1444ae" %}
[构建自定义场景](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/build-a-custom-scene.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/getting-started/scene-components.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.
