构建自定义场景

使用“Setup Required Components”命令将所需的 Convai 组件添加到新的 Unity 场景中，并配置你的第一个角色。

本页将带你从头开始使用 Convai AI 角色搭建一个新场景。到最后，你的场景将具备让角色接收语音输入并作出响应所需的最少组件。

最低必需层级结构

每个可正常工作的 Convai 场景都需要这三样：

[Manager GameObject]  → ConvaiManager + ConvaiRoomManager
[NPC GameObject]      → ConvaiCharacter + ConvaiAudioOutput + AudioSource
[Player GameObject]   → ConvaiPlayer

设置向导会自动创建第一项和第三项。NPC 组件需要你自己添加。

1

添加所需的管理器组件

在 Unity 编辑器菜单栏中，选择 GameObject > Convai > Setup Required Components.

Unity 会创建一个 ConvaiManager 带有 ConvaiManager 是位于 ConvaiRoomManager 已附加的，以及一个 ConvaiPlayer 带有 ConvaiPlayer 已附加。两者都会显示在层级视图中。

ConvaiRoomManager 始终位于与 ConvaiManager相同的 GameObject 上。不要将其移动到单独的 GameObject 上。

2

将 ConvaiCharacter 添加到你的 NPC

在层级视图中，选择你想设为可对话的 NPC GameObject。在检查器中，点击 添加组件 并添加 ConvaiCharacter.

3

添加 AudioSource 和 ConvaiAudioOutput

在同一个 NPC GameObject 上，添加 AudioSource，然后添加 ConvaiAudioOutput.

这三个组件—— ConvaiCharacter, ConvaiAudioOutput，以及 AudioSource ——现在都应显示在检查器中的同一个 GameObject 上。

4

设置角色 ID

在 ConvaiCharacter 在该 角色 ID 字段设置为你在仪表板中的角色 ID Convai 仪表板.

Character ID 字段是必需的。如果留空，角色将无法连接到 Convai，场景验证器会报告错误。

5

验证场景

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

会出现一个对话框，列出错误、警告和建议的下一步。

错误（必须修复）：

错误	修复
没有 ConvaiManager 发现	运行 设置所需组件
没有 ConvaiCharacter 发现	添加 ConvaiCharacter 到你的 NPC GameObject
ConvaiCharacter 没有 Character ID	从你的仪表板中设置角色 ID
没有 ConvaiPlayer 发现	运行 设置所需组件

警告：

警告	修复
未配置 API 密钥	打开 Convai > 账户 并输入你的密钥

当验证器不再报告错误时，场景就可以进入播放模式了。

6

进入播放模式

按 播放。Unity 控制台会记录：

• [ConvaiRuntime] 已成功启动 — SDK 已初始化
• [RoomConnectionRuntimeAdapter] 角色 <character-id> 已成功连接（mode=create）。 — 角色已连接到 Convai

对着麦克风说话。角色会在几秒钟内作出回应。

使用示例

示例 1：安全培训模拟

场景： 一名工业安全培训 NPC 会回应学员有关设备操作流程的问题。

设置：

• NPC GameObject： SafetyTrainer 其带有 ConvaiCharacter, ConvaiAudioOutput, AudioSource
• Character ID：来自 Convai 仪表板的安全培训角色的 ID
• ConvaiCharacter._characterName: "安全培训师"
• ConvaiCharacter._enableRemoteAudio: true

预期结果： 学员与 NPC 对话，并获得关于安全流程的语音回复。角色名称会显示在转录 UI 中。

示例 2：一个场景中的多个角色

场景： 一个包含两个角色的医疗培训模拟——一名主管医生和一名护士。

设置：

• 两个独立的 NPC GameObject，每个都带有 ConvaiCharacter, ConvaiAudioOutput, AudioSource
• 每个 ConvaiCharacter 都有自己独特的 Character ID
• 只有一个 ConvaiManager 和一个 ConvaiPlayer 位于场景中

预期结果： 两个角色都会被自动发现并注册。对话会根据玩家正在与哪个角色交谈而在它们之间切换。

除非你的 Convai 角色配置明确将它们关联起来，否则角色 A 和角色 B 不会共享对话上下文。

下一步

场景搭建完成后，在添加功能之前运行验证器，确认一切连接正确。

验证你的设置