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

# 多人遊戲活動的範例程式碼

> XBOX 多人遊戲活動 C++ 快速入門範例，用於從您的 GDK 遊戲設定活動、傳送邀請和更新最近的玩家清單。

本主題旨在作為多人遊戲活動用戶端 API 基本用法的快速入門指南。本主題討論管理活動、傳送邀請，以及將玩家新增至最近的玩家清單。

[活動](#activities) [邀請](#invites) [最近的玩家](#recent-players)

## 活動

### 設定活動

每當遊戲開始或加入多人遊戲體驗時，都應建立活動。這麼做可讓殼層以及您遊戲中的其他玩家看到該玩家的活動，並讓其他玩家有可能加入進行中的遊戲。如果玩家想要加入您遊戲的活動，而遊戲並未執行，遊戲會被啟用並傳入連線字串。

遊戲應在玩家加入或離開時更新活動。這可為其他玩家提供更豐富的活動檢視，並告知他們活動是否已滿。

如需活動欄位的相關資訊，請參閱[活動內容](https://docs.xbox.com/zh-TW/services/xbox-services/multiplayer/mpa/concepts/live-mpa-activities.md#activity-contents)。

以下是設定活動的程式碼範例。它適用於建立活動以及更新現有的活動。

```cpp theme={null}
auto async = std::make_unique<XAsyncBlock>();
async->queue = queue;
async->callback = [](XAsyncBlock* async)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // Take ownership of XAsyncBlock.
    HRESULT hr = XAsyncGetStatus(async, false);
};

XblMultiplayerActivityInfo info{};
info.connectionString = "dummyConnectionString";
info.joinRestriction = XblMultiplayerActivityJoinRestriction::Followed;
info.maxPlayers = 10;
info.currentPlayers = 1;
info.groupId = "dummyGroupId";

HRESULT hr = XblMultiplayerActivitySetActivityAsync(
    xblContext,
    &info,
    false,
    async.get()
);

if (SUCCEEDED(hr))
{
    async.release();
}
```

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

* [XAsyncBlock](https://docs.xbox.com/zh-TW/reference/system/xasync/structs/xasyncblock.md)
* [XAsyncGetStatus](https://docs.xbox.com/zh-TW/reference/system/xasync/functions/xasyncgetstatus.md)
* [XblMultiplayerActivityInfo](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_activity_c/structs/xblmultiplayeractivityinfo.md)
* [XblMultiplayerActivityJoinRestriction](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_activity_c/enums/xblmultiplayeractivityjoinrestriction.md)
* [XblMultiplayerActivitySetActivityAsync](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_activity_c/functions/xblmultiplayeractivitysetactivityasync.md)

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

### 取得活動

遊戲可能會想要知道其他玩家的活動。例如，遊戲可能會想要在遊戲內 UI 中顯示玩家在該遊戲中的好友及其活動。

以下是擷取活動的程式碼範例。

```cpp theme={null}
auto async = std::make_unique<XAsyncBlock>();
async->queue = queue;
async->callback = [](XAsyncBlock* async)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // Take ownership of XAsyncBlock.

    size_t resultSize{};
    HRESULT hr = XblMultiplayerActivityGetActivityResultSize(async, &resultSize);
    if (SUCCEEDED(hr))
    {
        std::vector<uint8_t> buffer(resultSize);
        XblMultiplayerActivityInfo* activityInfo{};
        size_t resultCount{};
        hr = XblMultiplayerActivityGetActivityResult(async, buffer.size(), buffer.data(), &activityInfo, &resultCount, nullptr);
        if (SUCCEEDED(hr))
        {
            // ...
        }
    }
};

HRESULT hr = XblMultiplayerActivityGetActivityAsync(
    xblContext,
    &xuid,
    1,
    async.get()
);

if (SUCCEEDED(hr))
{
    async.release();
}
```

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

* [XAsyncBlock](https://docs.xbox.com/zh-TW/reference/system/xasync/structs/xasyncblock.md)
* [XblMultiplayerActivityGetActivityResultSize](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_activity_c/functions/xblmultiplayeractivitygetactivityresultsize.md)
* [XblMultiplayerActivityInfo](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_activity_c/structs/xblmultiplayeractivityinfo.md)
* [XblMultiplayerActivityGetActivityResult](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_activity_c/functions/xblmultiplayeractivitygetactivityresult.md)
* [XblMultiplayerActivityGetActivityAsync](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_activity_c/functions/xblmultiplayeractivitygetactivityasync.md)

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

### 刪除活動

當玩家結束或離開多人遊戲活動時，遊戲應使用下列程式碼刪除活動。

```cpp theme={null}
auto async = std::make_unique<XAsyncBlock>();
async->queue = queue;
async->callback = [](XAsyncBlock* async)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // Take ownership of XAsyncBlock.
    HRESULT hr = XAsyncGetStatus(async, false);
};

HRESULT hr = XblMultiplayerActivityDeleteActivityAsync(xblContext, async.get());

if (SUCCEEDED(hr))
{
    async.release();
}
```

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

* [XAsyncBlock](https://docs.xbox.com/zh-TW/reference/system/xasync/structs/xasyncblock.md)
* [XAsyncGetStatus](https://docs.xbox.com/zh-TW/reference/system/xasync/functions/xasyncgetstatus.md)
* [XblMultiplayerActivityDeleteActivityAsync](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_activity_c/functions/xblmultiplayeractivitydeleteactivityasync.md)

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

## 邀請

### 在沒有 UI 的情況下傳送邀請

玩家可能會想要直接傳送邀請給一或多位其他玩家。在傳送邀請之前，遊戲應確保已設定活動。這可確保殼層與您的遊戲之間的連續性，因為殼層會根據目前的活動傳送邀請。

若要在沒有 UI 的情況下傳送邀請，在使用 [XblMultiplayerActivitySetActivityAsync](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_activity_c/functions/xblmultiplayeractivitysetactivityasync.md) 設定活動之後 (請參閱上方範例)，遊戲應呼叫 [XblMultiplayerActivitySendInvitesAsync](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_activity_c/functions/xblmultiplayeractivitysendinvitesasync.md) API，並傳遞要邀請的玩家陣列，以及您目前活動中使用的相同連線字串。

如需邀請內容的相關資訊，請參閱[傳送要求讓另一位玩家加入多人遊戲體驗。](https://docs.xbox.com/zh-TW/services/xbox-services/multiplayer/mpa/concepts/live-mpa-invites.md)。

以下是在沒有 UI 的情況下傳送邀請的程式碼範例。

```cpp theme={null}
auto async = std::make_unique<XAsyncBlock>();
async->queue = queue;
async->callback = [](XAsyncBlock* async)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // Take ownership of XAsyncBlock.
    HRESULT hr = XAsyncGetStatus(async, false);
};

HRESULT hr = XblMultiplayerActivitySendInvitesAsync(
    xblContext,
    &xuid,
    1,
    true, // Setting false will send the invite to only players on the sender's platform.
    "dummyConnectionString",
    async.get()
);

if (SUCCEEDED(hr))
{
    async.release();
}
```

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

* [XAsyncBlock](https://docs.xbox.com/zh-TW/reference/system/xasync/structs/xasyncblock.md)
* [XAsyncGetStatus](https://docs.xbox.com/zh-TW/reference/system/xasync/functions/xasyncgetstatus.md)
* [XblMultiplayerActivitySendInvitesAsync](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_activity_c/functions/xblmultiplayeractivitysendinvitesasync.md)

### 使用 UI 傳送邀請

玩家可能會想要直接傳送邀請給一或多位其他玩家。在傳送邀請之前，遊戲應確保已設定活動。這可確保殼層與您的遊戲之間的連續性，因為殼層會根據目前的活動傳送邀請。

若要使用 UI 傳送邀請，在使用 [XblMultiplayerActivitySetActivityAsync](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_activity_c/functions/xblmultiplayeractivitysetactivityasync.md) 設定活動之後 (請參閱上方範例)，遊戲應呼叫 [XGameUiShowMultiplayerActivityGameInviteAsync](https://docs.xbox.com/zh-TW/reference/system/xgameui/functions/xgameuishowmultiplayeractivitygameinviteasync.md) API 並傳入提出要求的使用者。它會使用遊戲目前的活動，並使用其連線字串和設定邀請玩家。

如需邀請內容的相關資訊，請參閱[傳送要求讓另一位玩家加入多人遊戲體驗。](https://docs.xbox.com/zh-TW/services/xbox-services/multiplayer/mpa/concepts/live-mpa-invites.md)。

以下是使用 UI 傳送邀請的程式碼範例。

```cpp theme={null}
auto async = std::make_unique<XAsyncBlock>();
async->queue = queue;
async->callback = [](XAsyncBlock* async)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // Take ownership of XAsyncBlock.
    HRESULT hr = XGameUiShowMultiplayerActivityGameInviteResult(async);
    if (hrAsync == S_OK) 
    { 
        // Handle success 
    } 
    else 
    { 
        // Likely will only happen during development - usually indicates 
        // an invalid user was passed in or that there is no multiplayer activity set
    }     
};

HRESULT hr = XGameUiShowMultiplayerActivityGameInviteAsync(
    async.get()
    requestingUser
);

if (SUCCEEDED(hr))
{
    async.release();
}
```

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

* [XAsyncBlock](https://docs.xbox.com/zh-TW/reference/system/xasync/structs/xasyncblock.md)
* [XAsyncGetStatus](https://docs.xbox.com/zh-TW/reference/system/xasync/functions/xasyncgetstatus.md)
* [XGameUiShowMultiplayerActivityGameInviteAsync](https://docs.xbox.com/zh-TW/reference/system/xgameui/functions/xgameuishowmultiplayeractivitygameinviteasync.md)
* [XGameUiShowMultiplayerActivityGameInviteResult](https://docs.xbox.com/zh-TW/reference/system/xgameui/functions/xgameuishowmultiplayeractivitygameinviteresult.md)

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

### 接收邀請

若要在玩家接受邀請時收到通知，遊戲可以使用 `XGameInviteRegisterForEvent` 註冊邀請通知。每次接受邀請時，都會透過註冊的回呼將格式化的 URI 傳遞給遊戲。可以剖析 URI 以判斷邀請傳送者、接收者和連線字串。連線字串是遊戲特定的，並在建立多人遊戲活動時設定。對於使用多人遊戲活動服務的遊戲，URI 的完整格式如下表所示。

| 平台 | 格式 |
| - | - |
| 主機上的 Microsoft Game Development Kit (GDK) 或 XBOX One 軟體開發套件 | `ms-xbl-<titleId>://inviteAccept?invitedUser=<xuid>&sender=<xuid>&connectionString=<connectionString>` |
| PC 上的 Microsoft Game Development Kit (GDK) 或通用 Windows 平台 (UWP) | `ms-xbl-multiplayer://inviteAccept?invitedUser=<xuid>&sender=<xuid>&connectionString=<connectionString>` |

當不再需要邀請通知時，可以使用 `XGameInviteUnregisterForEvent` 取消註冊回呼。以下是註冊和處理已接受邀請的程式碼範例。

```cpp theme={null}
void CALLBACK MyXGameInviteEventCallback(
    _In_opt_ void* context,
    _In_ const char* inviteUri)
{
    if (inviteUri != nullptr)
    {
        std::string uri{ inviteUri };
        size_t invitedUserBegin = uri.find("invitedUser=");
        size_t senderBegin = uri.find("sender=");
        std::string invitedUser = uri.substr(invitedUserBegin, uri.find('&', invitedUserBegin) - invitedUserBegin);
        std::string sender = uri.substr(senderBegin, uri.find('&', senderBegin) - senderBegin);
        std::string connectionString = uri.substr(uri.find("connectionString="));

        // ...
    }
}

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

// ...
bool result = XGameInviteUnregisterForEvent(token, true);
```

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

* [XGameInviteRegisterForEvent](https://docs.xbox.com/zh-TW/reference/system/xgameinvite/functions/xgameinviteregisterforevent.md)
* [XGameInviteUnregisterForEvent](https://docs.xbox.com/zh-TW/reference/system/xgameinvite/functions/xgameinviteunregisterforevent.md)

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

## 最近的玩家

若要更新玩家的最近的玩家清單，遊戲應提交曾與目前玩家有過有意義互動之其他玩家的清單。此清單是單向的，表示每位玩家的用戶端負責更新自己的清單，玩家的清單不會影響彼此的清單。

例如，假設一群玩家一起位於賽前大廳中並被配對在一起。比賽開始時，每位玩家都會以大廳中所有其他 `xuids` 更新其清單。如果有新玩家加入，可以個別寫入。

> [!NOTE]
>
> 您可以決定什麼構成有意義的互動。對某個遊戲而言，可能是出現在大廳中。對另一個遊戲而言，可能是某位玩家射擊另一位玩家。對第三個遊戲而言，可能只是畫面上看得到另一位玩家。

在您可能不希望玩家隊伍在比賽工作階段開始之前被看到的案例中，您可以延遲寫入玩家清單，直到您希望他們彼此可見的時間為止。若要排清用戶端的最近的玩家清單，如果您需要立即強制排清，可以呼叫 `XblMultiplayerActivityFlushRecentPlayersAsync`。否則，最近的玩家清單會每五秒自動排清一次。

以下是更新最近的玩家清單和排清更新的程式碼範例。

### 更新最近的玩家

```cpp theme={null}
XblMultiplayerActivityRecentPlayerUpdate update{ xuid };
HRESULT hr = XblMultiplayerActivityUpdateRecentPlayers(xblContext, &update, 1);
```

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

* [XblMultiplayerActivityRecentPlayerUpdate](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_activity_c/structs/xblmultiplayeractivityrecentplayerupdate.md)
* [XblMultiplayerActivityUpdateRecentPlayers](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_activity_c/functions/xblmultiplayeractivityupdaterecentplayers.md)

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

### 排清最近的玩家

```cpp theme={null}
auto async = std::make_unique<XAsyncBlock>();
async->queue = queue;
async->callback = [](XAsyncBlock* async)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // Take ownership of XAsyncBlock.
    HRESULT hr = XAsyncGetStatus(async, false);
};

HRESULT hr = XblMultiplayerActivityFlushRecentPlayersAsync(xblContext, async.get());
if (SUCCEEDED(hr))
{
    async.release();
}
```

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

* [XAsyncBlock](https://docs.xbox.com/zh-TW/reference/system/xasync/structs/xasyncblock.md)
* [XAsyncGetStatus](https://docs.xbox.com/zh-TW/reference/system/xasync/functions/xasyncgetstatus.md)
* [XblMultiplayerActivityFlushRecentPlayersAsync](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_activity_c/functions/xblmultiplayeractivityflushrecentplayersasync.md)

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


## Related topics

- [多人遊戲活動範例程式碼](https://docs.xbox.com/zh-TW/services/xbox-services/multiplayer/mpa/how-to/live-mpa-how-to-nav.md)
- [多人遊戲活動 (MPA)](https://docs.xbox.com/zh-TW/services/xbox-services/multiplayer/mpa/live-mpa-nav.md)
- [操作說明](https://docs.xbox.com/zh-TW/services/xbox-services/multiplayer/mpa/how-to/index.md)
- [XblMultiplayerActivityGetActivityResultSize](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_activity_c/functions/xblmultiplayeractivitygetactivityresultsize.md)
- [XblMultiplayerActivityEncounterType](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_activity_c/enums/xblmultiplayeractivityencountertype.md)