> 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 游戏对象]      → ConvaiCharacter + ConvaiAudioOutput + AudioSource
[玩家 GameObject]   → ConvaiPlayer
```

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

{% stepper %}
{% step %}

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

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

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

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

{% step %}

#### 向你的 NPC 添加 ConvaiCharacter

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

{% step %}

#### 添加 AudioSource 和 ConvaiAudioOutput

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

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

{% step %}

#### 设置角色 ID

在 `ConvaiCharacter` 组件，设置 **Character 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 key not configured | 打开 **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 包中随附的默认设置资源。你第一次在角色的 Inspector 中修改这些资源中的某个字段时，Convai 会将该资源复制到你的项目中，将角色指向该副本，并在副本上应用你的修改——打包中的原始资源绝不会直接就地编辑。

如果角色有 prefab，则副本会在其旁边创建；否则会位于 `Assets/Convai/<module>` 下。你无需自己创建此副本；只需更改一个字段即可，Inspector 会显示副本写入的位置。

### 使用示例

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

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

**设置：**

* NPC GameObject： `SafetyTrainer` 与 `ConvaiCharacter`, `ConvaiAudioOutput`, `AudioSource`
* Character ID：你在 Convai 控制面板中安全培训角色的 ID
* `ConvaiCharacter._characterName`: `“安全培训员”`
* `ConvaiCharacter._enableRemoteAudio`: `是`

**预期结果：** 角色名称会显示在转录 UI 中。

#### 示例 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 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.