> 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/unity-plugin-beta-overview/getting-started/setup/custom-scene-setup.md).

# 自定义场景设置

## 简介

本指南演示如何通过添加……将 Convai 集成到您自己的 Unity 场景中 **Convai Manager**，创建 Convai Player，并配置 Convai Characters。

## 先决条件

* 已安装 Convai SDK
* API 密钥配置成功
* 您的场景已在 Unity 中打开

## 分步骤

{% stepper %}
{% step %}
**添加 Convai Manager**

* 在 Unity 顶部菜单中，前往 **GameObject → Convai → 设置所需组件**\
  **或** 在其中右键单击 **层级** → **Convai → 设置所需组件**

<figure><img src="/files/285f4fd929792465f27e5b241f64478be747a071" alt=""><figcaption></figcaption></figure>

* 在弹出窗口中确认并继续。
* **预期结果：** 一个 **Convai Manager** 对象存在于您的场景中。

<figure><img src="/files/8d7111a61524ffe5c1ed71eabc8e8448044d9b46" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**创建或选择您的 Player 对象**

* 选择您现有的玩家 GameObject，或创建一个空的。
* 添加 **Convai Player 组件**.
* 设置 **玩家名称**.
* **预期结果：** 场景中恰好配置了一个 Convai Player。

<figure><img src="/files/7c56c2265c4c7955b8327760fb492988e1474385" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**添加 Convai Character 组件**

对于您想让其具备对话能力的每个角色 GameObject：

* 添加 **Convai Character** 组件
* 设置 **角色 ID**

<figure><img src="/files/6d1e69633557b33d5a4aae92b5ed767759c6a4a7" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**从 Convai 获取您的角色 ID**

* [在 Convai 控制台中](https://docs.convai.com/api-docs/convai-playground/character-customization/character-description#id-1.-character-name-and-id)，打开您的角色并复制其 ID。
  {% endstep %}

{% step %}
**验证您的场景设置**

* 使用以下验证选项之一：
  * 顶部菜单： **GameObject → Convai → 验证场景设置**
  * 层级右键： **Convai → 验证场景设置**

<figure><img src="/files/ae3ac853843f395f55b0d90c8d40721faf5715b9" alt=""><figcaption></figcaption></figure>

* **预期结果：** 类似以下的成功消息：
  * “场景设置正确！”以及找到的 Convai Characters 数量。

<figure><img src="/files/cdc6db2415373acfa8fd9aa898fabb104de67cd8" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**运行对话测试**

* 按 **播放**
* 使用麦克风说话，或在存在时使用 Chat UI
* **预期结果：** 角色会响应。麦克风对话是 **免手持** （无需按住说话）。
  {% endstep %}
  {% endstepper %}

## 故障排查

* **验证失败**
  * 确认一个 **Convai Manager** 对象存在于场景中。
  * 确保您已添加 **Convai Player 组件** 到玩家对象中。
  * 确保每个角色都有有效的 **角色 ID**.
* **角色没有响应**
  * 确认已设置 API 密钥。
  * 检查 Console 中的网络/身份验证错误。

## 结论

您已将 Convai 集成到自定义场景中，验证了设置，并确认角色可以响应。接下来，可选地添加 **聊天 UI** 以支持文本输入和转录。

{% hint style="info" %}
**需要帮助？** 如有疑问，请访问 [**Convai 开发者论坛**](https://forum.convai.com/).
{% endhint %}


---

# 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/unity-plugin-beta-overview/getting-started/setup/custom-scene-setup.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.