> 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 驱动的场景都由四个核心组件构成。了解每个组件的作用以及它们彼此之间的关系，会让你的搭建和调试变得很直接。

### 组件概览

下图展示了这些组件在运行时如何相互依赖。

```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` 用于仅语音； `AudioVideo` 用于同时发送摄像头画面 |
| `_pushToTalkKey`            | `KeyCode.T` | 用于按键通话输入模式的键盘按键                         |
| `_maxReconnectAttempts`     | `3`         | 放弃重连前的尝试次数                              |
| `_autoMicStartDelaySeconds` | `0.5`       | 连接后等待多久再打开麦克风                           |
| `_roomRejoinTtlSeconds`     | `60`        | 断开连接后，会话仍可恢复的秒数                         |

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

### ConvaiCharacter

`ConvaiCharacter` 表示你场景中的一个 AI 角色。每个与玩家对话的 NPC 或虚拟导师都需要自己的 `ConvaiCharacter` 组件。完全支持多个角色。SDK 一次只连接一个角色——当玩家与另一个角色对话时，会话会自动切换到该角色。

**角色 ID 字段是必填项。** 请从你的角色资料页获取此值，位于 [Convai 仪表板](https://convai.com).

**检查器字段：**

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

**运行时有用的属性：**

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

**组件依赖：** `ConvaiAudioOutput` （负责此角色的音频播放）必须与其位于同一个 GameObject 上。 `ConvaiAudioOutput` 需要一个 `AudioSource` 位于同一个 GameObject 上。

### ConvaiPlayer

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

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

**检查器字段：**

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

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

**有用的方法：**

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

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

### 可选组件

#### ConvaiAudioOutput

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

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

#### ConvaiSceneConfig

一个可选的 ScriptableObject（**Assets > Create > Convai > Scene Config**），它允许你将角色 ID、预制体和自动连接行为定义在可复用资源中，而不是直接写在检查器中。适用于管理跨场景的多个角色。完整细节请参见高级主题。

### 下一步

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

{% content-ref url="/pages/2c636c36fad522854df1a097c056f4a12f1444ae" %}
[构建自定义场景](/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 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/getting-started/scene-components.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.