> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Game Chat 2 简介

> 使用 Game Chat 2 为 XBOX GDK 游戏添加语音和文本聊天,尊重玩家隐私与无障碍设置,并满足 XBOX 主机通信要求。

使用 Game Chat 2 可在遵循用户隐私设置的前提下,为您的应用添加语音和文本聊天通信,同时满足与语音和文本聊天相关的 XBOX 主机 GDK 游戏要求。Game Chat 2 依赖您的 GDK 游戏提供网络传输。如果您需要同时包含聊天音频和传输的一体化解决方案,请考虑 [Microsoft Azure PlayFab Party](https://devdocs.xbox.com/zh-CN/build/console-features/networking/game-mesh/playfab-party-intro-networking.md)。
有关 API 相关的参考资料,请参见 [API 内容 (Game Chat 2)](https://devdocs.xbox.com/zh-CN/reference/chat/gamechat2/gamechat2_members.md)。

> [!NOTE]
>
> Game Chat 2 和 PlayFab Party API 使用相同的内部平台功能,不能在同一游戏中并行使用。

Game Chat 2 提供下表所示的功能,用于管理游戏的通信。

| 功能 | 说明 |
| - | - |
| 通信关系 | 精细控制用户之间的通信方式。Game Chat 2 不指定队伍或频道,而是要求明确定义每对用户之间的关系。Game Chat 2 通信关系支持任意一对用户之间的单向和双向通信。语音和文本通信关系可以相互独立设置。 |
| 无障碍功能 | 尊重用户的 "Game Chat Transcription" 首选项,并执行翻译,以创建代表传入语音音频的聊天文本消息,并为传出的聊天文本消息播放合成的语音音频。 |
| XBOX 服务集成 | 使用 XBOX 服务以确保尊重每位用户的偏好和特权。 |
| 语音活动检测 | 执行语音活动检测,确定音频数据是否包含语音活动。 |
| 自动增益控制 | 执行自动增益控制,最小化用户麦克风输出的变化。 |
| 编解码器 | 对传送到应用远程实例的音频数据进行编码。在 XBOX One 上,此编码(以及接收端的解码)采用硬件加速。 |
| `chat_manager::start`/`finish_processing_state_changes` | 应用在每个 UI 帧调用的一对方法,用于执行异步操作以检索以 [game\_chat\_state\_change](https://devdocs.xbox.com/zh-CN/reference/chat/gamechat2/structs/game_chat_state_change.md) 结构形式处理的结果。完成后释放关联的资源。 |
| `chat_manager::start`/`finish_processing_data_frames` | 用于将 Game Chat 2 添加到应用的传输层的一对方法。应用在每个网络帧调用这些方法以检索并将 [game\_chat\_data\_frame](https://devdocs.xbox.com/zh-CN/reference/chat/gamechat2/structs/game_chat_data_frame.md) 对象分发到远程设备上的应用实例,然后在完成后释放关联资源。 |
| `chat_manager::process_incoming_data` | 用于向 Game Chat 2 提供通过应用传输层从远程 Game Chat 2 实例传送的数据的方法。 |
| 实时音频处理 | 在聊天音频管道中插入应用以检查或处理聊天音频数据。有关详细信息,请参见 [实时音频处理](https://devdocs.xbox.com/zh-CN/services/xbox-services/multiplayer/chat/game-chat2/real-time-audio-manipulation.md)。 |

应用告知库有关本地设备上的用户以及预期一起聊天的远程设备上的用户信息。然后应用配置每个用户之间的关系。

Game Chat 2 从本地用户的麦克风轮询音频,执行自动增益控制和语音活动检测,对数据进行编码,然后通过 `chat_manager::start`/`finish_processing_data_frames` 公开待传输给远程 Game Chat 2 实例的音频数据。

应用将包含在 [game\_chat\_state\_change](https://devdocs.xbox.com/zh-CN/reference/chat/gamechat2/structs/game_chat_state_change.md) 对象中的数据传送到该对象中指定的 Game Chat 2 远程实例。

接收到数据后,应用的远程实例通过 `chat_manager::process_incoming_data` 将数据提交给自己的 Game Chat 2 实例。Game Chat 2 解码传入的数据,然后将其渲染到本地用户的音频设备。

## 通信特权与隐私

Game Chat 2 强制执行 XBOX 服务特权和隐私要求。没有通信特权的用户不会生成音频数据。通过隐私设置被屏蔽的用户不会渲染其音频数据。

## 网络初始化

在初始化 Game Chat 2 库之前,无需等待网络初始化。但是,在创建任何用于发送/接收 Game Chat 2 数据包的套接字之前,必须等待网络初始化。Game Chat 2 在网络初始化之前不会生成任何要发送的数据包。有关网络初始化的详细信息,请参见 [网络初始化与连接](https://devdocs.xbox.com/zh-CN/build/console-features/networking/initialization-connectivity-networking.md#ID4ETA)。

## 挂起/恢复

您应通过 `RegisterAppStateChangeNotification` 注册挂起和恢复事件。在挂起时,您应通过调用 `chat_manager::cleanup()` 清理 Game Chat 2。此调用可能需要几百毫秒才能完成,因此应与其他挂起逻辑并行或异步进行,以避免挂起处理程序超时。`cleanup` 调用无需在挂起处理程序返回之前完成。

在恢复时,一旦 `cleanup` 调用完成,您应调用 `chat_manager::singleton_instance().initialize(...)` 以重新初始化 Game Chat 2。在挂起/恢复状态更改时未能调用 `cleanup` 和 `initialize` 会导致您继续尝试使用 Game Chat 2 时发生游戏崩溃。

## 从通用 Windows 平台 (UWP) 和 XBOX One ERA 到 GDK 的 API 变更

对 API 进行了以下更改以支持 Game Chat 2。

* `game_chat_audio_encoding_type_and_bitrate` 已更新为 [game\_chat\_audio\_encoding\_bitrate](https://devdocs.xbox.com/zh-CN/reference/chat/gamechat2/enums/game_chat_audio_encoding_bitrate.md)。
* `set_audio_encoding_type_and_bitrate` 已更新为 `set_audio_encoding_bitrate`。
* `audio_encoding_type_and_bitrate` 已更新为 `audio_encoding_bitrate`。
* `game_chat_communication_relationship_adjuster::privilege` 已更新以指示可由游戏解决的权限问题。
* 添加了 `game_chat_communication_relationship_adjuster::privilege_check_failed`。
* 允许的 GDK 版本的 Game Chat 2 添加了 [chat\_manager::set\_legacy\_era\_uwp\_compat\_mode\_enabled()](https://devdocs.xbox.com/zh-CN/reference/chat/gamechat2/classes/chat_manager/methods/chat_manager_set_legacy_era_uwp_compat_mode_enabled.md) API,以便与 UWP 和 ERA 版本的 Game Chat 2 互操作。

> [!NOTE]
>
> * Game Chat 2 仅在 [XGameRuntimeIsFeatureAvailable](https://devdocs.xbox.com/zh-CN/reference/system/xgameruntimefeature/functions/xgameruntimeisfeatureavailable.md) 指示 `XGameRuntimeFeature::XNetworking` 功能可用时才可用。
> * 用户在被添加到 Game Chat 2 实例之前需通过 [XUserAddAsync](https://devdocs.xbox.com/zh-CN/reference/system/xuser/functions/xuseraddasync.md) 添加到 Microsoft Game Development Kit。
> * 音频焦点检测支持将在 GDK 的未来预览版中提供。

## 从 UWP 和 ERA 到 GDK 的功能变更

* 在游戏启动时以及恢复游戏后,代表 Game Chat 2 发送数据包前,请等待 [网络初始化](https://devdocs.xbox.com/zh-CN/build/console-features/networking/initialization-connectivity-networking.md)。Game Chat 2 在网络初始化之前进行初始化。
* 通过 `RegisterAppStateChangeNotification` 注册挂起和恢复事件。挂起后,使用 [chat\_manager::cleanup()](https://devdocs.xbox.com/zh-CN/reference/chat/gamechat2/classes/chat_manager/methods/chat_manager_cleanup.md) 清理 Game Chat 2。恢复后,重新初始化 Game Chat 2。如果您在挂起/恢复周期中使用它,可能会崩溃。

## 参考 API 文档

* [Gamechat2 (API 内容)](https://devdocs.xbox.com/zh-CN/reference/chat/gamechat2/gamechat2_members.md)
  * 结构
    * [game\_chat\_state\_change](https://devdocs.xbox.com/zh-CN/reference/chat/gamechat2/structs/game_chat_state_change.md)
    * [game\_chat\_data\_frame](https://devdocs.xbox.com/zh-CN/reference/chat/gamechat2/structs/game_chat_data_frame.md)
* [xgameruntimefeature (API 内容)](https://devdocs.xbox.com/zh-CN/reference/system/xgameruntimefeature/xgameruntimefeature_members.md)
  * 函数
    * [XGameRuntimeIsFeatureAvailable](https://devdocs.xbox.com/zh-CN/reference/system/xgameruntimefeature/functions/xgameruntimeisfeatureavailable.md)
* [xuser (API 内容)](https://devdocs.xbox.com/zh-CN/reference/system/xuser/xuser_members.md)
  * 函数
    * [XUserAddAsync](https://devdocs.xbox.com/zh-CN/reference/system/xuser/functions/xuseraddasync.md)

## 另请参见

[API 内容 (GameChat2)](https://devdocs.xbox.com/zh-CN/reference/chat/gamechat2/gamechat2_members.md)

[使用 Game Chat 2 C++ API](https://devdocs.xbox.com/zh-CN/services/xbox-services/multiplayer/chat/game-chat2/using-game-chat-2.md)

[实时音频处理](https://devdocs.xbox.com/zh-CN/services/xbox-services/multiplayer/chat/game-chat2/real-time-audio-manipulation.md)

[Microsoft Game Development Kit](https://devdocs.xbox.com/zh-CN/services/playfab/sdks/platforms/gdk.md)


## Related topics

- [game_chat_user_chat_indicator](https://devdocs.xbox.com/zh-CN/reference/chat/gamechat2/enums/game_chat_user_chat_indicator.md)
- [game_chat_data_frame](https://devdocs.xbox.com/zh-CN/reference/chat/gamechat2/structs/game_chat_data_frame.md)
- [game_chat_state_change](https://devdocs.xbox.com/zh-CN/reference/chat/gamechat2/structs/game_chat_state_change.md)
- [game_chat_sample_type](https://devdocs.xbox.com/zh-CN/reference/chat/gamechat2/enums/game_chat_sample_type.md)
- [game_chat_thread_id](https://devdocs.xbox.com/zh-CN/reference/chat/gamechat2/enums/game_chat_thread_id.md)