> ## 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.

# 多人遊戲管理員概觀

> 多人遊戲管理員概觀，這是可簡化 MPSD 工作階段管理、SmartMatch 配對、邀請和中途加入的高階 XBOX Live API。

本主題說明藉由管理工作階段、配對和遊戲邀請來新增多人遊戲功能的高階 API。此 API 提供以狀態為基礎和以事件為基礎的程式設計模型。

XBOX 服務為在您的遊戲中新增多人遊戲功能提供廣泛的支援，讓您的遊戲可以連接世界各地的 XBOX 成員。
這包括豐富的配對案例、讓玩家加入好友進行中遊戲的能力等等。

直接使用多人遊戲 API 實作 XBOX 服務多人遊戲可能是一項複雜的工作。這需要大量的設計和測試，以確認您遵循最佳做法並符合認證需求。

多人遊戲管理員藉由管理工作階段和配對，並提供以狀態為基礎和以事件為基礎的程式設計模型，讓您可以輕鬆地在遊戲中新增多人遊戲功能。

多人遊戲管理員是一組 API。其設計目的是讓您能輕鬆地為採用對等裝載多人遊戲設計的 XBOX 服務遊戲實作多人遊戲案例。

多人遊戲管理員提供以常見多人遊戲案例為中心的 API，例如與好友一起玩多人遊戲、處理遊戲邀請、處理中途加入、配對等等。

多人遊戲管理員支援多個本機使用者。如果您使用協力廠商配對服務，它也能讓您的遊戲更容易與多人遊戲工作階段目錄 (MPSD) 整合。許多這類案例只需要幾個 API 呼叫即可完成。

## 主要功能

多人遊戲管理員 API 的主要功能如下。

* 簡單的工作階段管理和 XBOX 服務配對
* 以狀態為基礎和以事件為基礎的程式設計模型
* 確保遵循 XBOX 服務最佳做法，同時符合多人遊戲 XR 規範
* 實作 2015 多人遊戲流程圖

多人遊戲管理員 API 設計的重要資訊如下。

* 不支援大型 MPSD 工作階段 (超過 100 位成員)。
* 僅以對等裝載的多人遊戲設計為目標。具有專用伺服器的遊戲應改用[多人遊戲活動服務](/zh-TW/services/xbox-services/multiplayer/mpa/live-mpa-overview)或[多人遊戲服務 API](/zh-TW/services/xbox-services/multiplayer/mpsd/live-mpsd-overview) 以及[服務對服務呼叫 (NDA 主題)](/zh-TW/services/xbox-services/fundamentals/s2s-auth-calls/s2s-calls/live-title-service-calls-xbox-live)。

<Info>若要通過認證，您的遊戲仍必須實作線上多人遊戲的必要事件。</Info>

## 概觀

多人遊戲管理員以下列主要概念為中心。

* **大廳工作階段：** 持續性工作階段，用於管理裝置上的本機使用者，以及想要一起玩的受邀好友。

  該群組可以一起玩遊戲，例如多個回合、地圖和關卡。大廳工作階段會追蹤這個核心好友群組 (包括裝置上的本機玩家)。
  通常，這個群組是在主機瀏覽功能表，並與群組成員聊天以決定要玩哪種遊戲模式時形成的。

* **遊戲工作階段：** 追蹤正在玩特定遊戲執行個體的玩家。

  例如，一場競賽、一張地圖或一個關卡。
  您可以透過 [XblMultiplayerManagerJoinGameFromLobby](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoingamefromlobby) 建立包含大廳工作階段成員的新遊戲工作階段。

  當成員接受邀請時，他們會被新增至大廳和遊戲工作階段 (如果有空間的話)。

  如果啟用配對，可以將其他玩家新增至遊戲工作階段，但這些其他玩家不會被新增至大廳工作階段。
  這表示當遊戲結束時，大廳工作階段中的玩家仍在一起，而透過配對加入的額外玩家則不會。

* [XblMultiplayerManagerMember](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/structs/xblmultiplayermanagermember)：代表在本機或遠端裝置上登入的個別使用者。

* [XblMultiplayerManagerDoWork](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork)：確保在遊戲與 XBOX 服務多人遊戲服務之間維持適當的遊戲狀態更新。

  為了確保最佳效能，必須經常呼叫 [XblMultiplayerManagerDoWork](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork)，例如每個畫面格一次。

  [XblMultiplayerManagerDoWork](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork) 會提供 [XblMultiplayerEvent](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/structs/xblmultiplayerevent) 回呼事件陣列，供遊戲處理。

## 狀態機器

必須呼叫 [XblMultiplayerManagerDoWork](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork)，才能確保您的狀態保持最新。
為了讓多人遊戲管理員執行其工作，您必須定期呼叫 [XblMultiplayerManagerDoWork](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork) 方法。
最可靠的做法是每個畫面格至少呼叫一次。

[XblMultiplayerManagerDoWork](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork) 在沒有工作要做時會快速傳回，因此不必擔心呼叫得太頻繁。

### 執行緒

多人遊戲管理員 API 傳回的所有物件都不應被視為安全執行緒。
不過，如果您從多個執行緒呼叫它，它可讓您控制執行緒同步處理。

此程式庫具有內部多執行緒保護。不過，如果您需要讓某個執行緒存取任何值，仍然需要實作自己的鎖定；例如，在另一個執行緒可能正在叫用 [XblMultiplayerManagerDoWork](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork) 時逐一查看成員清單。

### 以狀態為基礎的模型更新

多人遊戲管理員會維護以狀態為基礎的模型，在玩家加入、離開或工作階段更新時，於背景更新工作階段。
為了協助避免 UI 執行緒與遊戲執行緒之間的執行緒同步處理問題，多人遊戲管理員在您呼叫 [XblMultiplayerManagerDoWork](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork) 方法之前，不會更新工作階段的應用程式可見狀態。

傳統上，您會在背景執行緒上收到事件 (例如工作階段變更) 的通知，然後必須將其與 UI 執行緒同步，才能顯示這些變更。
使用多人遊戲管理員時，這些幕後工作都會為您完成。

您可以在您選擇的時間於主執行緒上呼叫 [XblMultiplayerManagerDoWork](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork)，以取得多人遊戲管理員在幕後為您緩衝的最新狀態快照。

## 事件和通知

多人遊戲管理員定義了一組重要事件 (請參閱 [XblMultiplayerEvent](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/structs/xblmultiplayerevent))，並在事件發生時透過 [XblMultiplayerManagerDoWork](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork) 方法通知遊戲。
例如，事件包括遠端玩家加入或離開、成員屬性變更，或工作階段狀態變更。

所有多人遊戲管理員 API 都是非同步的。
[XblMultiplayerManagerDoWork](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork) 方法會在這些非同步作業完成時傳回事件清單。
您的遊戲應根據您的情況適當處理這些事件。
如需詳細資訊，請參閱 [XblMultiplayerEvent](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/structs/xblmultiplayerevent) 類別文件。

每個傳回的 [XblMultiplayerEvent](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/structs/xblmultiplayerevent) 都包含一個 `EventArgsHandle`，您必須使用它來取得事件類型的適當 `args`。
例如，如果 [XblMultiplayerEventType](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/enums/xblmultiplayereventtype) 是 `MemberJoined`，您可以呼叫 [XblMultiplayerEventArgsMembersCount](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayereventargsmemberscount) 和 [XblMultiplayerEventArgsMembers](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayereventargsmembers)。

下列範例示範如何使用 [XblMultiplayerManagerDoWork](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork) 處理事件。

#### 平面 C API

```cpp theme={null}
size_t eventCount{ 0 };
const XblMultiplayerEvent* events{ nullptr };
HRESULT hr = XblMultiplayerManagerDoWork(&events, &eventCount);
if (FAILED(hr))
{
    // Handle failure.
}

for (auto i = 0u; i < eventCount; ++i)
{
    switch (events[i].EventType)
    {
        case XblMultiplayerEventType::MemberJoined:
        {
            // Handle MemberJoined.
            size_t memberCount = 0;
            hr = XblMultiplayerEventArgsMembersCount(events[i].EventArgsHandle, &memberCount);
            assert(SUCCEEDED(hr));

            std::vector<XblMultiplayerManagerMember> members(memberCount);
            hr = XblMultiplayerEventArgsMembers(events[i].EventArgsHandle, memberCount, members.data());
            assert(SUCCEEDED(hr));
            ...

            break;
        }

        case XblMultiplayerEventType::SessionPropertyChanged:
        {
            // Handle SessionPropertyChanged.
            const char* changedProperty{ nullptr };
            hr = XblMultiplayerEventArgsPropertiesJson(events[i].EventArgsHandle, &changedProperty);
            assert(SUCCEEDED(hr));
            ...

            break;
        }
        ...
    }
}
```

如需詳細資訊，請參閱下列內容：

* [XblMultiplayerEvent](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/structs/xblmultiplayerevent)
* [XblMultiplayerEventArgsMembers](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayereventargsmembers)
* [XblMultiplayerEventArgsMembersCount](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayereventargsmemberscount)
* [XblMultiplayerEventArgsPropertiesJson](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayereventargspropertiesjson)
* [XblMultiplayerEventType](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/enums/xblmultiplayereventtype)
* [XblMultiplayerManagerDoWork](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork)
* [XblMultiplayerManagerMember](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/structs/xblmultiplayermanagermember)

## 案例

本節涵蓋常見案例，以及您在每個案例中會呼叫的 API。
本節也提供多人遊戲管理員在幕後執行之作業的部分資訊。

* [使用多人遊戲管理員啟用與好友一起玩多人遊戲](/zh-TW/services/xbox-services/multiplayer/mpm/how-to/live-play-multiplayer-with-friends)
* [使用多人遊戲管理員透過 SmartMatch 尋找多人遊戲](/zh-TW/services/xbox-services/multiplayer/mpm/how-to/live-play-multiplayer-with-matchmaking)
* [使用多人遊戲管理員傳送遊戲邀請](/zh-TW/services/xbox-services/multiplayer/mpm/how-to/live-send-game-invites)
* [使用多人遊戲管理員處理通訊協定啟用以開始遊戲](/zh-TW/services/xbox-services/multiplayer/mpm/how-to/live-handle-protocol-activation)

如需 API 的高階概觀，請參閱[多人遊戲管理員 API 概觀](/zh-TW/services/xbox-services/multiplayer/mpm/concepts/live-multiplayer-manager-api-overview)。

## 多人遊戲管理員不會執行的工作

多人遊戲管理員讓實作多人遊戲案例變得容易許多，並為您抽象化部分資料。不過，多人遊戲管理員不會處理下列項目：

* 持續性線上伺服器遊戲，例如大型多人線上 (MMO) 遊戲，或其他需要大型工作階段 (一個工作階段中超過 100 位玩家) 的遊戲類型
* 伺服器對伺服器的工作階段管理
* 節流 MPSD 呼叫以遵守[細微速率限制](/zh-TW/services/xbox-services/develop/best-practices/live-fine-grained-rate-limiting)
* 混用多人遊戲服務 API 和多人遊戲管理員 API

<Note>多人遊戲管理員不受限於任何特定的網路技術，應可搭配任何網路通訊層運作。</Note>

## 資源

如需 API 的實際運作範例，請參閱 [NetRumble 範例](https://aka.ms/gdkdl)。

如需 API 文件，請參閱 [multiplayer\_manager\_c](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/multiplayer_manager_c_members)。
您也可以檢視 `multiplayer_manager_c.h` 標頭檔。

如果您在使用多人遊戲管理員時有任何問題、意見反應或遇到問題，請連絡您的開發人員客戶經理 (DAM)，或在 [https://forums.xboxlive.com](https://forums.xboxlive.com) 的論壇上張貼支援討論串。


## Related topics

- [多人遊戲管理員 (MPM)](/zh-TW/services/xbox-services/multiplayer/mpm/live-multiplayer-manager-nav.md)
- [XBOX 服務多人遊戲概觀](/zh-TW/services/xbox-services/multiplayer/overviews/live-multiplayer-intro.md)
- [多人遊戲管理員概念](/zh-TW/services/xbox-services/multiplayer/mpm/concepts/live-mm-concepts-nav.md)
- [多人遊戲管理員 API 概觀](/zh-TW/services/xbox-services/multiplayer/mpm/concepts/live-multiplayer-manager-api-overview.md)
- [多人遊戲管理員範例程式碼](/zh-TW/services/xbox-services/multiplayer/mpm/how-to/live-mm-howto-nav.md)