通过

大厅 SDK 快速入门

  • 项目

本文介绍如何使用 PlayFab 多人游戏 C/C++ SDK 设置 Azure PlayFab 大厅的开发环境并创建第一个大厅。

注意

PlayFab 多人游戏 SDK 还为 PlayFab 匹配提供 API。

先决条件

需要 PlayFab 帐户 才能使用 PlayFab 大厅。 有关创建帐户的说明，请参阅 快速入门：Game Manager。

下载并设置 PlayFab 多人游戏 SDK

下载适用于平台的 C/C++ SDK ，并将提供程序标头和库文件集成到生成中。

注意

本快速入门重点介绍如何使用 C/C++ SDK。 有关 Unity 和 Unreal 接口，请参阅以下文章：

登录 PlayFab 实体

若要使用 PlayFab 大厅 SDK，需要使用 PlayFab 实体密钥和实体令牌对客户端进行身份验证。 通过使用 LoginWithCustomId REST API 登录来获取 PlayFab 实体密钥和令牌对。 此 API 还可通过 PlayFab REST SDK提供 C/C++ 投影。

注意

LoginWithCustomId 是开始使用 PlayFab 功能的一种快速方法，但不旨在成为你随附的登录机制。 有关登录指南，请参阅 登录基础知识和最佳做法。

初始化 PlayFab 多人游戏 SDK

按照以下基本步骤初始化 PlayFab 多人游戏 SDK：

  1. 通过调用 PFMultiplayerInitialize 初始化 SDK
  2. 通过调用 PFMultiplayerSetEntityToken，设置库代表玩家使用的实体密钥和令牌。
static PFMultiplayerHandle g_pfmHandle = nullptr;
...
...
HRESULT hr = S_OK;

// Initialize the PFMultiplayer library.
hr = PFMultiplayerInitialize(titleId, &g_pfmHandle);
if (FAILED(hr))
{
    // handle initialize failure
    printf("PFMultiplayerInitialize failed! %s\n", PFMultiplayerGetErrorMessage(hr));
    return hr;
}

// Set an entity token for a local user. The token is used to authenticate PlayFab operations on behalf of this user. 
// Tokens can expire, and this API token should be called again when this token is refreshed.
hr = PFMultiplayerSetEntityToken(g_pfmHandle, localUserEntity, entityToken);
if (FAILED(hr))
{
    // handle set entity token failure
    printf("PFMultiplayerSetEntityToken failed! %s\n", PFMultiplayerGetErrorMessage(hr));
    return hr;
}

创建大厅

最后，我们将按照以下基本步骤创建大厅：

  1. 调用 PFMultiplayerCreateAndJoinLobby
  2. 通过定期轮询 PFLobbyCreateAndJoinLobbyCompletedStateChange 的 PFMultiplayerStartProcessingLobbyStateChanges 来检查异步完成。
PFLobbyCreateConfiguration lobbyConfiguration{};
lobbyConfiguration.maxMemberCount = 16;
lobbyConfiguration.ownerMigrationPolicy = PFLobbyOwnerMigrationPolicy::Automatic;
lobbyConfiguration.accessPolicy = PFLobbyAccessPolicy::Public;

PFLobbyJoinConfiguration memberConfiguration{};

PFLobbyHandle lobby;
HRESULT hr = PFMultiplayerCreateAndJoinLobby(g_pfmHandle, localUserEntity, &lobbyConfiguration, &memberConfiguration, nullptr, &lobby);
if (FAILED(hr))
{
    // handle immediate create failure
    printf("PFMultiplayerCreateAndJoinLobby failed! %s\n", PFMultiplayerGetErrorMessage(hr));
    return hr;
}

// NOTE: to simplify this quickstart, we'll synchronously block waiting waiting for the CreateAndJoinLobby operation
// to finish. In a real implementation, this polling would be done asynchronously on a background thread/worker.
bool createAndJoinLobbyFinished = false;
while (!createAndJoinLobbyFinished)
{
    uint32_t lobbyStateChangeCount;
    const PFLobbyStateChange * const * lobbyStateChanges;
    HRESULT hr = PFMultiplayerStartProcessingLobbyStateChanges(m_pfmHandle, &lobbyStateChangeCount, &lobbyStateChanges);
    if (FAILED(hr))
    {
        // handle the failure
        printf("PFMultiplayerStartProcessingLobbyStateChanges failed! %s\n", PFMultiplayerGetErrorMessage(hr));
        return hr;
    }

    for (uint32_t i = 0; i < lobbyStateChangeCount; ++i)
    {
        const PFLobbyStateChange* stateChange = lobbyStateChanges[i];
        switch (stateChange->stateChangeType)
        {
            case PFLobbyStateChangeType::CreateAndJoinLobbyCompleted:
            {
                auto createAndJoinStateChange = 
                    static_cast<const PFLobbyCreateAndJoinLobbyCompletedStateChange*>(stateChange);

                if (SUCCEEDED(createAndJoinStateChange->result))
                {
                    // lobby successfully created!
                    printf("Lobby 0x%p successfully created!\n", createAndJoinStateChange->lobby);
                }
                else
                {
                    // report asynchronous failure
                    printf("Failed to create lobby 0x%p! %s\n",
                        createAndJoinStateChange->lobby,
                        PFMultiplayerGetErrorMessage(createAndJoinStateChange->result));
                }
                createAndJoinLobbyFinished = true;
                break;
            }
        }
    }

    hr = PFMultiplayerFinishProcessingLobbyStateChanges(m_pfmHandle, lobbyStateChangeCount, lobbyStateChanges);
    if (FAILED(hr))
    {
        printf("PFMultiplayerFinishProcessingLobbyStateChanges failed! %s\n", PFMultiplayerGetErrorMessage(hr));
        return hr;
    }
}

有关创建大厅的详细信息，请参阅 创建大厅。

有关处理异步操作的详细信息，请参阅 异步操作和通知。

后续步骤

另请参阅