> 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 场景都需要这三样东西：

```
[管理器 GameObject] → ConvaiManager + ConvaiRoomManager
[NPC GameObject] → ConvaiCharacter + ConvaiAudioOutput + AudioSource
[Player GameObject] → ConvaiPlayer
```

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

{% stepper %}
{% step %}

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

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

Unity 会创建一个 **ConvaiManager** 带有 `ConvaiManager` 和 `ConvaiRoomManager` 已附加的……，以及一个 **ConvaiPlayer** 带有 `ConvaiPlayer` 已附加的……。两者都会出现在层级面板中。

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

{% step %}

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

在层级面板中，选择你想要设置为可对话的 NPC GameObject。在 Inspector 中，点击 **Add Component** 并添加 `ConvaiCharacter`.
{% endstep %}

{% step %}

#### 添加 AudioSource 和 ConvaiAudioOutput

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

这三个组件—— `ConvaiCharacter`, `ConvaiAudioOutput`，以及 `AudioSource` ——现在都应该出现在 Inspector 中同一个 GameObject 上。
{% endstep %}

{% step %}

#### 设置 Character ID

在 `ConvaiCharacter` 组件，设置 **Character ID** 字段，填入你在 [Convai 控制台](https://convai.com).

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

{% step %}

#### 验证场景

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

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

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

| 错误                                | 修复                                        |
| --------------------------------- | ----------------------------------------- |
| 未 `ConvaiManager` 发现              | 运行 **设置所需组件**                             |
| 未 `ConvaiCharacter` 发现            | 添加 `ConvaiCharacter` 到你的 NPC GameObject 上 |
| `ConvaiCharacter` 没有 Character ID | 从控制台设置 Character ID                       |
| 未 `ConvaiPlayer` 发现               | 运行 **设置所需组件**                             |

**警告：**

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

当验证器未报告错误时，场景就可以进入 Play Mode 了。
{% endstep %}

{% step %}

#### 进入 Play Mode

按 **播放**。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`: `“Safety Trainer”`
* `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, and the optional `goal` 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>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.