> 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/additional-feature-migration.md).
# 附加功能迁移
#### 附加功能迁移
#### LTM（会话恢复）
无需进行 API 迁移。请根据需要在您的设置中继续启用/禁用会话恢复。
#### 动态信息： `DynamicInfoController` -> `ConvaiRoomManager`
动态信息 API 现在通过以下组件路由： `ConvaiRoomManager`.
```csharp
// 旧版
public class PlayerHealth : MonoBehaviour
{
[SerializeField] private DynamicInfoController _dynamicInfoController;
private int _health = 100;
private void Start()
{
_dynamicInfoController.SetDynamicInfo("玩家生命值为 " + _health);
Debug.Log("玩家生命值为 " + _health);
}
}
// 新版
public class PlayerHealth : MonoBehaviour
{
[SerializeField] private ConvaiRoomManager _convaiRoomManager;
private int _health = 100;
private void Start()
{
_convaiRoomManager.SendDynamicInfo("玩家生命值为 " + _health);
Debug.Log("玩家生命值为 " + _health);
}
}
```
***
### 叙事设计迁移（旧版 -> 当前 SDK）
叙事设计仍受支持，但引用现在与新的 SDK 架构（`ConvaiCharacter` + 模块化叙事组件）。\
旧版设置参考： [将叙事设计添加到您的角色中](https://docs.convai.com/api-docs/plugins-and-integrations/unity-plugin/adding-narrative-design-to-your-character).
#### 叙事快速映射
* `ConvaiNPC` （旧版角色组件） -> `ConvaiCharacter`
* `叙事设计管理器` （旧版设置） -> `Convai 叙事设计管理器` (`ConvaiNarrativeDesignManager`)
* `叙事设计触发器` （旧版设置） -> `Convai 叙事设计触发器` (`ConvaiNarrativeDesignTrigger`)
* `InvokeSelectedTrigger(message)` -> `SetTriggerMessage(message)` + `InvokeTrigger()`
* 角色上仍可通过以下方式直接调用触发器： `SendTrigger(triggerName, message)`
#### 叙事最小迁移步骤
{% stepper %}
{% step %}
**替换旧版 NPC 组件引用**
将旧版 NPC 组件引用替换为 `ConvaiCharacter`.
{% endstep %}
{% step %}
**将 Convai 叙事设计管理器添加到角色**
添加 `Convai 叙事设计管理器` 到角色对象中（或在管理器中分配该角色）。
{% endstep %}
{% step %}
**与后端同步**
单击 **与后端同步** 在管理器检查器中，以获取该角色的章节。
{% endstep %}
{% step %}
**重新绑定章节事件**
重新绑定章节事件（`章节开始时`, `章节结束时`）在管理器中。
{% endstep %}
{% step %}
**将叙事设计触发器添加到触发对象**
添加 `Convai 叙事设计触发器` 到触发对象，并分配相同的 `ConvaiCharacter`.
{% endstep %}
{% step %}
**获取触发器并配置激活**
单击 **获取** 在触发器检查器中，选择一个触发器，并配置激活模式（碰撞/接近/手动/基于时间）。
{% endstep %}
{% endstepper %}
#### 脚本迁移示例（触发器调用）
```csharp
// 旧版
if (convaiNPC.TryGetComponent(out NarrativeDesignTrigger narrativeDesignTrigger))
{
string message = "玩家已收集到足够的资源";
narrativeDesignTrigger.InvokeSelectedTrigger(message);
}
// 新版
if (convaiCharacter.TryGetComponent(out ConvaiNarrativeDesignTrigger narrativeDesignTrigger))
{
string message = "玩家已收集到足够的资源";
narrativeDesignTrigger.SetTriggerMessage(message);
narrativeDesignTrigger.InvokeTrigger();
}
```
#### 注意
* 章节/触发器列表按角色 ID 获取，因此在同步/获取之前始终确保正确的 `ConvaiCharacter` 已被分配。
* `InvokeTrigger()` 发送当前配置的触发器名称 + 可选消息。
* 对于完全由代码驱动的流程，您可以直接调用 `convaiCharacter.SendTrigger(triggerName, message)` 。
***
### 转录 UI 迁移（旧版动态 UI -> ChatTranscriptUI）
转录 UI 架构已从直接推送模型更改为基于视图模型的流程。
#### 更改内容
* **旧模型：** UI 类直接使用以下方式推送文本： `ConvaiChatUIHandler`, `ChatUIBase`，以及 `UIType`.
* **新模型：** UI 是一个轻量视图，实现 `ITranscriptUI`；路由/聚合发生在控制器和呈现策略层。
* **结果：** 自定义 UI 主要应渲染 `TranscriptViewModel`.
#### 快速映射
* `ConvaiChatUIHandler` -> `TranscriptUIController` + 呈现策略
* 从以下类派生的自定义类 `ChatUIBase` -> `MonoBehaviour` 实现 `ITranscriptUI`
* `SendCharacterText(...)` / `SendPlayerText(...)` -> `DisplayMessage(TranscriptViewModel viewModel)`
* 完成消息 -> `CompleteMessage(string messageId)`
* 清除转录/聊天 -> `ClearAll()`
* 按类型激活 UI -> `标识符` + `SetActive(bool active)`
#### 最小迁移步骤
{% stepper %}
{% step %}
**创建一个新脚本**
创建一个新脚本（例如， `MyGameTranscriptUI.cs`).
{% endstep %}
{% step %}
**使用参考实现**
使用 `SDK/Runtime/Presentation/Views/Transcript/Chat/ChatTranscriptUI.cs` 作为参考。
{% endstep %}
{% step %}
**实现接口**
实现 `MonoBehaviour` + `ITranscriptUI` （以及 `IInjectable` 如果需要服务注入）。
{% endstep %}
{% step %}
**保留必需成员**
保留必需成员：
* `标识符`
* `IsActive`
* `DisplayMessage(TranscriptViewModel viewModel)`
* `CompleteMessage(string messageId)`
* `ClearAll()`
* `SetActive(bool active)`
* `CompletePlayerTurn()`
{% endstep %}
{% step %}
**如有需要，注入服务**
如有需要，请通过以下方式注入服务： `InjectServices(IServiceContainer container)`:
* `IConvaiCharacterLocatorService`
* `IPlayerInputService`
{% endstep %}
{% step %}
**重新连接预制件引用**
重新连接预制件引用（气泡预制件、容器、输入字段、淡出组件），并在注册转录 UI 的位置分配新组件。
{% endstep %}
{% endstepper %}
#### 重要行为说明
* 流式传输期间，进行中的消息通常按说话者作为键。
* `CompleteMessage(messageId)` 完成一个气泡，并将其从当前进行中的映射中移除。
* 文本提交通常通过以下方式流转 `IPlayerInputService`.
* 角色颜色通过以下方式解析 `IConvaiCharacterLocatorService`.
#### 常见陷阱
如果未显示任何转录消息，请检查：
* UI 已激活（`SetActive(true)`).
* `标识符` 是否与控制器设置期望的转录模式匹配（例如， `“聊天”`).
***
### 预构建 UI 预制件
新 SDK 包含可直接使用或按需自定义的预构建 UI 预制件：
* **设置面板预制件**: `Packages/com.convai.convai-sdk-for-unity/Prefabs/SettingsPanel/SettingsPanel_Landscape.prefab`
* **转录聊天预制件**: `Packages/com.convai.convai-sdk-for-unity/Prefabs/TranscriptUI/TranscriptUI_Chat.prefab`
* **通知预制件**: `Packages/com.convai.convai-sdk-for-unity/Prefabs/Notifications/Notification.prefab`
对于从旧版 SDK 文档迁移的团队，此信息以前列在 [Convai UI 预制件](https://docs.convai.com/api-docs/plugins-and-integrations/unity-plugin/utilities/convai-ui-prefabs).
***
### 迁移完成
完成上述步骤后：
* 项目使用最新的 Convai SDK。
* NPC 交互通过 `ConvaiCharacter`.
* 场景默认项通过 `ConvaiDefaults`.
* 转录 UI 遵循新的 `ITranscriptUI` 流程。
如果迁移后遇到问题，请检查：
* 是否缺少脚本引用。
* 自定义脚本中的 API 使用是否已更新。
* 角色对象上的音频源设置。
* 转录 UI 激活和标识符匹配。
---
# 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/additional-feature-migration.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.