验证你的设置

运行场景验证工具，确认所有必需组件都已存在、正确连接并配置无误。

在部署或分享你的场景之前，请运行 SDK 内置的验证器，并确认 Play Mode 的启动顺序。本页涵盖验证器执行的所有检查、成功时预期的控制台输出，以及常见失败的故障排查表。

运行场景验证器

场景验证器会检查你的场景是否存在缺失组件、必填字段为空以及常见的错误配置。请在开发过程中的任何时候运行它——不必等到最后。

在 Unity Editor 菜单栏中，选择 GameObject > Convai > Validate Scene Setup.

会出现一个对话框，其中包含以下列表： 错误 （必须修复）、 警告 （建议处理）和 后续步骤 （建议操作）。

验证器检查

错误 — 必须修复

这些问题会阻止场景连接到 Convai。

错误	原因	修复
没有 ConvaiManager 在场景中找到	SDK 未初始化	运行 GameObject > Convai > Setup Required Components
没有 ConvaiCharacter 在场景中找到	未注册任何角色	添加 ConvaiCharacter 到你的 NPC GameObject
ConvaiCharacter 没有 Character ID	必填字段为空	输入你在 Convai 仪表板中的 Character ID
没有 ConvaiPlayer 在场景中找到	缺少 Player 组件	运行 GameObject > Convai > Setup Required Components

警告 — 建议处理

这些问题不会阻止连接，但可能会影响功能。

警告	原因	修复
API 密钥未配置	ConvaiSettings.HasApiKey 返回 false	打开 Convai > Account 并输入你的 API 密钥
视频模式已启用，但未找到视觉源	_connectionType 为 AudioVideo 但没有 IVisionFrameSource 组件存在	添加帧源组件，或切换到 音频 模式

当验证器显示零错误且零警告时，你的场景就已准备好进入 Play Mode。

Play 模式启动检查清单

验证器通过后，进入 Play Mode，并按顺序观察 Console 中是否出现以下日志行。

• [ConvaiRuntime] 启动成功 — SDK 已初始化所有内部服务
• [RoomConnectionRuntimeAdapter] Character <character-id> 连接成功（模式=create）。 — 角色已连接到 Convai
• [ChatTranscriptUI] 依赖项已通过显式初始化注入 — 记录 UI 已连接（如果存在）
• 角色 IsCharacterReady 变为 true 在 30 秒内——Convai 已确认该角色

角色就绪信号可能会在房间连接后 2–10 秒到达，具体取决于服务器负载。如果它未在以下时间内到达 _characterReadyTimeoutSeconds （默认：30 秒），SDK 会记录超时警告。

要在 IsCharacterReady 运行时检查：

void Start()
{
    var character = FindFirstObjectByType<ConvaiCharacter>();
    character.OnCharacterReady += () => Debug.Log("Character is ready to converse.");
}

故障排查

症状	可能原因	修复
[ConvaiRuntime] 启动成功 不在 Console 中	ConvaiManager 缺失或启动失败	检查 ConvaiManager 是否在场景中。查看 Console 中更早的错误。
房间从未连接——没有角色已连接日志	API 密钥无效或缺失；网络问题	在以下位置验证你的 API 密钥 Convai > Account。检查防火墙规则是否允许到以下地址的 WebSocket/HTTPS： live.convai.com.
[ChatTranscriptUI] 依赖项未注入……	ConvaiManager 在 UI 启动时未找到	确保 ConvaiManager 在场景中。其执行顺序（-1100）保证它最先运行。
角色 IsCharacterReady 保持 false	Character ID 错误，或者你的账户中不存在该角色	验证 Character ID 与你在 Convai 仪表板上看到的内容完全一致。
麦克风从未打开——角色什么也听不到	按键通话模式已开启，且麦克风在开始时处于静音	在 ConvaiRoomManager，确认 模式 为 HandsFree，或者按 T 如果使用按键通话。
角色声音播放，但 blendshape 不会播放动画	ConvaiLipSyncComponent 未配置或配置文件 ID 不匹配	添加 ConvaiLipSyncComponent 到该角色。请验证 _lockedProfileId 与你角色的传输格式匹配。分配目标 SkinnedMeshRenderer（们）。
示例场景中的材质呈粉色	渲染管线不匹配（Built-in 与 URP）	通过以下方式转换材质 Edit > Rendering > Materials > Convert All Built-in Materials to URP，或者手动重新分配 URP 着色器。

设置完成

你的场景现在具备：

• 已安装 SDK，并使用有效 API 密钥连接到 Convai
• 一个包含 ConvaiManager, ConvaiRoomManager, ConvaiCharacter，以及 ConvaiPlayer
• 验证器通过且零错误
• 一个可连接、变为就绪并响应语音输入的角色

下一步

继续入门流程，配置输入模式、音频和 UI。

配置对话输入模式

或者浏览 Features 部分，为你的角色添加 Actions、Emotion、Long-Term Memory 或 Vision。

功能

查看 Core Concepts，以更深入了解会话生命周期和事件系统。

核心概念