> 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/multi-character-sample.md).

# 多角色示例

导入多角色示例场景，查看多个 Convai 角色共享同一房间、交互目标选择以及实时文字记录。

该 **多角色示例** 是 Convai Unity SDK 随附的共享房间场景，展示多个角色、交互目标选择、转录 UI，以及在场景运行时进行的名册更改。导入它，可在构建你自己的场景之前先查看一个可工作的多角色房间。

### 前提条件

* Convai Unity SDK <code class="expression">space.vars.unity\_sdk\_version</code> 已安装。
* 已配置的 API 密钥和服务器环境位于 **编辑 > 项目设置 > Convai SDK**.

### 导入该示例

{% stepper %}
{% step %}

#### 导入多角色示例

在 **窗口 > 包管理器**，选择 **适用于 Unity 的 Convai SDK**，打开 **示例** 选项卡，并导入 **多角色示例**。它是自包含的： `Sofia` 它使用的角色随该包一起提供，而不是来自另一个示例，因此无需先导入其他内容。Unity 会将其场景和脚本复制到 `Assets/Samples/Convai SDK for Unity/<version>/Multi-Character Sample/`，其中 `<version>` 是已安装的 SDK 版本（<code class="expression">space.vars.unity\_sdk\_version</code>).
{% endstep %}

{% step %}

#### 分配你自己的角色 ID

打开已导入的场景。在每个 `ConvaiCharacter`中，将示例角色 ID 替换为一个与你已配置的 API 密钥相同 Convai 账号和环境下拥有的角色。参见 [角色身份](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/multi-character-sessions/character-identity.md) ，如果两个角色最终共享了同一个 ID。
{% endstep %}

{% step %}

#### 如果提示，请导入 TextMesh Pro 资源

如果出现提示，请接受 Unity 导入 TextMesh Pro Essential Resources 的请求。
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
多角色房间是 Convai 账号的一项功能。如果你 API 密钥背后的账号没有此功能，房间将拒绝连接，且控制台会说明原因——无需事先检查任何内容。
{% endhint %}

### 场景展示了什么

进入播放模式并看向任意角色即可对其发言——对话会随着摄像机指向的变化而进行，无需任何额外输入，而一旦转向另一个角色，前一个角色的回答就会立刻结束。使用 **WASD**移动，用鼠标查看，并按 **Escape** 释放光标；点击 UI 外部会重新捕获光标。在触摸设备上，两个屏幕虚拟摇杆是在键盘和鼠标基础上的补充，而不是替代它们。

屏幕上的读数会显示你正在对谁说话，以及他们是否已经能听见你。 `准备中` 是房间连接后、服务宣布该角色之前的短暂窗口——在此期间说出的任何内容都不会被任何人听到。

在场景运行时，选择 `GameObject` 持有 **Convai Manager** 并打开其 **实时** 部分：它会显示正在与谁对话、玩家是否可以与他们交谈、上次目标选择决策背后的结果，以及房间中每个角色对应的一行。

### 在播放时更改名册

在房间连接期间出现在场景中的角色会在无需重新连接的情况下加入对话——无需调用任何内容。禁用某个角色不会移除其座位；它将不再可被指定，并会在重新启用的瞬间再次变得可被指定。角色只有在被销毁或从所有权中移除时才会离开房间。

之所以可行，是因为该示例在两个角色处于激活状态时建立连接，从而打开了一个带有名册的房间。以单个角色连接的房间不带名册，之后也无法扩展——在它连接之前，先让你希望在场景中激活的所有角色都就绪。

### 示例如何读取目标选择和可用性

示例脚本中没有任何内容在让多角色对话正常工作——那是 SDK 的职责，无需设置。 `MultiCharacterSampleController` 只通过项目自己的指示器应读取的两个成员来读取结果：

```csharp
ConvaiCharacter addressed = _manager.AddressedCharacter;
ConvaiConversationAvailability availability = _manager.ConversationAvailability;
```

`AddressedCharacter` 表示玩家正在与谁交谈。 `ConversationAvailability` 表示该角色是否已经能听见玩家——应据此决定是否启用聊天输入框或麦克风按钮，而不是依据房间是否已连接。 `MultiCharacterSampleFirstPersonPlayer` 提供场景所需的移动和视角输入，使玩家能够转向某个角色或另一个角色；它是示例的输入支撑代码，不属于 SDK。

### 下一步

{% 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/ec375bce1b67b826c522092ecdd5eb84031bca76" %}
[对话可用性](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/conversation-availability.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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.