將 GSDK 新增至專案

本文說明如何升級現有專案，使其可以裝載在 PlayFab 多人遊戲伺服器 (MPS) 上。此程序涉及將 PlayFab GSDK 新增並設定至 Unreal 專案中。這裡的指示是使用 Unreal ThirdPersonMP 範本專案撰寫的。請注意，您的 Unreal 專案必須具備下列功能：

網路
多人遊戲
專用遊戲伺服器

如果沒有，您需要返回範例專案設定指南，將您的專案設定為具有專用伺服器功能、已啟用網路功能的多人遊戲。

目標

我們將在您的專案中新增並設定 PlayFab Unreal GSDK，並在本機進行測試，以確認它預期可以在 PlayFab 多人遊戲服務上運作。

需求

下載 Visual Studio。Community 版本是免費的。
- 必要的工作負載：.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”。
最後，在 Visual Studio 中建置專案，並選取 Development Editor 設定以啟動編輯器。

顯示 Visual Studio 中以 Development Editor 模式建置之選項的影像

專案設定

專案啟用伺服器模式後，您會有一個 {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，並再次以原始程式碼組建模式 Generate project files
使用 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 函式
在圖表中按一下滑鼠右鍵，並新增所有 register 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 的就緒信號。
此外，別忘了新增 “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。

後續步驟

您現在已準備好在本機電腦上建置專案。或者，您可以返回主要的 Unreal GSDK 外掛程式指南。

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 中

後續步驟