> 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/convai-unity-sdk/features/multi-character-sessions/room-session-reference.md).

# 房间会话参考

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

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

***

### `CharacterRoomStatus`

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

| 值     | 数值  | 含义                                                   |
| ----- | --- | ---------------------------------------------------- |
| `启动中` | `0` | 该成员已存在于花名册中，但尚未被报告为就绪或失败。                            |
| `就绪`  | `1` | 该角色已发出信号，表示可以接收输入。                                   |
| `失败`  | `2` | 该角色未能启动。 `CharacterRoomMembership.FailureCode` 包含原因。 |

***

### `CharacterRoomMembership`

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

| 成员                | 类型                      | 说明                                                                                                                                                       |
| ----------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `成员 ID`           | `字符串`                   | 用于定位此实例——将其传递给 `SetInteractionTargetAsync(string, CancellationToken)`, `RemoveCharacterAsync(string, string, CancellationToken)`，或 `FindByMembershipId`. |
| `角色 ID`           | `字符串`                   | 创建此实例时所基于的 Convai 角色定义。在花名册中并不唯一——同一个值可能出现在多个成员上。                                                                                                        |
| `SessionId`       | `字符串`                   | Convai 在连接响应中为此成员返回的会话标识符。                                                                                                                               |
| `角色会话 ID`         | `字符串`                   | 用于跨会话延续此实例的对话，并消歧重复的 `角色 ID` 值。                                                                                                                          |
| `参与者标识`           | `字符串`                   | 将此实例与其传输参与者和音频轨道匹配。请视为不透明值。                                                                                                                              |
| `是否初始`            | `布尔值`                   | `是` 用于 Convai 标记为房间初始角色的那个成员。                                                                                                                            |
| `Provisioning 状态` | `字符串`                   | Convai 为此条目返回的原始 provisioning 字符串。                                                                                                                       |
| `角色`              | `IConvaiCharacterAgent` | 本地 `ConvaiCharacter` 绑定到此成员的，或者 `null` 当花名册中持有场景没有对应组件的成员时。                                                                                              |
| `状态`              | `CharacterRoomStatus`   | 该成员的当前状态。对外只读；SDK 在内部设置它。                                                                                                                                |
| `失败代码`            | `字符串`                   | Convai 报告的失败原因，在 `状态` 是 `失败`. `null` 否则。                                                                                                                 |
| `ParticipantId`   | `字符串`                   | 当该成员的媒体出现时，SDK 绑定到此成员的由传输层分配的参与者。是在绑定之后填充的，而不是在连接时。                                                                                                      |

`CharacterRoomMembership.WaitUntilReadyAsync(CancellationToken cancellationToken = default)` 返回一个 `Task` ，当此特定成员达到 `就绪`时完成，或者在其达到 `失败`时出错。可用于等待次要角色； `MultiCharacterRoomSession.WaitUntilReadyAsync` 只会对 `InitialCharacter`.

{% hint style="info" %}
`ProvisioningStatus == "dispatch_failed"` 会在成员创建的瞬间将其标记为 `失败` ，在任何单独的生命周期消息到达之前。
{% endhint %}

***

### `MultiCharacterRoomSession`

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

#### 属性

| 属性                 | 类型                                       | 说明                                                                      |
| ------------------ | ---------------------------------------- | ----------------------------------------------------------------------- |
| `房间会话 ID`          | `字符串`                                    | 持久化的房间标识符，可与 `MultiCharacterJoinOptions.RoomSessionId` 一起使用，以便稍后加入同一房间。 |
| `当前成员 ID`          | `字符串`                                    | “ `成员 ID` 当前交互目标的 ID；如果未设置目标，则为空字符串。                                    |
| `路由 epoch`         | `整数`                                     | 每当交互目标变化时递增。用于防止乱序确认导致目标更新出错。                                           |
| `花名册 epoch`        | `整数`                                     | 每当花名册变化时递增。用于防止乱序确认导致花名册更新出错。                                           |
| `部分派发`             | `布尔值`                                    | `是` 当 Convai 在连接时未派发所有请求的角色时。会话生命周期内固定不变。                               |
| `角色`               | `IReadOnlyList<CharacterRoomMembership>` | 当前花名册中的每个成员。                                                            |
| `InitialCharacter` | `CharacterRoomMembership`                | Convai 标记为初始的成员，或者在没有任何成员带有该标记时取花名册中的第一个成员。对于有任何成员的房间，绝不会为 `null` null。 |
| `是否就绪`             | `布尔值`                                    | `是` 当 `InitialCharacter.Status` 是 `就绪`。不受其他任何成员状态的影响。                   |

#### 事件

| 事件                         | 签名                                                         | 在……时触发                                                                                                  |
| -------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `CharacterStatusChanged`   | `Action<CharacterRoomMembership>`                          | 某个成员转变为 `就绪` 或 `失败`，或者一个新成员被插入到花名册中时。                                                                   |
| `CharacterAdded`           | `Action<CharacterRoomMembership>`                          | 某个成员被添加到花名册中，来源可以是花名册命令的确认，也可以是未请求的生命周期消息。                                                              |
| `CharacterRemoved`         | `Action<CharacterRoomMembership>`                          | 某个成员从花名册中移除。                                                                                            |
| `InteractionTargetChanged` | `Action<CharacterRoomMembership, CharacterRoomMembership>` | 交互目标发生变化。第一个参数是先前的成员（或 `null`），第二个是当前成员（或 `null`).                                                      |
| `RosterEpochChanged`       | `Action<int>`                                              | 观察到更新的权威花名册 epoch。即使没有匹配的，也可能推进，因此如果你需要这一点，不要仅仅根据添加/移除事件来推断花名册已变化。 `CharacterAdded`/`CharacterRemoved`。 |
| `已退役`                      | `Action`                                                   | 此会话被替换或清空——仅触发一次。应将其视为终止信号，并把处理程序重新附加到新的 `CurrentMultiCharacterSession`.                                |

{% hint style="warning" %}
移除活动成员会先触发 `InteractionTargetChanged` ，其中被移除的成员作为前一个值，而 `null` 作为当前值，然后再触发 `CharacterRemoved`。响应移除的代码可以依赖于目标已被清空。
{% endhint %}

#### 方法

| 方法                                                                   | 返回值                       | 说明                                                                                                                                                                                                                            |
| -------------------------------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WaitUntilReadyAsync(CancellationToken cancellationToken = default)` | `Task`                    | 当 `InitialCharacter` 达到 `就绪`时完成，或者如果 `是否就绪` 已经是 `是`则立即返回。并抛出 `InvalidOperationException` ，其中携带 `初始角色启动失败（<code>）。` 当初始角色达到 `失败`. `<code>` 是 `失败代码`，或 `unknown` 时，且 Convai 未报告任何内容。若连接响应已经将初始角色标记为失败，则该错误可能在第一次 `await` 之前就发生。 |
| `FindByCharacter(IConvaiCharacterAgent character)`                   | `CharacterRoomMembership` | 返回绑定到 `character`，或 `null` 当 `character` 是 `null` 的成员，或者其不是该房间的成员。                                                                                                                                                            |
| `FindByMembershipId(string membershipId)`                            | `CharacterRoomMembership` | 返回具有给定 `成员 ID`，或 `null` 当 `membershipId` 的成员；如果其为空或未找到，则返回空。                                                                                                                                                                  |

***

### `InteractionTargetResult`

`InteractionTargetResult` 是一个由 `SetInteractionTargetAsync` 和 `ClearInteractionTargetAsync`.

| 属性                     | 类型    | 说明                                                                 |
| ---------------------- | ----- | ------------------------------------------------------------------ |
| `命令 ID`                | `字符串` | SDK 为交互目标命令分配的标识符。                                                 |
| `当前成员 ID`              | `字符串` | 规范的 `当前成员 ID` 在此命令应用后的会话上。                                         |
| `PreviousMembershipId` | `字符串` | “ `成员 ID` 在此命令之前处于活动状态的那个。                                         |
| `路由 epoch`             | `整数`  | “ `路由 epoch` 由此命令产生的值。                                             |
| `已变更`                  | `布尔值` | `是` 当此命令的结果确实移动了规范目标时。 `否` 当一个过时的确认被丢弃，因为其路由 epoch 未超过 `路由 epoch`. |

***

### `CharacterRosterUpdateResult`

`CharacterRosterUpdateResult` 是一个由 `AddCharacterAsync` 和 `RemoveCharacterAsync`.

| 属性          | 类型                                       | 说明                         |
| ----------- | ---------------------------------------- | -------------------------- |
| `命令 ID`     | `字符串`                                    | SDK 为花名册命令分配的标识符。          |
| `已添加`       | `IReadOnlyList<CharacterRoomMembership>` | 此命令添加的成员。若命令只移除了成员，则为空。    |
| `已移除`       | `IReadOnlyList<CharacterRoomMembership>` | 此命令移除的成员。若命令只添加了成员，则为空。    |
| `当前成员 ID`   | `字符串`                                    | 规范的 `当前成员 ID` 在此命令应用后的会话上。 |
| `路由 epoch`  | `整数`                                     | “ `路由 epoch` 此命令后的值。       |
| `花名册 epoch` | `整数`                                     | “ `花名册 epoch` 由此命令产生的值。    |

***

### `CharacterRosterUpdateException`

`CharacterRosterUpdateException` 是一个继承自 `InvalidOperationException`的密封类。花名册命令的 `Task` 当 Convai 的确认报告的状态不是 `success` 或 `ok`.

| 成员   | 类型         | 说明                                          |
| ---- | ---------- | ------------------------------------------- |
| `代码` | `字符串`      | 确认中的后端错误代码。如果 Convai 未报告，则为空字符串。            |
| `消息` | `字符串` （继承） | 确认中的后端错误消息，或者 `角色花名册更新失败。` 当 Convai 未报告消息时。 |

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

此异常不同于 `ConvaiOperationException` 连接尝试因客户端花名册验证而抛出的异常——请参见 [连接 API 参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/multi-character-sessions/connection-api-reference.md#exceptions-and-timeouts) 了解该路径。

***

### 相关参考

{% content-ref url="/pages/634a0663b206a73fe4e2113edd3096e48b351d9a" %}
[连接 API 参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/multi-character-sessions/connection-api-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/1de47e20d64086de6ea2148c4871a665eec92182" %}
[多角色会话工作原理](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/multi-character-sessions/how-multi-character-sessions-work.md)
{% endcontent-ref %}

{% content-ref url="/pages/9febe55e8fa6244952665a225b37a964cd41c375" %}
[房间就绪状态](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/multi-character-sessions/readiness-and-partial-dispatch.md)
{% endcontent-ref %}


---

# 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, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/multi-character-sessions/room-session-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.