将 GSDK 添加到项目

本文介绍如何升级现有项目,使其可以托管在 PlayFab Multiplayer Servers (MPS) 上。该过程包括将 PlayFab GSDK 添加并配置到 Unreal 项目中。此处的说明是使用 Unreal ThirdPersonMP 模板项目编写的。请注意,您的 Unreal 项目必须具有以下功能:

网络
多人游戏
专用游戏服务器

如果没有,您需要返回到示例项目设置指南,将您的项目配置为启用网络的多人游戏,并具备专用服务器功能。

目标

我们将向您的项目添加并配置 PlayFab Unreal GSDK,并在本地测试以验证它有望在 PlayFab Multiplayer Services 上正常工作。

要求

下载 Visual Studio。社区版是免费的。
- 所需的工作负载:.NET 桌面开发和使用 C++ 的桌面开发
下载 Unreal Engine 源代码。有关说明,请参见下载 Unreal Engine 源代码(外部)。
已完成的 ThirdPersonMP 示例项目,或具有类似功能的项目
PlayFab Unreal GSDK 插件
[可选] PlayFab Marketplace 插件或 GitHub 上的源代码版本。此插件对于 GSDK 不是必需的,但对于许多 PlayFab 服务(包括登录)是必需的。

C++ 实现

将插件添加到项目

按照以下步骤将 Unreal GSDK 添加到您的项目:

转到您的 Unreal 项目
打开文件资源管理器,在游戏的根目录中创建一个 Plugins 文件夹。在 Plugins 文件夹中,创建一个名为 PlayFabGSDK 的文件夹。
转到 {depot}\GSDK\gsdk\UnrealPlugin。将 UnrealPlugin 文件夹中的所有文件拖到 Plugins/PlayFabGSDK 文件夹中。
最后,使用您选择的文本编辑器打开 {ProjectName}.uproject 文件。在 plugins 数组中,添加 “PlayFabGSDK” 插件。

请参见下面的示例:

{
    "FileVersion": 3,
    "EngineAssociation": "{YourEngineVersion}",
    "Category": "",
    "Description": "",
    "Modules": [
        {
            "Name": "{ProjectName}",
            "Type": "Runtime",
            "LoadingPhase": "Default",
            "AdditionalDependencies": [
                "Engine"
            ]
        }
    ],
    "Plugins": [                    // Add this if it doesn't exist
        {                           // Add this
            "Name": "PlayFabGSDK",  // Add this
            "Enabled": true         // Add this
        }                           // Add this
    ]                               // Add this if it doesn't exist
}

将插件包含在您的模块中

更新 {ProjectName}.Build.cs 文件,将 “PlayFabGSDK” 添加到 PublicDependencyModuleNames.AddRange(); 列表中,如下所示:

PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore", "HeadMountedDisplay", "PlayFabGSDK" });

右键单击 {ProjectName}.uproject 文件并选择 Switch Unreal Engine version 选项,这样您就可以快速检查当前使用的 Unreal Engine 版本。应该会出现下面看到的弹出窗口。如果您已经看到 Unreal Engine 版本是源代码构建,则无需更改任何内容,请单击 Cancel。如果 Unreal 版本当前不是源代码构建,请从下拉列表中选择它,然后单击 OK。

再次右键单击 {ProjectName}.uproject 文件并选择 “Generate Visual Studio Project Files”。
最后,通过选择 Development Editor 配置在 Visual Studio 中构建项目并启动编辑器。

项目设置

一旦您的项目启用了服务器模式,您将拥有一个 {ProjectName}Server.Target.cs 文件。结果应该类似于:

public class {ProjectName}ServerTarget : TargetRules
{
    public {ProjectName}ServerTarget( TargetInfo Target) : base(Target)
    {
        Type = TargetType.Server;
        DefaultBuildSettings = BuildSettingsVersion.V2;
        ExtraModuleNames.AddRange( new string[] { "{ProjectName}" } );

    // You may have additional configuration based on your server needs
    }
}

对于 Windows 构建,您可能需要添加以下可选配置:

DisablePlugins.Add("WMFMediaPlayer");
DisablePlugins.Add("AsyncLoadingScreen"); //if you are using this plugin
DisablePlugins.Add("WindowsMoviePlayer");
DisablePlugins.Add("MediaFoundationMediaPlayer");

注意:这些配置对于 Linux 服务器构建是无效的。

创建/更新 GameInstance 类

创建 GameInstance 类

如果您正在从头开始创建项目,并且尚未拥有 GameInstance 类,请首先按照以下示例说明创建 GameInstance 类。如果您使用的是已经具有 GameInstance 类的项目(例如 Unreal 示例库中的 ShooterGame),请转到标题为 修改 GameInstance 类 的部分。

在 Unreal Editor 中:

选择 Files
选择 Create a new C++ class
选择 Show all classes
在搜索字段中键入 GameInstance
- 按照所述直接选择它,所有内容应该都能正确生成,然后您可以添加我们下面详述的函数
关闭 Unreal 并再次在源代码构建模式下 生成项目文件
使用 Visual Studio,打开这些新创建的文件并按照说明修改 GameInstance 类。

修改 GameInstance 类

根据您项目的设置,您可以使用 C++ 或蓝图修改 GameInstance 类。下面介绍了两种方法,您应该选择适合您需求的那一种。

C++ 实现

找到您的 GameInstance 类,它很可能被命名为类似 {ProjectName}GameInstance 或 MyGameInstance。从现在开始,您的 GameInstance 类将用 [YourGameInstanceClassName] 表示。

修改 GameInstance 头文件

首先,检查 include 语句并确保您的 GameInstance 类 ([YourGameInstanceClassName].h) 的头文件中包含以下内容:

#include "CoreMinimal.h"
#include "Engine/GameInstance.h"
#include "MyGameInstance.generated.h"

[可选] 使用以下代码,用户可以专门为 GameInstance 引入日志通道。或者,使用 LogTemp 进行日志记录就足够了。

DECLARE_LOG_CATEGORY_EXTERN(LogPlayFabGSDKGameInstance, Log, All);

然后,将以下声明添加到 public 部分:(如果您已经有 Init() 函数,则无需再次包含另一个声明)

public:

    virtual void Init() override;
    virtual void OnStart() override;

然后,将以下方法声明添加到 protected 部分:

protected:

    UFUNCTION()
    void OnGSDKShutdown();

    UFUNCTION()
    bool OnGSDKHealthCheck();

    UFUNCTION()
    void OnGSDKServerActive();

    UFUNCTION()
    void OnGSDKReadyForPlayers();

};

修改 GameInstance CPP 文件

然后,找到 [YourGameInstanceClassName].cpp 文件。请确保包含以下内容:

#include "[YourGameInstanceClassName].h"
#include "PlayfabGSDK.h"
#include "GSDKUtils.h"

如果已在头文件中引入自定义日志通道,则需要以下代码:

DEFINE_LOG_CATEGORY(LogPlayFabGSDKGameInstance);

然后找到您的 Init() 函数。如果您还_没有_ Init() 函数,则添加该函数,如下所示:

创建 Init() 函数

void U[YourGameInstanceClassName]::Init()
{
    FOnGSDKShutdown_Dyn OnGSDKShutdown;
    OnGSDKShutdown.BindDynamic(this, &UMyGameInstance::OnGSDKShutdown);
    FOnGSDKHealthCheck_Dyn OnGSDKHealthCheck;
    OnGSDKHealthCheck.BindDynamic(this, &UMyGameInstance::OnGSDKHealthCheck);
    FOnGSDKServerActive_Dyn OnGSDKServerActive;
    OnGSDKServerActive.BindDynamic(this, &UThirdPersonGameInstance::OnGSDKServerActive);
    FOnGSDKReadyForPlayers_Dyn OnGSDKReadyForPlayers;
    OnGSDKReadyForPlayers.BindDynamic(this, &UThirdPersonGameInstance::OnGSDKReadyForPlayers);

    UGSDKUtils::RegisterGSDKShutdownDelegate(OnGSDKShutdown);
    UGSDKUtils::RegisterGSDKHealthCheckDelegate(OnGSDKHealthCheck);
    UGSDKUtils::RegisterGSDKServerActiveDelegate(OnGSDKServerActive);
    UGSDKUtils::RegisterGSDKReadyForPlayersDelegate(OnGSDKReadyForPlayers);
}

如果您已经有 Init() 函数,请检查 [YourGameInstanceClassName].cpp 文件,查看是否有指示实例是否为专用服务器的变量。如果您能找到此变量,请在 Init() 函数的末尾添加以下内容:

修改现有的 Init() 函数

    if (IsDedicatedServerInstance() == true)
    {
        FOnGSDKShutdown_Dyn OnGsdkShutdown;
        OnGsdkShutdown.BindDynamic(this, &UShooterGameInstance::OnGSDKShutdown);
        FOnGSDKHealthCheck_Dyn OnGsdkHealthCheck;
        OnGsdkHealthCheck.BindDynamic(this, &UShooterGameInstance::OnGSDKHealthCheck);
        FOnGSDKServerActive_Dyn OnGSDKServerActive;
        OnGSDKServerActive.BindDynamic(this, &UShooterGameInstance::OnGSDKServerActive);
        FOnGSDKReadyForPlayers_Dyn OnGSDKReadyForPlayers;
        OnGSDKReadyForPlayers.BindDynamic(this, &UShooterGameInstance::OnGSDKReadyForPlayers);

        UGSDKUtils::RegisterGSDKShutdownDelegate(OnGsdkShutdown);
        UGSDKUtils::RegisterGSDKHealthCheckDelegate(OnGsdkHealthCheck);
        UGSDKUtils::RegisterGSDKServerActiveDelegate(OnGSDKServerActive);
        UGSDKUtils::RegisterGSDKReadyForPlayers(OnGSDKReadyForPlayers);
    }

通过调用以下用于为 MPS 设置默认端口的函数来完成 Init() 函数。

#if UE_SERVER
    UGSDKUtils::SetDefaultServerHostPort();
#endif

最后,将这些方法实现添加到 [YourGameInstanceClassName].cpp 文件的底部:

void UMyGameInstance::OnStart()
{
    UE_LOG(LogPlayFabGSDKGameInstance, Warning, TEXT("Reached onStart!"));
    UGSDKUtils::ReadyForPlayers();
}

void UMyGameInstance::OnGSDKShutdown()
{
    UE_LOG(LogPlayFabGSDKGameInstance, Warning, TEXT("Shutdown!"));
    FPlatformMisc::RequestExit(false);
}

bool UMyGameInstance::OnGSDKHealthCheck()
{
    // Uncomment the next line if you want your server to log something at every heartbeat for sanity check.
    /* UE_LOG(LogPlayFabGSDKGameInstance, Warning, TEXT("Healthy!")); */
    return true;
}

void UThirdPersonGameInstance::OnGSDKServerActive()
{
    /**
     * Server is transitioning to an active state.
     * Optional: Add in the implementation any code that is needed for the game server when
     * this transition occurs.
     */
    UE_LOG(LogPlayFabGSDKGameInstance, Warning, TEXT("Active!"));
}

void UThirdPersonGameInstance::OnGSDKReadyForPlayers()
{
    /**
     * Server is transitioning to a StandBy state. Game initialization is complete and the game
     * is ready to accept players.
     * Optional: Add in the implementation any code that is needed for the game server before
     * initialization completes.
     */
    UE_LOG(LogPlayFabGSDKGameInstance, Warning, TEXT("Finished Initialization - Moving to StandBy!"));
}

蓝图实现

只有当您决定继续使用蓝图实现而不是纯 C++ 实现时,才需要这部分。

观察 Unreal Editor 中的 Content Browser 窗口
选择或创建一个文件夹来包含新的蓝图
右键单击并创建一个蓝图类
在 All classes 下拉菜单中,找到您的 GameInstance 类
- 在此示例中,蓝图被命名为 “MyGameInstance”
双击蓝图
在左侧,将鼠标悬停在函数字段上,并选择 Override 下拉菜单
选择 Init 函数
在图表中右键单击并添加所有的注册 GSDK 函数
对于 GSDK Shutdown 和 Maintenance Delegate,从红色方块中拖出一条线,然后选择 “Add Custom Event”
对于 “Register GSDK Health Check Delegate”,在 “Event Dispatchers” 中选择 “Create Event”。
在新节点的下拉菜单中选择 “Create matching function”。这一点很重要,因为 GSDK Health Check Delegate 有一个返回值。
在该函数中,请确保勾选返回布尔值。
不要忘记将所有节点连接到 Event Init 节点。
最后添加 “ReadyforPlayers” 节点,以便能够对 PlayFab 的 ready 信号做出反应。
此外,不要忘记添加 “SetDefaultServerHostPort” 节点以连接到 GSDK 期望的端口。
对于您想要在蓝图中添加的每个 GSDK 函数/节点,您可以通过在新节点中键入函数名称的前几个字母,并查看预期的 GSDK 函数出现在建议中来验证它是否存在。
最后,您的蓝图应该类似于下图所示。

设置 GameInstance 类

创建了与 gsdk 集成的自定义 GameInstance 类后,您必须配置项目以实际使用这个新创建的 GameInstance 类。有两种方法可以做到这一点 - 通过 Unreal Engine 编辑器或直接编辑 DefaultEngine.ini。

在 Unreal Editor 中

在编辑器中,可以通过编辑器中的 UI 设置默认 GameInstance。在编辑器中,转到 Edit -> Project Settings。从打开的窗口中,导航到左侧的 Maps&Modes。滚动到底部,然后您可以直接将 GameInstanceClass 选项设置为您新的 GameInstance 类(避免拼写错误,必须完全匹配)。

在 DefaultEngine.ini 中

或者您可以更新 DefaultEngine.ini 文件并添加以下行:

[/Script/EngineSettings.GameMapsSettings]
GameInstanceClass=/Script/{ProjectName}.MyGameInstance

包括 Windows 专用服务器的先决条件

有两种方法可以包括应用程序本地的先决条件 - 通过 Unreal Engine 编辑器或编辑 DefaultGame.ini。

在 Unreal Editor 中

在编辑器中,转到 Edit -> Project Settings。在打开的窗口中,导航到左侧的 Packaging。滚动到列表底部,然后勾选 “Include app-local prerequisites”。

在 DefaultGame.ini 中

或者您可以使用以下代码更新 DefaultGame.ini:

[/Script/UnrealEd.ProjectPackagingSettings]
IncludeAppLocalPrerequisites=True

如果该类别已经存在于您的 DefaultGame.ini 中,那么只需将第二行添加到其中即可。此配置可确保所有应用程序本地依赖项也随项目一起发布。如果您正在使用持续集成 (CI),您可以将其添加到您的设置中,以便仅在构建专用服务器时打开此标志,这样只有在专用服务器构建时才会添加先决条件的 dll。

XBOX Services

PlayFab

GSDK 项目设置

将 GSDK 添加到项目

目标

要求

C++ 实现

将插件添加到项目

将插件包含在您的模块中

项目设置

创建/更新 GameInstance 类

创建 GameInstance 类

修改 GameInstance 类

C++ 实现

修改 GameInstance 头文件

修改 GameInstance CPP 文件

创建 Init() 函数

修改现有的 Init() 函数

蓝图实现

设置 GameInstance 类

在 Unreal Editor 中

在 DefaultEngine.ini 中

包括 Windows 专用服务器的先决条件

在 Unreal Editor 中

在 DefaultGame.ini 中

后续步骤

​将 GSDK 添加到项目

​目标

​要求

​C++ 实现

​将插件添加到项目

​将插件包含在您的模块中

​项目设置

​创建/更新 GameInstance 类

​创建 GameInstance 类

​修改 GameInstance 类

​C++ 实现

修改 GameInstance 头文件

修改 GameInstance CPP 文件

创建 Init() 函数

修改现有的 Init() 函数

​蓝图实现

​设置 GameInstance 类

​在 Unreal Editor 中

​在 DefaultEngine.ini 中

​包括 Windows 专用服务器的先决条件

​在 Unreal Editor 中

​在 DefaultGame.ini 中

​后续步骤

将 GSDK 添加到项目

目标

要求

C++ 实现

将插件添加到项目

将插件包含在您的模块中

项目设置

创建/更新 GameInstance 类

创建 GameInstance 类

修改 GameInstance 类

C++ 实现

蓝图实现

设置 GameInstance 类

在 Unreal Editor 中

在 DefaultEngine.ini 中

包括 Windows 专用服务器的先决条件

在 Unreal Editor 中

在 DefaultGame.ini 中

后续步骤