> ## Documentation Index
> Fetch the complete documentation index at: https://docs.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://docs.xbox.com/zh-TW/build/console-features/networking/game-mesh/playfab-party-intro-networking.md)。
如需 API 特定參考的詳細資訊，請參閱 [API 內容 (Game Chat 2)](https://docs.xbox.com/zh-TW/reference/chat/gamechat2/gamechat2_members.md)。

> [!NOTE]
>
> Game Chat 2 和 PlayFab Party API 使用相同的內部平台功能，無法在遊戲中平行使用。

Game Chat 2 提供下表所示的功能，用於管理遊戲的通訊。

| 功能 | 描述 |
| - | - |
| 通訊關係 | 對使用者之間的通訊方式提供精細的控制。Game Chat 2 不指定小組或頻道，而是要求定義每對使用者之間的明確關係。Game Chat 2 通訊關係支援任何一對使用者之間的單向和雙向通訊。語音和文字通訊關係可以彼此獨立設定。 |
| 協助工具 | 遵守使用者的「遊戲聊天轉譯」偏好設定，並執行轉換，分別建立代表傳入語音音訊的聊天文字訊息，以及為傳出的聊天文字訊息播放合成語音音訊。 |
| XBOX 服務整合 | 使用 XBOX 服務確保每位使用者的偏好設定和權限都受到尊重。 |
| 語音活動偵測 | 執行語音活動偵測，以判斷音訊資料何時包含語音活動。 |
| 自動增益控制 | 執行自動增益控制，以將使用者麥克風輸出的變化降到最低。 |
| 轉碼器 | 對傳遞至應用程式遠端執行個體的音訊資料進行編碼。在 XBOX One 上，此編碼 (以及接收端的解碼) 是硬體加速的。 |
| `chat_manager::start`/`finish_processing_state_changes` | 應用程式在每個 UI 畫面呼叫的一對方法，用於執行非同步作業以擷取以 [game\_chat\_state\_change](https://docs.xbox.com/zh-TW/reference/chat/gamechat2/structs/game_chat_state_change.md) 結構形式處理的結果。完成時會釋放相關聯的資源。 |
| `chat_manager::start`/`finish_processing_data_frames` | 用於將 Game Chat 2 新增至應用程式傳輸層的一對方法。應用程式會在每個網路畫面呼叫這些方法，以擷取 [game\_chat\_data\_frame](https://docs.xbox.com/zh-TW/reference/chat/gamechat2/structs/game_chat_data_frame.md) 物件並將其散發至遠端裝置上的應用程式執行個體，然後在完成時釋放相關聯的資源。 |
| `chat_manager::process_incoming_data` | 用於將透過應用程式傳輸層從 Game Chat 2 遠端執行個體傳遞的資料提供給 Game Chat 2 的方法。 |
| 即時音訊操作 | 將應用程式插入聊天音訊管線中，以檢查或操作聊天音訊資料。如需詳細資訊，請參閱[即時音訊操作](https://docs.xbox.com/zh-TW/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://docs.xbox.com/zh-TW/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://docs.xbox.com/zh-TW/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 變更

為了支援 Game Chat 2，對 API 進行了下列變更。

* `game_chat_audio_encoding_type_and_bitrate` 已更新為 [game\_chat\_audio\_encoding\_bitrate](https://docs.xbox.com/zh-TW/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://docs.xbox.com/zh-TW/reference/chat/gamechat2/classes/chat_manager/methods/chat_manager_set_legacy_era_uwp_compat_mode_enabled.md) API，以便與 UWP 和 ERA 版本的 Game Chat 2 交互操作。

> [!NOTE]
>
> * 只有在 [XGameRuntimeIsFeatureAvailable](https://docs.xbox.com/zh-TW/reference/system/xgameruntimefeature/functions/xgameruntimeisfeatureavailable.md) 指出 `XGameRuntimeFeature::XNetworking` 功能可用時，才能使用 Game Chat 2。
> * 使用者會先透過 [XUserAddAsync](https://docs.xbox.com/zh-TW/reference/system/xuser/functions/xuseraddasync.md) 新增至 Microsoft Game Development Kit，然後才新增至 Game Chat 2 執行個體。
> * 音訊焦點偵測支援將在 GDK 的未來預覽版中提供。

## 從 UWP 和 ERA 到 GDK 的功能變更

* 在遊戲啟動時以及繼續遊戲之後，請先等待[網路初始化](https://docs.xbox.com/zh-TW/build/console-features/networking/initialization-connectivity-networking.md)，然後再代表 Game Chat 2 傳送封包。Game Chat 2 會在網路初始化之前初始化。
* 透過 `RegisterAppStateChangeNotification` 註冊暫停和繼續事件。暫停之後，使用 [chat\_manager::cleanup()](https://docs.xbox.com/zh-TW/reference/chat/gamechat2/classes/chat_manager/methods/chat_manager_cleanup.md) 清除 Game Chat 2。繼續之後，重新初始化 Game Chat 2。如果您在暫停/繼續週期中使用它，它可能會當機。

## 參考 API 文件

* [Gamechat2 (API 內容)](https://docs.xbox.com/zh-TW/reference/chat/gamechat2/gamechat2_members.md)
  * 結構
    * [game\_chat\_state\_change](https://docs.xbox.com/zh-TW/reference/chat/gamechat2/structs/game_chat_state_change.md)
    * [game\_chat\_data\_frame](https://docs.xbox.com/zh-TW/reference/chat/gamechat2/structs/game_chat_data_frame.md)
* [xgameruntimefeature (API 內容)](https://docs.xbox.com/zh-TW/reference/system/xgameruntimefeature/xgameruntimefeature_members.md)
  * 函式
    * [XGameRuntimeIsFeatureAvailable](https://docs.xbox.com/zh-TW/reference/system/xgameruntimefeature/functions/xgameruntimeisfeatureavailable.md)
* [xuser (API 內容)](https://docs.xbox.com/zh-TW/reference/system/xuser/xuser_members.md)
  * 函式
    * [XUserAddAsync](https://docs.xbox.com/zh-TW/reference/system/xuser/functions/xuseraddasync.md)

## 另請參閱

[API 內容 (GameChat2)](https://docs.xbox.com/zh-TW/reference/chat/gamechat2/gamechat2_members.md)

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

[即時音訊操作](https://docs.xbox.com/zh-TW/services/xbox-services/multiplayer/chat/game-chat2/real-time-audio-manipulation.md)

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


## Related topics

- [chat_user](https://docs.xbox.com/zh-TW/reference/chat/gamechat2/classes/chat_user/chat_user.md)
- [game_chat_user_chat_indicator](https://docs.xbox.com/zh-TW/reference/chat/gamechat2/enums/game_chat_user_chat_indicator.md)
- [game_chat_data_frame](https://docs.xbox.com/zh-TW/reference/chat/gamechat2/structs/game_chat_data_frame.md)
- [game_chat_state_change](https://docs.xbox.com/zh-TW/reference/chat/gamechat2/structs/game_chat_state_change.md)
- [game_chat_sample_type](https://docs.xbox.com/zh-TW/reference/chat/gamechat2/enums/game_chat_sample_type.md)