> 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 场景都需要以下三项：

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

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

{% stepper %}
{% step %}

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

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

Unity 会创建一个带有 **ConvaiManager** GameObject，并在其上附加 `ConvaiManager` 和 `ConvaiRoomManager` ；此外还会创建一个带有 **ConvaiPlayer** GameObject，并在其上附加 `ConvaiPlayer` 的 GameObject。这两者都会显示在层级视图中。

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

{% step %}

#### 将 ConvaiCharacter 添加到 NPC

在层级视图中，选择要设为可对话角色的 NPC GameObject。在 Inspector 中，点击 **添加组件** 并添加 `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" %}
中的 ID。Character ID 字段为必填项。如果该字段为空，角色将无法连接到 Convai，Scene Validator 也会报告错误。
{% endhint %}
{% endstep %}

{% step %}

#### 验证场景

在菜单栏中，选择 **游戏对象 > Convai > 验证场景设置**.

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

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

| 错误                        | 解决方法                             |
| ------------------------- | -------------------------------- |
| 未找到 `ConvaiManager` 。     | 运行 **设置必需组件**                    |
| 未找到 `ConvaiCharacter` 。   | 将 `ConvaiCharacter` 添加到 NPC 游戏对象 |
| `ConvaiCharacter` 没有角色 ID | 使用控制面板中的角色 ID 进行设置               |
| 未找到 `ConvaiPlayer` 。      | 运行 **设置必需组件**                    |

**警告：**

| 警告         | 解决方法                          |
| ---------- | ----------------------------- |
| 未配置 API 密钥 | 打开 **Convai > 设置 > 凭据** 并输入密钥 |

当验证工具未报告任何错误时，场景即可进入播放模式。
{% endstep %}

{% step %}

#### 进入播放模式

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

* `[ConvaiRuntime] Started successfully` — SDK 已初始化
* `[RoomConnectionRuntimeAdapter] Room connection succeeded (mode=create).` — 房间已连接到 Convai

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

如果之后向 NPC 添加注视、身体动画、身体语言或情绪模块组件，Convai 会自动将所需的支持性基础组件添加到同一个游戏对象中。有关各组件的作用，请参阅 [场景组件参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/scene-components.md) 。
{% endstep %}
{% endstepper %}

### 编辑 SDK 自带的设置

某些可选模块会让角色引用 Convai 包内自带的默认设置资源。首次从角色的检视面板中更改其中一个资源的字段时，Convai 会将该资源复制到项目中，让角色引用副本，并在副本上应用更改，绝不会直接修改包中的原始资源。

如果角色有预制件，副本会创建在预制件旁边；否则会创建在 `Assets/Convai/<module>` 下。无需自行创建副本；只需更改字段即可，检视面板会显示副本的保存位置。

### 使用示例

#### 示例 1：安全培训模拟

**场景：** 一名工业安全培训师 NPC 回答学员有关设备操作规程的问题。

**设置：**

* NPC 游戏对象： `SafetyTrainer` 包含 `ConvaiCharacter`, `ConvaiAudioOutput`, `AudioSource`
* Character ID：Convai 控制台中安全培训师角色的 ID
* `ConvaiCharacter._characterName`: `"Safety Trainer"`
* `ConvaiCharacter._enableRemoteAudio`: `true`

**预期结果：** 受训者与 NPC 对话，并收到关于安全操作流程的语音回复。角色名称会显示在对话记录界面中。

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

**场景：** 一个包含两名角色的医疗培训模拟：一名指导医生和一名护士。

**设置：**

* 两个独立的 NPC GameObject，每个都包含 `ConvaiCharacter`, `ConvaiAudioOutput`, `AudioSource`
* 每个 `ConvaiCharacter` 都有自己唯一的 Character ID
* 只有一个 `ConvaiManager` 和一个 `ConvaiPlayer` 位于场景中

**预期结果：** 两个角色都会被自动发现并注册。无需添加组件，也无需填写字段： `ConvaiManager` 会将对话指向玩家正在交谈的角色，并在玩家的注意力转移时切换对话对象。请参阅 [对话目标选择](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/conversation-targeting.md) ，了解决定对话对象的规则及其相关设置。

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

### 后续步骤

场景构建完成后，在添加功能之前运行验证器，确认所有内容都已正确连接。

{% content-ref url="/pages/21a0b0c11649e9125ef5195167e66c3a2caaadf1" %}
[验证你的设置](https://docs.convai.com/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.
