> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/build-a-custom-scene.md).

# 构建自定义场景

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

### 最低必需层级结构

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

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

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

{% stepper %}
{% step %}

#### 添加所需的管理器组件

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

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

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

{% step %}

#### 将 ConvaiCharacter 添加到你的 NPC

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

{% step %}

#### 添加 AudioSource 和 ConvaiAudioOutput

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

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

{% step %}

#### 设置角色 ID

在 `ConvaiCharacter` 在该 **角色 ID** 字段设置为你在仪表板中的角色 ID [Convai 仪表板](https://convai.com).

{% hint style="warning" %}
Character ID 字段是必需的。如果留空，角色将无法连接到 Convai，场景验证器会报告错误。
{% endhint %}
{% endstep %}

{% step %}

#### 验证场景

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

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

**错误（必须修复）：**

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

**警告：**

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

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

{% step %}

#### 进入播放模式

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

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

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

### 使用示例

#### 示例 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 不会共享对话上下文。

### 下一步

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

{% content-ref url="/pages/21a0b0c11649e9125ef5195167e66c3a2caaadf1" %}
[验证你的设置](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/validate-your-setup.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/build-a-custom-scene.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.