> 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` 并且 `以及一个` 实例的引用。

### ConvaiManager

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

**添加它：** 使用 **GameObject > Convai > Setup Required Components** 来一步添加 `ConvaiManager` 及其配套组件。不要通过 Add Component 手动添加——向导会确保正确的配置。

**关键行为：**

* 单例。每个场景中只能存在一个 `ConvaiManager` 。
* 在执行顺序 `-1100` 下运行——它会在所有其他组件之前初始化。
* 在启动时自动发现场景中的 `ConvaiCharacter` 并且 `以及一个` 实例。
* 当启用 `_autoInject` 时，自动将依赖注入到已发现的组件中（默认：开启）。

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

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

### ConvaiRoomManager

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

**关键行为：**

* 在 `Start()` 时自动连接，当 `ConnectOnStart` 是 `true` （默认： `true`).
* 时自动重连，最多 `_maxReconnectAttempts` （默认： `3`).
* 管理麦克风——在连接建立后 `_autoMicStartDelaySeconds` （默认： `0.5秒`后开始捕获音频。

**检视器字段：**

| 字段                          | 默认          | 说明                           |
| --------------------------- | ----------- | ---------------------------- |
| `ConnectOnStart`            | `true`      | 在场景开始时自动连接到 Convai           |
| `_connectionType`           | `音频`        | `音频` 用于仅语音； `视频` 用于同时发送摄像头画面 |
| `_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` 组件。完全支持多个角色：包含两个或更多已注册角色的场景会作为一个共享的多角色会话连接，而只有一个角色的场景会作为单角色会话连接。参见 [多角色会话](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/multi-character-sessions.md) ，了解房间如何构建，以及玩家输入如何一次路由到一个角色。

**Character ID 字段是必填项。** 请从你角色在 [Convai 控制台](https://convai.com).

**检视器字段：**

| 字段                              | 默认      | 说明                            |
| ------------------------------- | ------- | ----------------------------- |
| `中的个人资料获取此值`                    | *（空）*   | **必填。** 来自你的 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` 需要一个 `AudioSource` 在同一个 GameObject 上。

### 以及一个

`以及一个` 标识对话中的用户。它会向转录 UI 提供玩家的显示名称和颜色，并让 Convai 将玩家语音归因到正确的参与者。

**每个场景 `以及一个` 一个。** 同一场景中不支持多个玩家组件。

**检视器字段：**

| 字段              | 默认         | 说明                                 |
| --------------- | ---------- | ---------------------------------- |
| `_playerName`   | `“Player”` | 在转录 UI 中显示的名称                      |
| `_playerId`     | *（空）*      | 用于转录归因的本地 ID（空 = 使用 `_playerName`) |
| `_nameTagColor` | 绿色         | 用于在转录 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 上。

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

#### ConvaiSceneConfig

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

### Convai 自动添加的具身化基础结构

有五个额外组件可能会出现在角色的 GameObject 上，而无需你手动添加。Convai 会在某个具身化模块——凝视、身体动画、肢体语言或情绪——第一次需要它时，为该角色添加每一个组件，通常是在添加这些模块后第一次进入播放模式时。看到它们出现是正常的；这不表示有问题。

| 组件                               | 添加时机                  | 作用                                                                                                        |
| -------------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------- |
| `EmbodimentContext`              | 任何具身化模块解析其角色时         | 角色作用域的组合根，供具身化模块用于查找角色的骨骼结构以及彼此共享的数据                                                                      |
| `StandardRigBinding`             | 模块需要角色的骨骼或面部网格时       | 检测骨骼约定（`ARKit`, `ReallusionCC3`, `ReallusionCC4Extended`, `MetaHuman`，或 `Custom`）并解析骨骼和 BlendShape，以供模块读取 |
| `AnimatorConductor`              | 模块需要驱动 `Animator` 参数  | 参数的单一写入者，因此两个模块绝不会覆盖同一个参数 `Animator` 参数                                                                   |
| `EmbodimentTickScheduler`        | 任何具身化模块注册逐帧更新时        | 每帧以固定的 认知 → 表达 → 完成 顺序运行具身化模块                                                                             |
| `FacialBlendshapeCompositorHost` | 模块需要写入面部 BlendShape 时 | 面部 BlendShape 输出的单一写入者，每帧将唇形同步、情绪和其他来源合并为一个结果                                                             |

{% hint style="info" %}
这些组件都不会出现在 **Add Component** 菜单中。 `StandardRigBinding` 只有一个组件你可以自己添加——从 **Add Component > Convai > Embodiment > Character Rig** ——如果你想在播放模式前配置骨架检测。其他四个是 SDK 内部组件，绝不会手动添加。
{% endhint %}

### 下一步

现在你已经了解这些组件了，来从头构建你自己的场景吧。

{% 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 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.