附加功能迁移

附加功能迁移

LTM（会话恢复）

无需进行 API 迁移。请根据需要在您的设置中继续启用/禁用会话恢复。

动态信息： DynamicInfoController -> ConvaiRoomManager

动态信息 API 现在通过以下组件路由： ConvaiRoomManager.

// 旧版
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 + 模块化叙事组件）。 旧版设置参考： 将叙事设计添加到您的角色中.

叙事快速映射

• ConvaiNPC （旧版角色组件） -> ConvaiCharacter
• 叙事设计管理器 （旧版设置） -> Convai 叙事设计管理器 (ConvaiNarrativeDesignManager)
• 叙事设计触发器 （旧版设置） -> Convai 叙事设计触发器 (ConvaiNarrativeDesignTrigger)
• InvokeSelectedTrigger(message) -> SetTriggerMessage(message) + InvokeTrigger()
• 角色上仍可通过以下方式直接调用触发器： SendTrigger(triggerName, message)

叙事最小迁移步骤

1

替换旧版 NPC 组件引用

将旧版 NPC 组件引用替换为 ConvaiCharacter.

2

将 Convai 叙事设计管理器添加到角色

添加 Convai 叙事设计管理器 到角色对象中（或在管理器中分配该角色）。

3

与后端同步

单击 与后端同步 在管理器检查器中，以获取该角色的章节。

4

重新绑定章节事件

重新绑定章节事件（章节开始时, 章节结束时）在管理器中。

5

将叙事设计触发器添加到触发对象

添加 Convai 叙事设计触发器 到触发对象，并分配相同的 ConvaiCharacter.

6

获取触发器并配置激活

单击 获取 在触发器检查器中，选择一个触发器，并配置激活模式（碰撞/接近/手动/基于时间）。

脚本迁移示例（触发器调用）

// 旧版
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)

最小迁移步骤

1

创建一个新脚本

创建一个新脚本（例如， MyGameTranscriptUI.cs).

2

使用参考实现

使用 SDK/Runtime/Presentation/Views/Transcript/Chat/ChatTranscriptUI.cs 作为参考。

3

实现接口

实现 MonoBehaviour + ITranscriptUI （以及 IInjectable 如果需要服务注入）。

4

保留必需成员

保留必需成员：

• 标识符
• IsActive
• DisplayMessage(TranscriptViewModel viewModel)
• CompleteMessage(string messageId)
• ClearAll()
• SetActive(bool active)
• CompletePlayerTurn()

5

如有需要，注入服务

如有需要，请通过以下方式注入服务： InjectServices(IServiceContainer container):

• IConvaiCharacterLocatorService
• IPlayerInputService

6

重新连接预制件引用

重新连接预制件引用（气泡预制件、容器、输入字段、淡出组件），并在注册转录 UI 的位置分配新组件。

重要行为说明

• 流式传输期间，进行中的消息通常按说话者作为键。
• 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 预制件.

---

迁移完成

完成上述步骤后：

• 项目使用最新的 Convai SDK。
• NPC 交互通过 ConvaiCharacter.
• 场景默认项通过 ConvaiDefaults.
• 转录 UI 遵循新的 ITranscriptUI 流程。

如果迁移后遇到问题，请检查：

• 是否缺少脚本引用。
• 自定义脚本中的 API 使用是否已更新。
• 角色对象上的音频源设置。
• 转录 UI 激活和标识符匹配。