> 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 space.vars.unity\_sdk\_version 已安装。
* 在以下位置配置好的 API 密钥和服务器环境： **Edit > Project Settings > Convai SDK**.
### 导入示例
{% stepper %}
{% step %}
#### 导入多角色示例
在 **窗口 > 包管理器**，选择 **适用于 Unity 的 Convai SDK**，打开 **Samples** 选项卡，然后导入 **多角色示例**。它是自包含的：其中使用的 `Sofia` 角色随该包一并提供，而不是来自另一个示例，因此无需先导入其他内容。Unity 会将其场景和脚本复制到 `Assets/Samples/Convai SDK for Unity//Multi-Character Sample/`，其中 `` 是已安装的 SDK 版本（space.vars.unity\_sdk\_version).
{% 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 密钥背后的账号未开通该功能，房间会拒绝连接，Console 会说明原因——无需提前检查任何内容。
{% endhint %}
### 场景展示了什么
进入 Play 模式并注视任意角色即可与其对话——除了摄像机指向位置外无需任何输入，且一旦切换到其他角色，上一位角色的回答会立即结束。使用 **WASD**，用鼠标查看，并按 **Escape** 来释放光标；点击 UI 外部会重新捕获光标。在触屏设备上，两个屏幕虚拟摇杆是对键盘和鼠标的补充，而不是替代。
屏幕上的读数会显示你正在与谁交谈，以及他们是否已经能听到你。 `Preparing` 是房间连接之后、服务尚未宣布该角色之前的短暂窗口——在此期间说的任何话都不会被任何人听到。
在场景运行时，选择 `游戏对象` 持有 **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 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/multi-character-sample.md?ask=&goal=
```
`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.