快速入门：PlayFab 多人游戏 Unity 插件

项目
02/07/2024

PlayFab 多人游戏 Unity 插件入门。按照下面的步骤安装程序包，并尝试使用基本任务的示例代码。

本快速入门可帮助使用 PlayFab 多人游戏 SDK for Unity 进行首次 API 调用。在继续之前，请确保你已完成快速入门：Unity 中适用于 C# 的 PlayFab 客户端库，这可确保你拥有一个 PlayFab 帐户，并且熟悉如何从你的游戏和 PlayFab Game Manager 登录 PlayFab。

注意

如果你打算使用此插件开发基于 Microsoft 游戏开发工具包 (GDK) 的游戏，则需要单独获取并安装 GDK。另请参阅有关 Xbox 主机上适用于 Game Core 的 Unity 附加内容的详细信息。

要求

一个 PlayFab 开发者帐户。
Unity 编辑器的已安装副本。若要通过 Unity Hub 或 Unity+ 安装 Unity 以供个人使用，请参阅下载 Unity。如果需要，请在特定平台的文档中查看 Unity 支持。支持的最低 Unity 版本是 Unity 2017 LTS。
Unity 项目 - 这可以是以下任一项：
- 一个全新的项目：有关详细信息，请参阅首次启动 Unity。
- 引导式教程项目。有关详细信息，请参阅 Unity 入门。
- 一个现有项目。
PlayFab“core”Unity3D SDK（也包含在多人游戏 Unity 插件中）。有关安装 Unity3D SDK 的信息，请参阅快速入门：Unity 中适用于 C# 的 PlayFab 客户端库中的“下载并安装 PlayFab SDK”部分。

下载并安装 PlayFab 多人游戏 Unity 插件

按照步骤下载并安装 PlayFab 多人游戏 Unity 插件。

下载 PlayFab 多人游戏 Unity 插件资产包（根据你的平台使用分发点）。
重要事项！ 请参阅随插件发布的自述文件中的信息。它针对每个特定版本量身定制，并且可能包含特定于你的平台的重要说明。
打开你的 Unity 项目。
导航到保存 .unitypackage 的位置并双击它以打开导入对话框。
若要将 PlayFab 多人游戏 Unity 插件导入项目，请选择“导入”。

注意：如有必要，可能需要安装较新版本的 PlayFab“core”Unity SDK。

设置场景

指南的这一部分介绍了如何将 PlayfabMultiplayerEventProcessor 添加到你的场景，以便你能够从 Unity 调用 PlayFab 多人游戏 API。

必须先登录 PlayFab 玩家，然后才能使用多人游戏 API。有关登录播放器的信息，请参阅快速入门：Unity 中适用于 C# 的 PlayFab 客户端库中的“进行首次 API 调用”。

在 Unity 编辑器的“项目”窗口中，导航到 资产> PlayFabMultiplayerSDK > Prefabs。
在 Prefabs 文件夹中，将 PlayfabMultiplayerEventProcessor 拖放到“层次结构”窗口中的场景。
在场景中创建名为“HelloPartyLogic”的空游戏对象。
选择 HelloMultiplayerLogic 游戏对象以打开检查器。
选择“添加组件”。
键入“HelloPartyLogic”，然后按 Enter 以显示新的脚本菜单。
再次按 Enter 创建新脚本 HelloMultiplayerLogic.cs。
在“项目”窗口中找到脚本并双击它以编辑脚本。

将以下 using 语句添加至脚本：

using PlayFab;
using PlayFab.Multiplayer;
using PlayFab.ClientModels;

在 Start 方法中添加以下代码以登录 PlayFab。

// Log into playfab
var request = new LoginWithCustomIDRequest { CustomId = UnityEngine.Random.value.ToString(), CreateAccount = true };
PlayFabClientAPI.LoginWithCustomID(request, OnLoginSuccess, OnLoginFailure);

将以下方法添加到类。

private void OnLoginSuccess(LoginResult result)
{
}

private void OnLoginFailure(PlayFabError error)
{
}

注意

你可能会收到以下错误：

Error    CS0227    Unsafe code may only appear if compiling with /unsafe
The plugin requires unsafe code because it interops with a native DLL.

Mismatch between the processor architecture of the project being built "MSIL" and the processor architecture of the reference "XGamingRuntime", "AMD64".

Microsoft GDK 和 Windows 仅支持 x64。

若要解决这些问题，请执行以下操作：

在 Unity 编辑器中，选择“文件 > 生成设置”。
选择你的平台。然后，从“体系结构”下拉列表中选择 x86_64 或 x64。
选择“玩家设置”。
在右窗格中，选择“其他设置”。
找到“允许不安全的代码”设置并将其选中。
关闭“生成设置”和“项目设置”窗口。

创建和加入大厅

指南的这一部分介绍如何创建和加入网络。

打开 HelloMultiplayerLogic.cs 脚本。在 OnLoginSuccess 方法中，添加以下代码以创建和加入网络：

string entityId = ...; // PlayFab user's entity Id
string entityType = ...; // PlayFab user's entity type

PlayFabMultiplayer.OnLobbyCreateAndJoinCompleted += this.PlayFabMultiplayer_OnLobbyCreateAndJoinCompleted;
PlayFabMultiplayer.OnLobbyDisconnected += this.PlayFabMultiplayer_OnLobbyDisconnected;

var createConfig = new LobbyCreateConfiguration()
{
    MaxMemberCount = 10,
    OwnerMigrationPolicy = LobbyOwnerMigrationPolicy.Automatic,
    AccessPolicy = LobbyAccessPolicy.Public
};

createConfig.LobbyProperties["Prop1"] = "Value1";
createConfig.LobbyProperties["Prop2"] = "Value2";

var joinConfig = new LobbyJoinConfiguration();
joinConfig.MemberProperties["MemberProp1"] = "MemberValue1";
joinConfig.MemberProperties["MemberProp2"] = "MemberValue2";

PlayFabMultiplayer.CreateAndJoinLobby(
    new PFEntityKey(
        entityId,
        entityType),
    createConfig,
    joinConfig);

若要定义 OnLobbyCreateAndJoinCompleted 事件处理程序，请将以下代码添加到类：

private void PlayFabMultiplayer_OnLobbyCreateAndJoinCompleted(Lobby lobby, int result)
{
    if (LobbyError.SUCCEEDED(result))
    {
        // Lobby was successfully created
        Debug.Log(lobby.ConnectionString);
    }
    else
    {
        // Error creating a lobby
        Debug.Log("Error creating a lobby");
    }
}

若要定义 OnLobbyDisconnected 事件处理程序，请将以下代码添加到类：

private void PlayFabMultiplayer_OnLobbyDisconnected(Lobby lobby)
{
    // Disconnected from lobby
    Debug.Log("Disconnected from lobby!");
}

在 Unity 编辑器中保存并选择“播放”。大厅连接字符串显示在控制台窗口中。

加入大厅

指南的这一部分将介绍如何加入另一个客户端创建的现有大厅。

打开 HelloMultiplayerLogic.cs 脚本。在 OnLoginSuccess 方法中，添加以下代码以加入大厅：

PFEntityKey entityKey = ...; // PlayFab user's entity key

string connectionString = "<your lobby connection string>";

PlayFabMultiplayer.JoinLobby(
        entityKey,
        connectionString,
        null);

若要定义本地客户端加入大厅时触发的事件，请将以下代码添加到 OnLoginSuccess 方法：
```
PlayFabMultiplayer.OnLobbyJoinCompleted += this.PlayFabMultiplayer_OnLobbyJoinCompleted;
```

若要定义 OnLobbyJoinCompleted 事件处理程序，请将以下代码添加到类：

private void PlayFabMultiplayer_OnLobbyJoinCompleted(Lobby lobby, PFEntityKey newMember, int reason)
{
    if (LobbyError.SUCCEEDED(reason))
    {
        // Successfully joined a lobby
        Debug.Log("Joined a lobby");
    }
    else
    {
        // Error joining a lobby
        Debug.Log("Error joining a lobby");
    }
}

在 Unity 编辑器中保存并选择“播放”。字符串“已加入大厅”显示在控制台窗口中。

查找大厅

本指南的此部分介绍如何查找其他客户端创建的现有大厅。

打开 HelloMultiplayerLogic.cs 脚本。在 OnLoginSuccess 方法中，添加以下代码以加入网络：

PFEntityKey entityKey = ...; // PlayFab user's entity key

LobbySearchConfiguration config = new LobbySearchConfiguration();
PlayFabMultiplayer.FindLobbies(entityKey, config);

若要定义本地客户端查找大厅时触发的事件，请将以下代码添加到 OnLoginSuccess 方法：
```
PlayFabMultiplayer.OnLobbyFindLobbiesCompleted += this.PlayFabMultiplayer_OnLobbyFindLobbiesCompleted;
```

若要定义 OnLobbyFindLobbiesCompleted 事件处理程序，请将以下代码添加到类：

private void PlayFabMultiplayer_OnLobbyFindLobbiesCompleted(
    IList<LobbySearchResult> searchResults, 
    PFEntityKey newMember, 
    int reason)
{
    if (LobbyError.SUCCEEDED(reason))
    {
        // Successfully found lobbies
        Debug.Log("Found lobbies");

        // Iterate through lobby search results
        foreach (LobbySearchResult result in searchResults)
        {
            // Examine a search result
        }
    }
    else
    {
        // Error finding lobbies
        Debug.Log("Error finding lobbies");
    }
}

在 Unity 编辑器中保存并选择“播放”。 “找到的大厅”字符串显示在控制台窗口中。

创建匹配票证

本指南的这一部分演示如何创建匹配票证。请将它与下面另一个客户端上的“加入匹配票证”方案一起运行。

打开 HelloMultiplayerLogic.cs 脚本。在方法中 OnLoginSuccess ，添加以下代码以创建匹配票证：

PFEntityKey entityKey = ...; // PlayFab user's entity key
PFEntityKey remoteEntityKey = ...; // another PlayFab user's entity key
string remoteUserAttributesJson = ...; // JSON string with another PlayFab user's attributes for matchmaking

PlayFabMultiplayer.OnMatchmakingTicketStatusChanged += PlayFabMultiplayer_OnMatchmakingTicketStatusChanged;

List<MatchUser> localUsers = new List<MatchUser>();
localUsers.Add(new MatchUser(entityKey, remoteUserAttributesJson));

List<PFEntityKey> membersToMatchWith = new List<PFEntityKey>();
membersToMatchWith.Add(remoteEntityKey);

PlayFabMultiplayer.CreateMatchmakingTicket(
    localUsers,
    "QuickMatchQueueName",
    membersToMatchWith);

若要定义 OnMatchmakingTicketStatusChanged 事件处理程序，请将以下代码添加到类：

private void PlayFabMultiplayer_OnMatchmakingTicketStatusChanged(MatchmakingTicket ticket)
{
    // Store and print matchmaking ticket
    Debug.Log(ticket.TicketId);

    // Examine matchmaking ticket status
    Debub.Log(ticket.Status)

    // Share matchmaking ticket with other clients taking part in matchmaking

    // Examine ticket
}

在 Unity 编辑器中保存并选择“播放”。

如果指定了 membersToMatchWith，将触发一个 OnMatchmakingTicketStatusChanged 事件处理程序，状态将为 WaitingForPlayers。在这种情况下，当另一个客户端调用 JoinMatchmakingTicketFromId 后，将触发新的 OnMatchmakingTicketStatusChanged 事件处理程序，这次的状态将为 WaitingForMatch。

或者，将触发一个 OnMatchmakingTicketStatusChanged 事件处理程序，并且状态将为 WaitingForMatch。

创建匹配票证

指南的这一部分将介绍如何加入另一个客户端创建的现有网络。请将它与上述另一个客户端上的“创建匹配票证”方案一起运行。

打开 HelloMultiplayerLogic.cs 脚本。在 OnLoginSuccess 方法中，添加以下代码以匹配票证：

PFEntityKey entityKey = ...; // PlayFab user's entity key
string ticketId = ...; // Matchmaking ticket obtained from the client that created the ticket

PlayFabMultiplayer.OnMatchmakingTicketCompleted += PlayFabMultiplayer_OnMatchmakingTicketStatusChanged;

// Create JSON string with PlayFab user's attributes for matchmaking. This will need to be shared with other clients taking part in matchmaking
string uniqueId = System.Guid.NewGuid().ToString();
string userAttributesJson = "{\"MatchIdentifier\": \"" + uniqueId + "\"}";

PlayFabMultiplayer.JoinMatchmakingTicketFromId(
    new MatchUser(entityKey, userAttributesJson),
    ticketId,
    "QuickMatchQueueName",
    new List<PFEntityKey>());

若要定义 OnMatchmakingTicketStatusChanged 事件处理程序，请将以下代码添加到类：

private void PlayFabMultiplayer_OnMatchmakingTicketStatusChanged(MatchmakingTicket ticket)
{
    // Store and print matchmaking ticket
    Debug.Log(ticket.TicketId);

    // Examine matchmaking ticket status
    Debub.Log(ticket.Status)

    // Share matchmaking ticket with other clients taking part in matchmaking

    // Examine ticket
}

在 Unity 编辑器中保存并选择“播放”。

将触发一个 OnMatchmakingTicketStatusChanged，状态为 WaitingForMatch。

完成匹配票证

本指南的此部分介绍如何完成匹配。请将它与上述另一个客户端上的“创建匹配票证”方案一起运行。（可选）可以将其与“加入匹配票证”方案一起运行。

在同一队列中的多个票证有资格匹配后，将找到匹配项。在这种情况下，将触发 OnMatchmakingTicketCompleted 事件处理程序。

订阅 OnMatchmakignTicketCompleted 处理程序

PlayFabMultiplayer.OnMatchmakingTicketCompleted += PlayFabMultiplayer_OnMatchmakingTicketCompleted;

若要定义 OnMatchmakingTicketCompleted 事件处理程序，请将以下代码添加到类：

private void PlayFabMultiplayer_OnMatchmakingTicketCompleted(MatchmakingTicket ticket, int result)
{
    if (LobbyError.SUCCEEDED(result))
    {
        // Successfully completed matchmaking ticket
        Debug.Log("Completed matchmaking ticket");

        // Examine matchmaking details
        MatchmakingMatchDetails details = ticket.GetMatchDetails();
    }
    else
    {
        // Error completing a matchmaking ticket
        Debug.Log("Error completing a matchmaking ticket");
    }
}

通过

快速入门：PlayFab 多人游戏 Unity 插件

要求

下载并安装 PlayFab 多人游戏 Unity 插件

设置场景

创建和加入大厅

加入大厅

查找大厅

创建匹配票证

创建匹配票证

完成匹配票证

反馈

其他资源