> For the complete documentation index, see [llms.txt](https://docs.edgegap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.edgegap.com/zh/docs/tools-and-integrations/eos-voice-chat.md).

# EOS 语音聊天

为 Unreal Engine 游戏中的匹配玩家添加 Epic Online Services 语音聊天，并将 Edgegap 专用服务器作为受信任的语音服务器。

本指南展示了我们的 [虚幻引擎示例项目](https://github.com/edgegap/game-sample-unreal-engine-topdown) 如何通过 [EOS 语音](https://dev.epicgames.com/docs/epic-online-services/multiplayer/voice-and-rtc-interface/voice-interface/voice-overview) 从 Epic Online Services 添加游戏内语音聊天。由 [Edgegap Matchmaker](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong.md) 匹配的玩家可以在语音房间里与队友交谈，而你在 Edgegap 上的专用服务器决定谁加入哪个房间。

语音聊天 **默认处于禁用状态** 在示例中。在你启用它之前，游戏将按以下方式运行： [俯视角示例](https://docs.edgegap.com/zh/docs/sample-projects/unreal-engine/top-down-sample.md).

{% hint style="success" %}
**我们建议先从** [Unreal Engine](https://docs.edgegap.com/zh/unreal-engine.md) **指南开始，先构建你的游戏服务器，然后再继续。**
{% endhint %}

## 🎙️ 工作原理

你的专用服务器是 EOS 的 [受信任服务器](https://dev.epicgames.com/docs/epic-online-services/multiplayer/voice-and-rtc-interface/voice-interface/voice-overview#voice-with-a-trusted-server-application)。游戏客户端从不持有可以创建语音房间的凭据。

### 1. 玩家登录 EOS

游戏客户端使用设备 ID 将玩家登录到 EOS，因此玩家不需要 Epic 账号。然后它将该玩家的 Product User ID 以及 EOS ID 令牌发送给服务器。

### 2. 服务器检查玩家

服务器使用 Epic 的公钥验证 ID 令牌，因此玩家无法冒充他人的 ID。它还会检查该令牌是否是为你的 EOS 部署签发的。

### 3. 服务器选择房间

房间名称来自对局：

* 基础房间以匹配器的对局 ID 命名（`MM_MATCH_ID`），或者以你手动部署的服务器的部署 ID 命名，
* 启用队伍房间时（默认， `bTeamRooms=True`），每个队伍都会获得自己的房间，名称由对局和队伍决定。

服务器从 [作为环境变量注入的匹配器票据](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong/matchmaker-in-depth.md#injected-variables) 中找到每个玩家的队伍——它会将玩家连接来源的 IP 与每张票据上的 IP 进行匹配，并读取票据中的队伍信息。 **它从不信任客户端发送的队伍信息。** 没有匹配票据的玩家（例如通过 IP 连接的玩家）会留在对局房间中。设置 `bTeamRooms=False` 即可让整个对局处于同一个房间。

### 4. 服务器发放房间令牌

服务器向 [EOS Voice Web API](https://dev.epicgames.com/docs/web-api-ref/voice-web-api) 请求该玩家的房间令牌，并传入玩家的 IP，以便 EOS 使用离他们更近的语音服务器。服务器只把令牌发送给该玩家，客户端使用引擎的 EOSVoiceChat 插件加入房间。

### 5. 服务器移除离开的玩家

当玩家离开服务器时，服务器会将其从语音房间中移除，这也会吊销其令牌。游戏代码还可以通过以下方式将玩家对所有人静音： `UEdgegapVoiceServerSubsystem::SetHardMuted`.

{% hint style="info" %}
你的游戏模式和玩家控制器无需更改。当玩家登录（`PostLogin`）时，服务器会向其玩家控制器添加一个很小的复制组件， `UEdgegapVoiceComponent`，它只会复制到其拥有者客户端，并携带 `ServerRegisterVoice` 和 `ClientJoinVoiceRoom` RPC。
{% endhint %}

服务器通过 HTTPS 调用 EOS Web API，而不是 EOS SDK，因为 EOS SDK 不支持 Linux 上的语音。客户端侧则面向 Windows 和 Mac 构建，因为那里有 EOSVoiceChat 插件。

| 文件                            | 作用                                      |
| ----------------------------- | --------------------------------------- |
| `EdgegapVoiceSettings.h`      | 开关和选项，来自 `DefaultGame.ini`              |
| `EdgegapVoiceClientSubsystem` | EOS 设备 ID 登录、ID 令牌、加入和离开房间              |
| `EdgegapVoiceComponent`       | 由服务器添加到每个玩家，承载语音 RPC                    |
| `EdgegapVoiceServerSubsystem` | ID 令牌检查、房间选择、EOS Voice Web API 调用、注销时移除 |

## ⚙️ 设置

### 1. 创建 EOS 客户端

☑️ 在 [Epic Developer Portal](https://dev.epicgames.com/portal)中打开你的产品，然后 **产品设置**.

☑️ 在标签页 **SDK Download & Credentials**.

☑️ 在标签页中添加两个策略 **客户端**下的 **客户端策略**:

* **游戏客户端** - 类型 `GameClient`, **需要用户** 已勾选，不需要 Voice 权限，
* **受信任服务器** - **创建自定义策略**, **需要用户** 未勾选，带有 Voice 操作 `createRoomToken`, `kick` 和 `mute`.

☑️ 为每个策略添加一个客户端，并记下每个 Client ID 和 Client Secret。

{% hint style="danger" %}
你的受信任服务器客户端可以为你的部署中的任何房间创建令牌。 **切勿将其放入游戏构建中。**
{% endhint %}

✅ 现在可以继续下一步。

### 2. 配置游戏客户端

☑️ 填写 `[EOSVoiceChat]` 在 `MultiplayerGame/Config/UserEngine.ini` 中的产品、沙盒和部署 ID，以及你的 **游戏客户端的** ID 和密钥。该文件会被 git 忽略，并覆盖 `DefaultEngine.ini`，因此你的凭据不会进入版本控制。

☑️ 在 `MultiplayerGame/Config/UserGame.ini` 中启用语音（同样被 git 忽略）：

{% code collapsedlinecount="10" %}

```ini
[/Script/MultiplayerGame.EdgegapVoiceSettings]
bEnabled=True
```

{% endcode %}

✅ 现在可以继续下一步。

### 3. 配置服务器

☑️ 将这些环境变量添加到你的 [应用版本](https://app.edgegap.com/application-management/applications/list)中，并将密钥标记为隐藏：

| 变量                         | 值                                             |
| -------------------------- | --------------------------------------------- |
| `EOS_VOICE_CLIENT_ID`      | 受信任服务器 Client ID                              |
| `EOS_VOICE_CLIENT_SECRET`  | 受信任服务器 Client Secret                          |
| `EOS_VOICE_DEPLOYMENT_ID`  | EOS 部署 ID（如果它已经在其中则可选 `DefaultEngine.ini`)    |
| `EOS_VOICE_GAME_CLIENT_ID` | 游戏客户端的 Client ID，可选：服务器随后只接受为你的游戏客户端签发的 ID 令牌 |

这些设置完成后，你的服务器就已启用语音，因此你无需重新构建服务器镜像。对于本地运行的服务器，请将 `ServerClientId` 和 `ServerClientSecret` 在 `EdgegapVoiceSettings` 部分放在 `UserGame.ini` 中。

✅ 现在可以继续下一步。

### 4. 游玩

☑️ 重新打包你的服务器和客户端，部署并开始游玩。启用匹配器后，队友会共享一个房间。

☑️ 在控制台输入 `VoiceMute` 来将你的麦克风静音或取消静音。

🙌 恭喜，你的玩家现在可以与队友交谈了！

## 🧪 在一台 PC 上使用两个客户端进行测试

设备 ID 归 Windows 用户所有，因此同一台 PC 上的两个客户端会以同一个 EOS 玩家身份登录。添加 `-EOSVoiceNewDeviceId` 到第二个客户端的命令行，为其赋予新的身份。

{% hint style="warning" %}
`-EOSVoiceNewDeviceId` 每次启动都会创建一个新的 EOS 用户， **仅用于测试**。请等第一个客户端登录后再启动第二个客户端 `语音：已登录到 EOS` ——如果在第一个客户端仍在登录时更换设备 ID，两个客户端会获得相同的身份。
{% endhint %}

要在不对着麦克风说话的情况下检查音频是否流动，请使用以下方式启动客户端： `-ExecCmds="EOSVoiceChat.FakeAudioInputEnabled 1"` （开发版本）。它会发送测试信号，另一个客户端会记录 `语音：<id> 在房间 <room> 中开始说话`.

使用匹配器时，两个客户端必须在 10 秒内排队，否则 `休闲` 配置文件会开始单人对局。客户端启动速度不同，因此请使用相同的 `-FindMatchAt=<unix time>` （例如提前两分钟）同时启动它们，而不是使用 `-FindMatch` ——每个客户端都在那个时刻入队。

{% hint style="info" %}
需要查找的日志行（`LogEdgegapVoice`):

* 服务器 - `语音：受信任语音服务器已就绪`中打开你的产品，然后 `语音：<id> 获得房间 <room>` 针对每个玩家，以及 `语音：已移除 <id>` 当玩家离开时，
* 客户端 - `语音：已作为 <id> 登录到 EOS`, `语音：已加入房间 <room>`，以及 `语音：<id> 开始说话`.
  {% endhint %}
