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

# 使用多人遊戲管理員與好友一起玩多人遊戲

> 使用多人遊戲管理員初始化大廳工作階段、傳送 XBOX Live 邀請，並讓好友加入進行中遊戲的逐步指南。

<a id="top" />

在簡單的多人遊戲案例中，您遊戲的玩家可以與好友一起線上遊玩。本主題說明使用多人遊戲管理員支援此案例所需實作的基本步驟。

## 傳送和接受邀請的步驟

下列步驟使用多人遊戲管理員傳送邀請給使用者的好友，讓該好友可以加入進行中的遊戲。

1. [初始化多人遊戲管理員](#initialize-multiplayer-manager)
2. [藉由新增本機使用者建立大廳工作階段](#create-lobby)
3. [傳送邀請給好友](#send-invites)
4. [接受邀請](#accept-invites)
5. [從大廳加入遊戲工作階段](#join-game)

步驟 1、2、3 和 5 在發出邀請的裝置上執行。
步驟 4 通常在受邀者的裝置上，於透過通訊協定啟用啟動應用程式之後起始。

如需詳細資訊，請參閱[與好友一起玩遊戲 (流程圖)](/zh-TW/services/xbox-services/multiplayer/mpm/concepts/flowcharts/live-mpm-play-with-friends)。

## 初始化多人遊戲管理員 <a id="initialize-multiplayer-manager" />

使用有效的工作階段範本名稱初始化多人遊戲管理員時，會自動建立大廳工作階段物件。工作階段範本是在服務設定中定義的。

<Note>在新增使用者之前，服務上不會建立大廳工作階段執行個體。</Note>

#### 平面 C API

```cpp theme={null}
HRESULT hr = XblMultiplayerManagerInitialize(lobbySessionTemplateName, queueUsedByMultiplayerManager);
```

如需詳細資訊，請參閱 [XblMultiplayerManagerInitialize](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerinitialize)。

[返回本主題頂端。](#top)

## 藉由新增本機使用者建立大廳工作階段 <a id="create-lobby" />

將本機已登入的 XBOX 服務使用者新增至大廳工作階段。新增第一位使用者時，會裝載新的大廳。所有其他使用者都會以次要使用者的身分新增至現有的大廳。

多人遊戲管理員會在殼層中公告大廳，供好友加入。
只有在新增本機使用者之後，您才能透過 `lobby()` 傳送邀請、設定大廳屬性，以及存取大廳成員。

當本機使用者加入大廳時，建議您設定其連線位址和任何自訂屬性。

您必須針對所有本機已登入的使用者重複此程序。

[返回本主題頂端。](#top)

### 新增單一本機使用者

#### 平面 C API

```cpp theme={null}
HRESULT hr = XblMultiplayerManagerLobbySessionAddLocalUser(xblUserHandle);

if (!SUCCEEDED(hr))
{
    // Handle failure.
}

// Set member connection address.
const char* connectionAddress = "1.1.1.1";
hr = XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress(
    xblUserHandle, connectionAddress, context);

if (!SUCCEEDED(hr))
{
    // Handle failure.
}

// Set custom member properties.
const char* propName = "Name";
const char* propValueJson = "{}";
hr = XblMultiplayerManagerLobbySessionSetProperties(propName, propValueJson, context);

if (!SUCCEEDED(hr))
{
    // Handle failure.
}
...
```

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

* [XblMultiplayerManagerLobbySessionAddLocalUser](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionaddlocaluser)
* [XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionsetlocalmemberconnectionaddress)
* [XblMultiplayerManagerLobbySessionSetProperties](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionsetproperties)

[返回本主題頂端。](#top)

### 新增多個本機使用者

#### 平面 C API

```cpp theme={null}
std::vector<XblUserHandle> xblUsers;
for (XblUserHandle xblUserHandle : xblUsers)
{
    HRESULT hr = XblMultiplayerManagerLobbySessionAddLocalUser(xblUserHandle);

    if (!SUCCEEDED(hr))
    {
        // Handle failure.
    }

    // Set member connection address.
    const char* connectionAddress = "1.1.1.1";
    hr = XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress(
        xblUserHandle, connectionAddress, context);

    if (!SUCCEEDED(hr))
    {
        // Handle failure.
    }

    // Set custom member properties.
    const char* propName = "Name";
    const char* propValueJson = "{}";
    hr = XblMultiplayerManagerLobbySessionSetProperties(propName, propValueJson, context);
    ...
}
```

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

* [XblMultiplayerManagerLobbySessionAddLocalUser](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionaddlocaluser)
* [XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionsetlocalmemberconnectionaddress)
* [XblMultiplayerManagerLobbySessionSetProperties](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionsetproperties)

這些變更會在下一次 [XblMultiplayerManagerDoWork](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork) 呼叫時批次處理。
每次將使用者新增至大廳工作階段時，多人遊戲管理員都會引發 [XblMultiplayerEventType](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/enums/xblmultiplayereventtype)::UserAdded 事件。

建議您檢查事件的錯誤碼，以確認是否已成功新增該使用者。
如果失敗，錯誤訊息會提供失敗原因的詳細資料。

多人遊戲管理員會執行下列功能，藉由新增本機使用者來建立大廳工作階段。

* 向 XBOX 服務多人遊戲服務註冊即時活動和多人遊戲訂閱。
* 建立大廳工作階段。
* 讓所有本機玩家以作用中狀態加入。
* 上傳安全裝置位址 (SDA)。
* 設定成員屬性。
* 註冊工作階段變更事件。
* 將大廳工作階段設定為作用中工作階段。

[返回本主題頂端。](#top)

## 傳送邀請給好友 <a id="send-invites" />

顯示標準 XBOX UI，玩家可在其中選取要邀請加入遊戲的好友或最近的玩家。
當玩家確認其選取項目後，多人遊戲管理員會將邀請傳送給選取的玩家。

遊戲也可以使用 [XblMultiplayerManagerLobbySessionInviteUsers](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessioninviteusers) 方法，將邀請傳送給由其 XBOX 服務使用者識別碼定義的一組人員。
如果您使用自己的遊戲內 UI 而非標準 XBOX UI，此方法會很有用。

#### 平面 C API

```cpp theme={null}
size_t xuidsCount = 1;
uint64_t xuids[1] = {};
xuids[0] = 1234567891234567;
HRESULT hr = XblMultiplayerManagerLobbySessionInviteUsers(
    xblUserHandle, 
    xuids, 
    xuidsCount, 
    nullptr,    // ContextStringId 
    nullptr     // CustomActivationContext
);
```

如需詳細資訊，請參閱 [XblMultiplayerManagerLobbySessionInviteUsers](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessioninviteusers)。

多人遊戲管理員會執行下列功能來傳送邀請給好友。

* 顯示 XBOX 標準遊戲可呼叫 UI (TCUI)
* 直接將邀請傳送給選取的玩家

[返回本主題頂端。](#top)

## 接受邀請 <a id="accept-invites" />

當受邀玩家接受遊戲邀請，或透過殼層 UI 加入好友的遊戲時，遊戲會在其裝置上啟動。

在以 Microsoft Game Development Kit (GDK) 為基礎的遊戲上，遊戲啟動後，請呼叫 [XGameActivationRegisterForEvent](/zh-TW/reference/system/xgameactivation/functions/xgameactivationregisterforevent) 來接聽邀請事件。

在以 XBOX One Software Development Kit 和通用 Windows 平台 (UWP) 為基礎的遊戲上，遊戲啟動後，多人遊戲管理員可以使用通訊協定啟用的事件引數來加入大廳。

如果受邀使用者未透過 [XblMultiplayerManagerLobbySessionAddLocalUser](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionaddlocaluser) 新增，[XblMultiplayerManagerJoinLobby](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoinlobby) 會失敗，而您可以搭配 `JoinLobbyCompleted` 事件呼叫 [XblMultiplayerEventArgsXuid](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayereventargsxuid)，以取得邀請所傳送給的 xuid。

加入大廳之後，建議您設定本機成員的連線位址，以及該成員的任何自訂屬性。
如果主機不存在，您也可以透過 [XblMultiplayerManagerLobbySessionSetSynchronizedHost](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionsetsynchronizedhost) 設定主機。

最後，如果遊戲已在進行中且仍有空間容納受邀者，多人遊戲管理員會自動讓使用者加入遊戲工作階段。
遊戲會透過 `JoinGameCompleted` 事件收到通知，並提供適當的錯誤碼和訊息。

錯誤或成功結果會透過 `JoinLobbyCompleted` 事件處理。

#### 平面 C API

```cpp theme={null}

void CALLBACK MyXGameInviteEventCallback(
    _In_opt_ void* context,
    _In_ const XGameActivationInfo* activationInfo)
{
    UNREFERENCED_PARAMETER(context);
    if (activationInfo->type == XGameActivationType::AcceptedGameInvite)
    {
        if (activationInfo->inviteUri != nullptr)
        {
            std::string inviteString(activationInfo->inviteUri);
            auto pos = inviteString.find("handle=");
            auto inviteHandleId = inviteString.substr(pos + 7, 36);

            // Now use inviteHandleId when calling XblMultiplayerManagerJoinLobby().  
            // See the example call as follows.
        }
    }
}

XTaskQueueRegistrationToken token = { 0 };
HRESULT hr = XGameActivationRegisterForEvent(
    queue,
    nullptr,
    MyXGameInviteEventCallback,
    &token);

```

```cpp theme={null}
HRESULT hr = XblMultiplayerManagerJoinLobby(inviteHandleId, xblUserHandle);
if (!SUCCEEDED(hr))
{
    // Handle failure.
}

// Set member connection address.
const char* connectionAddress = "1.1.1.1";
hr = XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress(
    xblUserHandle, connectionAddress, context);
```

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

* [XblMultiplayerManagerJoinLobby](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoinlobby)
* [XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionsetlocalmemberconnectionaddress)

多人遊戲管理員會執行下列功能來接受邀請。

* 註冊即時活動和多人遊戲訂閱。
* 加入大廳工作階段。
* 清除現有的大廳狀態。
* 讓所有本機玩家以作用中狀態加入。
* 上傳 SDA。
* 設定成員屬性。
* 註冊工作階段變更事件。
* 將大廳工作階段設定為作用中工作階段。
* 加入遊戲工作階段 (如果存在)。
* 使用轉移控制代碼。

[返回本主題頂端。](#top)

## 從大廳加入遊戲工作階段 <a id="join-game" />

在邀請被接受且主機準備好開始玩遊戲之後，您可以呼叫 [XblMultiplayerManagerJoinGameFromLobby](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoingamefromlobby)，開始包含大廳工作階段成員的新遊戲。

錯誤或成功結果會透過 `JoinGameCompleted` 事件處理。

#### 平面 C API

```cpp theme={null}
HRESULT hr = XblMultiplayerManagerJoinGameFromLobby(gameSessionTemplateName);
if (!SUCCEEDED(hr))
{
    // Handle error.
}
```

如需詳細資訊，請參閱 [XblMultiplayerManagerJoinGameFromLobby](/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoingamefromlobby)。

多人遊戲管理員會執行下列功能，以從大廳加入遊戲工作階段。

* 建立遊戲工作階段。
* 讓所有本機玩家以作用中狀態加入。
* 上傳 SDA。
* 設定成員屬性。
* 註冊工作階段變更事件。
* 透過大廳工作階段公告遊戲。

[返回本主題頂端。](#top)


## Related topics

- [使用多人遊戲管理員傳送遊戲邀請](/zh-TW/services/xbox-services/multiplayer/mpm/how-to/live-send-game-invites.md)
- [使用多人遊戲管理員處理通訊協定啟用](/zh-TW/services/xbox-services/multiplayer/mpm/how-to/live-handle-protocol-activation.md)
- [接收邀請](/zh-TW/services/xbox-services/multiplayer/invites/how-to/live-invites-receive.md)
- [與好友一起玩遊戲 (流程圖)](/zh-TW/services/xbox-services/multiplayer/mpm/concepts/flowcharts/live-mpm-play-with-friends.md)
- [多人遊戲管理員範例程式碼](/zh-TW/services/xbox-services/multiplayer/mpm/how-to/live-mm-howto-nav.md)