切换交互目标

将玩家输入路由到共享 Unity 房间中的指定角色，并在不打断已在说话的角色的情况下释放目标。

将玩家输入路由到多角色会话中的某个角色，可使用 SetInteractionTargetAsync，并使用 ClearInteractionTargetAsync。当房间连接后，并且你需要更改玩家正在对话的角色时，使用此页面。

先决条件

• 一个已连接的多角色会话。参见 构建你的第一个多角色会话.
• IConvaiRoomConnectionService，通过以下方式检索： ConvaiManager.TryGetRoomConnectionService.
• 当前交互目标的 IConvaiCharacterAgent 你想要对话的角色，或 MembershipId 其 CharacterRoomMembership 来推导 session.Characters.

设置交互目标

调用 SetInteractionTargetAsync(IConvaiCharacterAgent, CancellationToken) 当你持有本地角色实例时，或 SetInteractionTargetAsync(string membershipId, CancellationToken) 当你只有成员 ID 时——例如，没有绑定 角色 因为场景中没有匹配的组件。这两个重载会发送相同的命令，并共享同一个门控，因此同一时间只能有一个目标更改在进行中；第二次调用会等待第一次完成。

如果 TimeoutException 并携带 等待交互目标确认超时。 在 10 秒内没有收到确认，则该命令会失败并抛出一个

Assets/Scripts/InteractionTargetSwitcher.cs

using System;
using Convai.Runtime.Components;
using Convai.Runtime.Room;
using UnityEngine;

public class InteractionTargetSwitcher : MonoBehaviour
{
    public async void SwitchTo(IConvaiRoomConnectionService roomService, ConvaiCharacter character)
    {
        try
        {
            InteractionTargetResult result = await roomService.SetInteractionTargetAsync(character);
            Debug.Log($"[MultiCharacter] Target is now {result.ActiveMembershipId} (route epoch {result.RouteEpoch}).");
        }
        catch (InvalidOperationException error)
        {
            Debug.LogError($"[MultiCharacter] Could not switch target: {error.Message}");
        }
        catch (ArgumentException error)
        {
            Debug.LogError($"[MultiCharacter] {error.Message}");
        }
        catch (TimeoutException error)
        {
            Debug.LogError($"[MultiCharacter] {error.Message}");
        }
    }
}

InteractionTargetResult 报告 SDK 实际应用的内容，而这不一定是你请求的内容。此任务只需要它的三个字段：

字段	包含
ActiveMembershipId	此命令处理后得到的规范目标。
RouteEpoch	此命令产生的路由纪元。
已更改	规范目标是否确实发生了变更。

参见 多角色房间会话参考 完整字段列表，包括 CommandId 和 PreviousMembershipId.

清除交互目标

调用 ClearInteractionTargetAsync 以便不将任何玩家输入路由到任何角色。它与 SetInteractionTargetAsync.

清除目标不会中断已经在说话的角色。 ClearInteractionTargetAsync 只会停止新的输入路由；已经发送中的音频会播放完毕。

try
{
    await roomService.ClearInteractionTargetAsync();
}
catch (InvalidOperationException error)
{
    Debug.LogError($"[MultiCharacter] {error.Message}");
}
catch (TimeoutException error)
{
    Debug.LogError($"[MultiCharacter] {error.Message}");
}

验证交互目标已更改

检查 InteractionTargetResult.Changed 而不是假定一次成功的调用总会移动目标。SDK 会丢弃过期或重复的确认，而不是应用它：路由纪元不严格大于会话当前 RouteEpoch 的确认会被丢弃，而规范 ActiveMembershipId 会保持在原来的位置。 已更改 是 false 在这种情况下，即使调用已完成且未抛出异常。请参阅 多角色会话的工作方式 以了解为何需要该保护。

故障排查

症状	原因	修复方法
InvalidOperationException: 当前没有活动的多角色房间会话。	房间作为单角色房间连接，或者该调用在连接完成之前就运行了。	检查 CurrentMultiCharacterSession 不为 null 在调用之前。
ArgumentException: 该角色不是当前房间的成员。	当前交互目标的 IConvaiCharacterAgent 传给角色重载的内容不在 session.Characters.	请先使用 在运行时添加和移除角色添加该角色，或者在它出现后通过 ID 定位其成员资格。
ArgumentException: 该成员不属于当前房间。	传给字符串重载的成员 ID 与当前任何成员都不匹配。	重新读取 session.Characters 并使用一个 MembershipId 当前在名册中的
InvalidOperationException: 此更新在等待期间，交互目标已被移除。	在此调用处于待处理状态时，另一个命令移除了目标成员。	重新读取 session.Characters 并将目标指向仍然存在的成员。
InvalidOperationException: 此更新在等待期间，多角色房间发生了变化。	在调用进行期间，会话被替换，通常是由于重新连接。	获取 CurrentMultiCharacterSession 在异常后再次获取，并针对新会话重试。
TimeoutException: 等待交互目标确认超时。	10 秒内未收到响应。	阅读 ActiveMembershipId 和 RouteEpoch 在重试之前——Convai 可能已经应用了该更改。

下一步

在运行时添加和移除角色响应名册与目标变化多角色会话的工作方式