场景组件参考

了解 ConvaiManager、ConvaiRoomManager、ConvaiCharacter 和 ConvaiPlayer 的作用，以及它们如何相互依赖。

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

轮流发言设置也在此配置。请参见 配置对话输入模式.

ConvaiCharacter

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

角色 ID 字段是必填项。 请从你的角色资料页获取此值，位于 Convai 仪表板.

检查器字段：

字段	默认值	说明
_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 中标识玩家的颜色

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

有用的方法：

// 在运行时覆盖显示名称（例如，玩家登录后）
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、预制体和自动连接行为定义在可复用资源中，而不是直接写在检查器中。适用于管理跨场景的多个角色。完整细节请参见高级主题。

下一步

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

构建自定义场景