多角色连接 API 参考

多角色连接操作、其加入与连接选项类型，以及每个操作可能抛出的所有异常的参考。

此页面列出了……的多角色成员 IConvaiRoomConnectionService，以及 MultiCharacterJoinOptions 类型，以及 RoomSessionConnectOptions上的多角色字段，以及每个操作产生的异常和超时。所有类型都在 Convai.Runtime.Room 命名空间中。

---

IConvaiRoomConnectionService — 多角色成员

定义于 SDK/Runtime/Room/IConvaiRoomConnectionService.cs:68-147。通过以下方式访问该服务： ConvaiManager.ActiveManager.TryGetRoomConnectionService(out IConvaiRoomConnectionService roomService).

成员	签名	返回
CurrentMultiCharacterSession	MultiCharacterRoomSession CurrentMultiCharacterSession { get; }	当前房间的规范名册，或 null 对于单角色房间。
JoinMultiCharacterRoomAsync	JoinMultiCharacterRoomAsync(MultiCharacterJoinOptions options, CancellationToken cancellationToken = default)	IConvaiOperation<RoomSession>
SetInteractionTargetAsync	SetInteractionTargetAsync(IConvaiCharacterAgent character, CancellationToken cancellationToken = default)	IConvaiOperation<InteractionTargetResult>
SetInteractionTargetAsync	SetInteractionTargetAsync(string membershipId, CancellationToken cancellationToken = default)	IConvaiOperation<InteractionTargetResult>
ClearInteractionTargetAsync	ClearInteractionTargetAsync(CancellationToken cancellationToken = default)	IConvaiOperation<InteractionTargetResult>
AddCharacterAsync	AddCharacterAsync(IConvaiCharacterAgent character, string characterSessionId = null, CancellationToken cancellationToken = default)	IConvaiOperation<CharacterRosterUpdateResult>
RemoveCharacterAsync	RemoveCharacterAsync(string membershipId, string replacementTargetMembershipId = null, CancellationToken cancellationToken = default)	IConvaiOperation<CharacterRosterUpdateResult>
RemoveCharacterAsync	RemoveCharacterAsync(IConvaiCharacterAgent character, string replacementTargetMembershipId = null, CancellationToken cancellationToken = default)	IConvaiOperation<CharacterRosterUpdateResult>

参见 操作与流类型 了解如何使用 IConvaiOperation<T>。结果和异常类型记录于 多角色房间会话参考.

---

并发门控

ConvaiRoomManager 通过各自的 SemaphoreSlim(1, 1)，定义于 SDK/Runtime/Adapters/Networking/ConvaiRoomManager.Connection.cs:27-28。同一时间最多只有一次名册变更和一次交互目标变更在进行。

门控	保护
_rosterMutationGate	AddCharacterAsync，两个 RemoveCharacterAsync 重载
_interactionTargetMutationGate	两个 SetInteractionTargetAsync 重载， ClearInteractionTargetAsync

同一族中的操作第二次调用会等待第一次完成，而不会并发执行。

---

异常和超时

每个操作都会使其 IConvaiOperation<T> 失败，而不是同步抛出。请在等待的任务上处理异常。

每个操作的通用前置条件

条件	异常	消息
当前没有活动的多角色房间	InvalidOperationException	当前没有活动的多角色房间会话。
命令在等待其门控时，多角色房间发生了变化	InvalidOperationException	此更新在等待期间，多角色房间发生了变化。
房间数据通道尚未就绪	InvalidOperationException	房间数据通道尚未就绪。

JoinMultiCharacterRoomAsync

条件	异常	消息
选项 是 null	ArgumentNullException	—（选项)
Convai 拒绝加入，或底层连接尝试失败	ConvaiOperationException	后端会话错误代码和消息。

JoinMultiCharacterRoomAsync 转换为 选项 到一个 RoomSessionConnectOptions 中，且 JoinExistingMultiCharacterRoom 设为 true，然后调用与 ConnectAsync (ConvaiRoomManager.Connection.cs:58-66）相同的连接路径。它不会发送名册，因此 连接时名册验证 中的名册验证异常不适用于它——但它继承了 ConnectAsync的其他失败模式，包括一个 ConvaiOperationException 用于被拒绝或无法到达的连接。参见 加入现有多角色会话 了解仅针对加入的原因及其修复方法。

SetInteractionTargetAsync

SetInteractionTargetAsync 有两个重载：一个接受一个 IConvaiCharacterAgent，另一个接受一个 membershipId 字符串。两者共享相同的超时和确认失败行为；只有“不是成员”检查因参数而异。

条件	异常	消息
字符重载的 角色 不是当前房间的成员	ArgumentException	该角色不是当前房间的成员。 (角色)
成员 ID 重载的 membershipId 不是当前房间的一部分	ArgumentException	该成员不属于当前房间。 (membershipId)
命令在等待门控时，目标成员已被移除	InvalidOperationException	此更新在等待期间，交互目标已被移除。
10 秒内未收到确认	TimeoutException	等待交互目标确认超时。
Convai 的确认报告了非成功状态	InvalidOperationException	后端消息，或 交互目标更新失败。 当 Convai 未报告任何内容时。

ClearInteractionTargetAsync

ClearInteractionTargetAsync 发送一个空目标，因此“等待期间已移除”检查不适用。它与前面两个 SetInteractionTargetAsync 上述重载共享相同的超时和确认失败行为。

清除交互目标不会中断角色已在播放的音频。它只会阻止新的玩家输入路由到该角色。

AddCharacterAsync

条件	异常	消息
角色 是 null	ArgumentNullException	—（角色)
character.CharacterId 为空	ArgumentException	该角色必须具有角色 ID。 (角色)
本地角色实例已是该房间的成员	ArgumentException	此本地角色实例已是当前房间的成员。添加克隆时请使用另一个实例。 (角色)
命令在等待门控时，添加了相同的本地角色	InvalidOperationException	此名册更新在等待期间，添加了本地角色。
15 秒内未收到确认	TimeoutException	等待角色名册更新确认超时。
Convai 的确认报告了非成功状态	CharacterRosterUpdateException	后端消息，或 角色成员列表更新失败。 当 Convai 未报告任何内容时。参见 多角色房间会话参考.

RemoveCharacterAsync

RemoveCharacterAsync 有两个重载：一个接受一个 membershipId 字符串，另一个接受一个 IConvaiCharacterAgent。两者共享替换目标和门控竞争检查；只有“不是成员”检查因参数而异。

条件	异常	消息
字符重载的 角色 是 null	ArgumentNullException	—（角色)
成员 ID 重载的 membershipId 不是当前房间的一部分	ArgumentException	该成员不属于当前房间。 (membershipId)
字符重载的 角色 不是当前房间的成员	ArgumentException	该角色不是当前房间的成员。 (角色)
replacementTargetMembershipId 不是当前房间的一部分	ArgumentException	替换目标不属于当前房间。 (replacementTargetMembershipId)
replacementTargetMembershipId 等于正在移除的成员	ArgumentException	替换目标不能是正在移除的成员。 (replacementTargetMembershipId)
命令在等待门控时，正在移除的成员已被移除	InvalidOperationException	此名册更新在等待期间，角色成员已被移除。
命令在等待门控时，替换目标已被移除	InvalidOperationException	此名册更新在等待期间，替换目标已被移除。
15 秒内未收到确认	TimeoutException	等待角色名册更新确认超时。
Convai 的确认报告了非成功状态	CharacterRosterUpdateException	后端消息，或 角色成员列表更新失败。 当 Convai 未报告任何内容时。

替换目标必须已经是房间成员，且不能是正在移除的成员。名册绝不会变为空：如果在没有有效替换项的情况下移除当前成员，只会清空目标，而不会删除最后一个成员。

---

连接时名册验证

注册了两个或更多角色的场景会在……期间构建其名册 ConnectAsync，在上述任何操作运行之前。SDK 在 RoomConnectionRuntimeAdapter.ApplyMultiCharacterTopology 中验证该名册并抛出一个 ConvaiOperationException 针对下面的每个条件。相同适配器中的外部处理程序（RoomConnectionRuntimeAdapter.cs:328-341）会捕获连接期间抛出的每个异常，并将其重新包装为一个 ConnectionFailure 并携带 SessionErrorCodes.ConnectionFailed。调用方会看到一个 ConvaiOperationException ，其 原始消息 如下，但其 Code 是 ConnectionFailed — 原始代码（ConnectionBadRequest, ConfigCharacterIdMissing）在调用处不可见。

条件	消息（调用处的代码始终为 ConnectionFailed)
注册了超过 50 个角色	多角色房间最多支持 50 个角色。
空或重复的角色引用	多角色名册包含空引用或重复的角色引用。
没有角色 ID 的角色	多角色房间中的每个角色都需要一个角色 ID。
两个角色解析为相同的角色会话 ID	角色会话 ID 在多角色名册中必须唯一。

此验证仅在连接时构建名册时运行。 JoinMultiCharacterRoomAsync 不会发送名册，因此绝不会抛出这些异常。

---

MultiCharacterJoinOptions

MultiCharacterJoinOptions 是一个可序列化类，传递给 JoinMultiCharacterRoomAsync。定义于 SDK/Runtime/Room/TurnTakingOptions.cs:404-432.

字段	类型	默认值	描述
RoomSessionId	string	null	由创建客户端的连接调用返回的持久房间标识符。使用此项或 SharedSessionKey，不要同时使用两者。
SharedSessionKey	string	null	房间的另一个由开发者控制的定位器。使用此项或 RoomSessionId，不要同时使用两者。
EndUserId	string	null	用于加入玩家的稳定开发者标识符。
EndUserMetadata	IReadOnlyDictionary<string, object>	null	面向最终用户的附加元数据。
TurnTaking	TurnTakingOptions	TurnTakingOptions.CreateHandsFreeDefault()	加入参与者的轮流发言配置。参见 轮流发言模式.

加入时会将这些字段转换为一个 RoomSessionConnectOptions 中，且 JoinExistingMultiCharacterRoom 设为 true 并发送连接模式 join 且不带角色名册。

---

RoomSessionConnectOptions — 多角色字段

RoomSessionConnectOptions 是被 ConnectAsync(RoomSessionConnectOptions, CancellationToken)。定义于 SDK/Runtime/Room/TurnTakingOptions.cs:329-358接受的选项类型。下表仅涵盖与多角色会话相关的字段；请参见 ConvaiManager API 以获取完整字段列表。

字段	类型	默认值	描述
SharedSessionKey	string	null	可选的共享会话密钥，用于将多人参与者分组到同一房间。
RoomSessionId	string	null	用于加入现有房间的持久多角色房间标识符。通过以下方式设置： MultiCharacterJoinOptions 而不是直接设置，供常规使用。
JoinExistingMultiCharacterRoom	布尔值	false	选择无拓扑的人类加入，而不是构建并发送名册。
MaxNumParticipants	int	0	共享会话的可选最大参与者数量。

---

相关参考

多角色房间会话参考多角色会话的工作方式构建你的第一个多角色会话