场景组件参考

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

每个由 Convai 驱动的场景都由四个核心组件构成。了解每个组件的作用以及它们之间的关系，可以让你更轻松地搭建和调试你的设置。

组件概览

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

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	断开连接后，会话可恢复的秒数

这里还配置了轮流发言设置。请参见 配置对话输入模式.

ConvaiCharacter

ConvaiCharacter 表示场景中的一个 AI 角色。每个与玩家对话的 NPC 或虚拟导师都需要自己的 ConvaiCharacter 组件。完全支持多个角色：包含两个或更多已注册角色的场景会作为一个共享的多角色会话连接，而只有一个角色的场景则作为单角色会话连接。参见 多角色会话 了解房间如何构建，以及玩家输入如何一次路由到一个角色。

Character ID 字段是必填项。 请从 Convai 仪表板.

检查器字段：

字段	默认值	说明
_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 需要一个 AudioSource 位于同一个 GameObject 上。

ConvaiPlayer

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

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

检查器字段：

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

PlayerId 仅是转录 UI 使用的本地显示标识符。它不是用于 Long-Term Memory 的服务器生成的说话者 ID。服务器分配的说话者 ID 会在连接后解析，不会手动设置。

有用的方法：

// 在运行时覆盖显示名称（例如，玩家登录后）
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 会在某个具身化模块——Gaze、Body Animation、Body Language 或 Emotion——首次需要它时添加每个组件，通常是在添加这些模块后首次进入 Play Mode 时。看到它们出现是正常的；并没有出错。

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

这些组件都不会出现在 Add Component 菜单中。 StandardRigBinding 是你唯一可以自己添加的一个——通过 Add Component > Convai > Embodiment > Character Rig ——如果你想在 Play Mode 前配置骨骼检测。其余四个组件属于 SDK 内部组件，绝不会手动添加。

下一步

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

构建自定义场景