> 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/migration-guide.md).
# 迁移指南
本指南说明如何将 Unity 项目从旧版 Convai SDK 迁移到最新的 Convai SDK。
{% hint style="warning" %}
重要：备份你的项目
开始之前，请先为你的 Unity 项目创建完整备份，以避免意外数据丢失。
{% endhint %}
{% stepper %}
{% step %}
**移除旧版 Convai SDK**
1. 打开你的 Unity 项目。
2. 在 Project 窗口中，转到 `Assets`.
3. 找到旧版 SDK 中的 `Convai` 文件夹。
4. 删除整个文件夹。
移除后，在所有引用迁移完成之前，Unity 可能会显示编译错误。
{% endstep %}
{% step %}
**安装最新的 Convai SDK**
使用以下任一方式安装最新 SDK：
**选项 A：Unity Asset Store**
1. 打开 Unity Asset Store。
2. 搜索 `Convai SDK`.
3. 下载并导入最新的包。
**选项 B：插件管理器**
1. 打开插件管理器。
2. 安装最新的 Convai 插件。
{% endstep %}
{% step %}
**设置 API 密钥**
**在 Unity 中打开 Convai 账户窗口**
在 Unity 顶部菜单中，转到 **Convai → 账户**.
**从 Convai 复制你的 API 密钥**
1. 在浏览器中打开 Convai 并登录。
2. 找到你的 **API 密钥** 位于仪表板/个人资料设置中。
3. 复制 API 密钥。
**将密钥粘贴并更新到 Unity 中**
* 将密钥粘贴到 **API 密钥** 字段中。
* 单击 **更新 API 密钥**.
* **预期结果：** 账户详情和使用信息已成功刷新。
{% endstep %}
{% step %}
**更新场景设置**
更新场景中的这些关键对象：
**将 Convai Essentials 替换为 ConvaiDefaults**
1. 移除 `ConvaiDefaults` 从场景中。
2. 添加 `ConvaiDefaults` 来自“Convai SDK For Unity/Prefabs/Setup”
你可以通过以下任一方式添加它：
* 将 `ConvaiDefaults` 将 Prefabs/Setup 文件夹中的 prefab 拖入场景。
* 在 Project 窗口中搜索 `ConvaiDefaults` 并手动添加它。
**将 ConvaiNPC 替换为 ConvaiCharacter**
1. 选择每个 NPC 角色对象。
2. 移除缺失/旧版 Convai 组件（如有）。
3. 添加 `Convai 角色` 组件。
**音频设置**
1. 添加后 `ConvaiCharacter`，使用检查器中显示的设置按钮。
2. 这将自动添加/配置一个 `音频源` 组件。
{% endstep %}
{% step %}
**口型同步设置（可选）**
如果你的角色是人形并使用面部唇部动作：
1. 选择角色对象。
2. 添加 `Convai 口型同步` 组件。
3. 根据你的头像设置配置 viseme/混合形状。
你可以了解更多关于添加口型同步的内容 [这里](https://docs.convai.com/api-docs/plugins-and-integrations/unity-plugin-beta-overview/getting-started/setup/adding-lip-sync-to-your-character)
{% endstep %}
{% endstepper %}
---
# 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/migration-guide.md?ask=
```
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.