> 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).

# 构建自定义场景

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

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

### 最低必需层级

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

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

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

{% stepper %}
{% step %}

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

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

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

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

{% step %}

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

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

{% step %}

#### 添加 AudioSource 和 ConvaiAudioOutput

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

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

{% step %}

#### 设置 Character ID

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

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

{% step %}

#### 验证场景

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

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

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

| Error                             | 修复方法                                      |
| --------------------------------- | ----------------------------------------- |
| 没有 `ConvaiManager` 已找到            | 运行 **设置所需组件**                             |
| 没有 `ConvaiCharacter` 已找到          | 添加 `ConvaiCharacter` 到你的 NPC GameObject 上 |
| `ConvaiCharacter` 没有 Character ID | 从你的仪表板中设置 Character ID                    |
| 没有 `ConvaiPlayer` 已找到             | 运行 **设置所需组件**                             |

**警告：**

| 警告        | 修复方法                                           |
| --------- | ---------------------------------------------- |
| API 密钥未配置 | 打开 **Convai > Settings > Credentials** 并输入你的密钥 |

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

{% step %}

#### 进入播放模式

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

* `[ConvaiRuntime] 已成功启动` — SDK 已初始化
* `[RoomConnectionRuntimeAdapter] 房间连接成功（模式=create）。` — 房间已连接到 Convai

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

如果你之后为 NPC 添加 Gaze、Body Animation、Body Language 或 Emotion 模块组件，Convai 会自动向同一个 GameObject 添加配套基础设施组件。请参见 [场景组件参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/scene-components.md) 了解各自的作用。
{% endstep %}
{% endstepper %}

### 编辑随 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` 会让对话始终指向玩家正在交谈的角色，并在玩家注意力转移时将其切换过去。请参见 [对话目标定位](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/conversation-targeting.md) 其中决定正在被呼叫对象的规则及其调节设置。

除非你的 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
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=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.