多角色房间会话参考

多角色房间会话类型、其成员和状态字段，以及其命令返回的结果和异常的参考。

MultiCharacterRoomSession 是多角色房间成员列表在客户端的投影。本页列出你可读取或调用的每一个公共成员 MultiCharacterRoomSession, CharacterRoomMembership, CharacterRoomStatus, InteractionTargetResult, CharacterRosterUpdateResult，以及 CharacterRosterUpdateException。SDK 自行构造这三种结果类型和异常类型，因此省略了它们的构造函数。这六种类型都位于 Convai.Runtime.Room 命名空间中，定义于 SDK/Runtime/Room/MultiCharacterRoomSession.cs.

---

CharacterRoomStatus

CharacterRoomStatus 是一个包含三个值的枚举，位于 CharacterRoomMembership.Status.

值	数值	含义
Starting	0	该成员身份已存在于成员列表中，但尚未被报告为就绪或失败。
Ready	1	角色已发出可以接收输入的信号。
Failed	2	角色未启动。 CharacterRoomMembership.FailureCode 包含原因。

---

CharacterRoomMembership

CharacterRoomMembership 是一个密封类，将一个后端成员身份绑定到一个本地角色实例。下面的每个字段都是 SDK 外部可见的公共只读属性。

成员	类型	描述
MembershipId	字符串	用于定位此实例——将其传递给 SetInteractionTargetAsync(string, CancellationToken), RemoveCharacterAsync(string, string, CancellationToken)，或者 FindByMembershipId.
CharacterId	字符串	创建此实例所依据的 Convai 角色定义。在成员列表中并不唯一——同一个值可能出现在多个成员身份上。
SessionId	字符串	Convai 在连接响应中为此成员身份返回的会话标识符。
CharacterSessionId	字符串	用于跨会话继续此实例的对话，并区分重复的 CharacterId 值。
ParticipantIdentity	字符串	将此实例与其传输参与者和音轨匹配。请将其视为不透明值。
IsInitial	布尔值	true ，适用于 Convai 标记为房间初始角色的那个成员身份。
ProvisioningStatus	字符串	Convai 为此条目返回的原始配置字符串。
角色	IConvaiCharacterAgent	本地 ConvaiCharacter 绑定到此成员身份的，或者 null 当成员列表中包含场景没有对应组件的成员身份时。
状态	CharacterRoomStatus	该成员身份的当前状态。对外为只读；SDK 在内部设置它。
FailureCode	字符串	Convai 报告的失败原因，在 状态 为 Failed. null 时设置，否则为。
ParticipantId	字符串	当其媒体出现时，SDK 为此成员身份绑定的传输分配的参与者。是在绑定之后填充，而非连接时。

ProvisioningStatus == "dispatch_failed" 将一个成员身份标记为 Failed 在它被创建的那一刻，早于任何单独的生命周期消息到达。

---

MultiCharacterRoomSession

MultiCharacterRoomSession 是一个密封类。SDK 在内部创建并更新其实例；请通过 IConvaiRoomConnectionService.CurrentMultiCharacterSession.

属性

属性	类型	描述
RoomSessionId	字符串	持久化的房间标识符，可与 MultiCharacterJoinOptions.RoomSessionId 一起使用，以便稍后加入同一个房间。
ActiveMembershipId	字符串	当前交互目标的 MembershipId 标识符，或者在未设置目标时为空字符串。
RouteEpoch	整数	每当交互目标发生变化时递增。用于防止因确认乱序而错误更新目标。
RosterEpoch	整数	每当成员列表发生变化时递增。用于防止因确认乱序而错误更新成员列表。
PartialDispatch	布尔值	true 当 Convai 在连接时未派发所有请求的角色时固定存在。会在整个会话生命周期内保持不变。
Characters	IReadOnlyList<CharacterRoomMembership>	当前位于成员列表中的每个成员身份。
InitialCharacter	CharacterRoomMembership	Convai 标记为初始的成员身份，若没有成员身份带有该标记，则取成员列表中的第一个成员身份。对于含有任何成员的房间，绝不会为 null 。
IsReady	布尔值	true 当 InitialCharacter.Status 为 Ready为时。不会受其他任何成员身份状态的影响。

事件

事件	签名	在以下情况触发
CharacterStatusChanged	Action<CharacterRoomMembership>	一个成员身份转变为 Ready 或 Failed，或者一个新的成员身份被插入到成员列表中。
CharacterAdded	Action<CharacterRoomMembership>	通过成员列表命令的确认或未请求的生命周期消息，将一个成员身份添加到成员列表中。
CharacterRemoved	Action<CharacterRoomMembership>	一个成员身份从成员列表中被移除。
InteractionTargetChanged	Action<CharacterRoomMembership, CharacterRoomMembership>	交互目标发生变化。第一个参数是先前的成员身份（或 null），第二个参数是当前成员身份（或 null).

移除活动成员身份时会先触发 InteractionTargetChanged ，其中被移除的成员身份作为前一个值，而 null 作为当前值，然后触发 CharacterRemoved。响应移除的代码可以依赖于目标已被清除。

方法

方法	返回值	描述
WaitUntilReadyAsync(CancellationToken cancellationToken = default)	Task	当以下情况时完成 InitialCharacter 达到 Ready，或者如果 IsReady 已经 true。若出现以下情况则失败 InvalidOperationException 并携带 初始角色启动失败（<code>）。 当初始角色达到 Failed. <code> 为 FailureCode，或者 未知 当 Convai 未报告任何内容时。该失败可在第一次 await 之前发生，如果连接响应已经将初始角色标记为失败。
FindByCharacter(IConvaiCharacterAgent character)	CharacterRoomMembership	返回绑定到 角色，或者 null 当 角色 为 null 的成员身份，或者该角色不是房间成员。
FindByMembershipId(string membershipId)	CharacterRoomMembership	返回具有给定 MembershipId，或者 null 当 membershipId 的成员身份；如果其为空或未找到，则返回。

---

InteractionTargetResult

InteractionTargetResult 是一个由 SetInteractionTargetAsync 和 ClearInteractionTargetAsync.

属性	类型	描述
CommandId	字符串	SDK 为交互目标命令分配的标识符。
ActiveMembershipId	字符串	此命令应用后会话中的规范 ActiveMembershipId 。
PreviousMembershipId	字符串	当前交互目标的 MembershipId 在此命令之前处于活动状态的。
RouteEpoch	整数	当前交互目标的 RouteEpoch 由此命令产生的值。
已更改	布尔值	true 当此命令的结果实际移动了规范目标时触发。 false 当某个过期的确认被丢弃，因为其路由纪元未超过 RouteEpoch.

---

CharacterRosterUpdateResult

CharacterRosterUpdateResult 是一个由 AddCharacterAsync 和 RemoveCharacterAsync.

属性	类型	描述
CommandId	字符串	SDK 为成员列表命令分配的标识符。
已添加	IReadOnlyList<CharacterRoomMembership>	由此命令添加的成员身份。当该命令只移除了成员身份时为空。
已移除	IReadOnlyList<CharacterRoomMembership>	由此命令移除的成员身份。当该命令只添加了成员身份时为空。
ActiveMembershipId	字符串	此命令应用后会话中的规范 ActiveMembershipId 。
RouteEpoch	整数	当前交互目标的 RouteEpoch 在此命令之后的值。
RosterEpoch	整数	当前交互目标的 RosterEpoch 由此命令产生的值。

---

CharacterRosterUpdateException

CharacterRosterUpdateException 是一个派生自 InvalidOperationException的密封类。成员列表命令的 Task 在 Convai 的确认报告状态不是 success 或 ok.

成员	类型	描述
Code	字符串	确认中的后端错误代码。如果 Convai 未报告，则为空字符串。
Message	字符串 （继承）	确认中的后端错误消息，或者 角色成员列表更新失败。 当 Convai 未报告消息时。

SDK 测试确认为恰好两个 Code 值： roster_epoch_mismatch 和 unauthorized_sender。后端可能还存在其他代码；不要假设该集合仅限于这两个。

此异常不同于 ConvaiOperationException 连接尝试因客户端成员列表验证而抛出的异常——请参见 多角色连接 API 参考 了解该路径。

---

相关参考

多角色连接 API 参考多角色会话的工作方式名册就绪与部分调度