For the complete documentation index, see llms.txt. This page is also available as Markdown.

构建自定义场景

使用“设置所需组件”命令向新的 Unity 场景添加所需的 Convai 组件,并配置你的第一个角色。

新的 Unity 场景在角色能够听到玩家并作出回应之前,需要将三个 Convai 组件连接好:管理器、角色和玩家。请在空场景中使用 设置所需组件 命令,然后添加并配置角色本身。

最低必需层级

每个可运行的 Convai 场景都需要这三项:

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

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

1

添加所需的管理器组件

在 Unity 编辑器菜单栏中,选择 GameObject > Convai > 设置所需组件.

Unity 会创建一个 ConvaiManager 带有 ConvaiManager 和 ConvaiRoomManager 所附加的,以及一个 ConvaiPlayer 带有 ConvaiPlayer 所附加的。两者都会出现在层级视图中。

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

2

将 ConvaiCharacter 添加到你的 NPC

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

3

添加 AudioSource 和 ConvaiAudioOutput

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

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

4

设置 Character ID

在 ConvaiCharacter 在该组件中,将 角色 ID 字段设为你在 Convai 仪表板.

5

验证场景

在菜单栏中选择 GameObject > Convai > 验证场景设置.

会出现一个对话框,列出错误、警告和建议的后续步骤。

错误(必须修复):

Error
修复方法

没有 ConvaiManager 已找到

运行 设置所需组件

没有 ConvaiCharacter 已找到

添加 ConvaiCharacter 到你的 NPC GameObject 上

ConvaiCharacter 没有 Character ID

从你的仪表板中设置 Character ID

没有 ConvaiPlayer 已找到

运行 设置所需组件

警告:

警告
修复方法

API 密钥未配置

打开 Convai > Settings > Credentials 并输入你的密钥

当验证器报告没有错误时,该场景就已准备好进入播放模式。

6

进入播放模式

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

  • [ConvaiRuntime] 已成功启动 — SDK 已初始化

  • [RoomConnectionRuntimeAdapter] 房间连接成功(模式=create)。 — 房间已连接到 Convai

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

如果你之后为 NPC 添加 Gaze、Body Animation、Body Language 或 Emotion 模块组件,Convai 会自动向同一个 GameObject 添加配套基础设施组件。请参见 场景组件参考 了解各自的作用。

编辑随 SDK 提供的设置

某些可选模块会将角色指向一个随 Convai 包提供的默认设置资源。你第一次从角色的检查器中更改这些资源中的某个字段时,Convai 会将该资源复制到你的项目中,把角色指向该副本,并在副本上应用你的修改——打包中的原始资源永远不会就地编辑。

副本会创建在角色的 prefab 旁边(如果有的话),否则位于 Assets/Convai/<module> 下。你无需手动创建此副本;只需更改一个字段即可,检查器会显示副本的写入位置。

使用示例

示例 1:安全培训模拟

场景: 一名工业安全培训 NPC 会回答受训者关于设备操作流程的问题。

设置:

  • NPC GameObject: SafetyTrainer 使用 ConvaiCharacter, ConvaiAudioOutput, AudioSource

  • Character ID:来自 Convai 控制面板的安全培训角色 ID

  • ConvaiCharacter._characterName: “安全培训员”

  • ConvaiCharacter._enableRemoteAudio: true

预期结果: 受训者与 NPC 对话,并收到有关安全流程的语音回复。角色名称会显示在转写界面中。

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

场景: 一个包含两个角色的医疗培训模拟——一名监督医生和一名护士。

设置:

  • 两个独立的 NPC GameObject,每个都带有 ConvaiCharacter, ConvaiAudioOutput, AudioSource

  • 每个 ConvaiCharacter 都有各自唯一的 Character ID

  • 只需一个 ConvaiManager 以及一个 ConvaiPlayer 位于场景中

预期结果: 两个角色都会被自动发现并注册。无需添加组件,也无需填写字段: ConvaiManager 会让对话始终指向玩家正在交谈的角色,并在玩家注意力转移时将其切换过去。请参见 对话目标定位 其中决定正在被呼叫对象的规则及其调节设置。

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

下一步

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

验证你的设置

最后更新于

这有帮助吗?