Ajouter le GSDK au projet

Cet article explique comment mettre à niveau un projet existant afin qu’il puisse être hébergé sur PlayFab Multiplayer Servers (MPS). Le processus consiste à ajouter et à configurer le PlayFab GSDK dans un projet Unreal. Les instructions présentées ici utilisent le projet modèle Unreal ThirdPersonMP. Notez que votre projet Unreal doit disposer des fonctionnalités suivantes :

Mise en réseau
Multijoueur
Serveur de jeu dédié

Si ce n’est pas le cas, vous devez revenir au guide Configuration de l’exemple de projet pour configurer votre projet en tant que jeu multijoueur compatible réseau, doté de fonctionnalités de serveur dédié.

Objectifs

Nous allons ajouter et configurer le GSDK Unreal PlayFab dans votre projet, puis le tester localement pour vérifier qu’il devrait fonctionner sur PlayFab Multiplayer Services.

Exigences

Téléchargez Visual Studio. La version Community est gratuite.
- Charges de travail requises : Développement .NET Desktop et Développement Desktop en C++
Téléchargez le code source d’Unreal Engine. Pour obtenir des instructions, consultez Downloading Unreal Engine Source code (externe).
Un exemple de projet ThirdPersonMP finalisé, ou un projet doté de fonctionnalités similaires
Le plug-in PlayFab Unreal GSDK
[Facultatif] Le plug-in PlayFab de la Marketplace ou la version source sur GitHub. Ce plug-in n’est pas requis pour le GSDK, mais il est nécessaire pour de nombreux services PlayFab, dont la connexion.

Implémentation C++

Ajouter le plug-in au projet

Suivez ces étapes pour ajouter le GSDK Unreal à votre projet :

Accédez à votre projet Unreal
Ouvrez l’Explorateur de fichiers et créez un dossier Plugins dans le répertoire racine de votre jeu. Dans le dossier Plugins, créez un dossier appelé PlayFabGSDK.
Accédez à {depot}\GSDK\gsdk\UnrealPlugin. Faites glisser tous les fichiers du dossier UnrealPlugin dans le dossier Plugins/PlayFabGSDK.
Enfin, ouvrez le fichier {ProjectName}.uproject dans l’éditeur de texte de votre choix. Dans le tableau plugins, ajoutez le plug-in “PlayFabGSDK”.

Consultez l’exemple ci-dessous :

{
    "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
}

Inclure le plug-in dans vos modules

Mettez à jour le fichier {ProjectName}.Build.cs pour ajouter “PlayFabGSDK” à la liste PublicDependencyModuleNames.AddRange(); comme suit :

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

Cliquez avec le bouton droit sur le fichier {ProjectName}.uproject et sélectionnez l’option Switch Unreal Engine version, qui vous permet de vérifier rapidement la version d’Unreal Engine que vous utilisez actuellement. La fenêtre contextuelle ci-dessous devrait s’afficher. Si la version d’Unreal Engine indiquée est déjà la build source, vous n’avez rien à modifier : cliquez sur Cancel. Si la version d’Unreal n’est pas actuellement la build source, sélectionnez-la dans la liste déroulante, puis cliquez sur OK.

Image d'une fenêtre indiquant "Select Unreal Engine Version"

Cliquez de nouveau avec le bouton droit sur le fichier {ProjectName}.uproject et sélectionnez “Generate Visual Studio Project Files”.
Enfin, générez le projet dans Visual Studio et démarrez l’éditeur en sélectionnant la configuration Development Editor.

Image de Visual Studio avec l'option de génération en mode Development Editor

Configuration du projet

Une fois le mode serveur activé dans votre projet, vous disposez d’un fichier {ProjectName}Server.Target.cs. Le résultat devrait ressembler à ceci :

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
    }
}

Pour les builds Windows, vous devrez peut-être ajouter ces configurations facultatives :

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

REMARQUE : ces configurations ne sont pas valides pour une build de serveur Linux.

Créer/mettre à jour la classe GameInstance

Créer une classe GameInstance

Si vous créez un projet de A à Z et ne disposez pas encore d’une classe GameInstance, suivez d’abord ces exemples d’instructions pour créer une classe GameInstance. Si vous utilisez un projet qui dispose déjà d’une classe GameInstance (par exemple, ShooterGame de la bibliothèque d’exemples d’Unreal), passez à la section intitulée Modifier la classe GameInstance.

Dans l’éditeur Unreal :

Sélectionnez Files
Sélectionnez Create a new C++ class
Sélectionnez Show all classes
Saisissez GameInstance dans le champ de recherche
- En la sélectionnant directement comme décrit, tout devrait être généré correctement ; vous pourrez ensuite ajouter les fonctions détaillées ci-dessous
Fermez Unreal et exécutez de nouveau Generate project files en mode build source
Dans Visual Studio, ouvrez ces fichiers nouvellement créés et suivez les instructions pour modifier la classe GameInstance.

Modifier la classe GameInstance

Selon la configuration de votre projet, vous pouvez modifier la classe GameInstance en C++ ou à l’aide de Blueprints. Les deux méthodes sont présentées ci-dessous ; choisissez celle qui correspond à vos besoins.

Implémentation C++

Recherchez votre classe GameInstance, qui s’appelle très probablement {ProjectName}GameInstance, MyGameInstance ou un nom similaire. Dans la suite, votre classe GameInstance est désignée par [YourGameInstanceClassName].

Modifier le fichier d’en-tête de GameInstance

Commencez par vérifier les instructions include et assurez-vous que les éléments suivants sont inclus dans le fichier d’en-tête de votre classe GameInstance ([YourGameInstanceClassName].h) :

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

[Facultatif] Avec le code suivant, l’utilisateur peut introduire un canal de journalisation propre à GameInstance. La journalisation avec LogTemp suffit également.

DECLARE_LOG_CATEGORY_EXTERN(LogPlayFabGSDKGameInstance, Log, All);

Ajoutez ensuite les déclarations suivantes à la section public : (si vous disposez déjà d’une fonction Init(), il n’est pas nécessaire d’inclure une autre déclaration)

public:

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

Ajoutez ensuite les déclarations suivantes à la section protected des méthodes :

protected:

    UFUNCTION()
    void OnGSDKShutdown();

    UFUNCTION()
    bool OnGSDKHealthCheck();

    UFUNCTION()
    void OnGSDKServerActive();

    UFUNCTION()
    void OnGSDKReadyForPlayers();

};

Modifier le fichier CPP de GameInstance

Recherchez ensuite le fichier [YourGameInstanceClassName].cpp. Assurez-vous que les éléments suivants sont inclus :

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

Si le canal de journalisation personnalisé a été introduit dans le fichier d’en-tête, le code suivant est nécessaire :

DEFINE_LOG_CATEGORY(LogPlayFabGSDKGameInstance);

Recherchez ensuite votre fonction Init(). Si vous n’avez pas encore de fonction Init(), ajoutez-la comme suit :

Créer la fonction 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);
}

Si vous disposiez déjà d’une fonction Init(), vérifiez dans le fichier [YourGameInstanceClassName].cpp si vous avez une variable indiquant si l’instance est destinée à un serveur dédié. Si vous trouvez cette variable, ajoutez ce qui suit à la fin de votre fonction Init() :

Modifier la fonction Init() existante

    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);
    }

Terminez la fonction Init() en appelant la fonction suivante, qui configure le port par défaut pour MPS.

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

Enfin, ajoutez ces implémentations de méthodes à la fin du fichier [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!"));
}

Implémentation Blueprint

Cette partie n’est nécessaire que si vous avez choisi l’implémentation Blueprint plutôt que l’implémentation purement C++.

Observez la fenêtre Content Browser de l’éditeur Unreal
Choisissez ou créez un dossier pour contenir les nouveaux Blueprints
Cliquez avec le bouton droit et créez une classe Blueprint
Dans le menu déroulant All classes, recherchez votre classe GameInstance
- Dans cet exemple, le Blueprint s’appelle “MyGameInstance”
Double-cliquez sur le Blueprint
À gauche, pointez sur le champ des fonctions et sélectionnez la liste déroulante Override
Sélectionnez la fonction Init
Cliquez avec le bouton droit dans le graphe et ajoutez toutes les fonctions d’inscription du GSDK
Pour les délégués GSDK Shutdown et Maintenance, faites glisser une ligne depuis le carré rouge et sélectionnez “Add Custom Event”
Pour “Register GSDK Health Check Delegate”, sélectionnez “Create Event” dans “Event Dispatchers”.
Dans la liste déroulante du nouveau nœud, sélectionnez “Create matching function”. C’est important, car le délégué GSDK Health Check a une valeur de retour.
Dans la fonction, assurez-vous que la valeur booléenne de retour est cochée.
N’oubliez pas de connecter tous les nœuds au nœud Event Init.
Enfin, ajoutez le nœud “ReadyforPlayers” pour pouvoir réagir au signal de disponibilité de PlayFab.
N’oubliez pas non plus d’ajouter le nœud “SetDefaultServerHostPort” pour vous connecter au port attendu par le GSDK.
Pour chaque fonction ou nœud du GSDK que vous souhaitez ajouter à votre Blueprint, vous pouvez vérifier qu’il existe en saisissant les premières lettres du nom de la fonction dans votre nouveau nœud : la fonction GSDK attendue doit apparaître dans les suggestions.
Au final, votre Blueprint devrait ressembler à celui présenté dans l’image ci-dessous.

Définir la classe GameInstance

Après avoir créé une classe GameInstance personnalisée intégrée au GSDK, vous devez configurer votre projet pour qu’il utilise réellement cette nouvelle classe GameInstance. Il existe deux façons de procéder : via l’éditeur Unreal Engine ou en modifiant directement DefaultEngine.ini.

Dans l’éditeur Unreal

Dans l’éditeur, la GameInstance par défaut peut être définie via l’interface utilisateur. Dans l’éditeur, accédez à Edit -> Project Settings. Dans la fenêtre qui s’ouvre, accédez à Maps&Modes sur la gauche. Faites défiler jusqu’en bas : vous pouvez alors définir directement l’option GameInstanceClass sur votre nouvelle classe GameInstance (évitez les fautes de frappe : la correspondance doit être exacte).

Dans DefaultEngine.ini

Vous pouvez également mettre à jour le fichier DefaultEngine.ini et y ajouter les lignes suivantes :

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

Inclure les prérequis pour le serveur dédié Windows

Il existe deux façons d’inclure les prérequis locaux de l’application : via l’éditeur Unreal Engine ou en modifiant DefaultGame.ini.

Dans l’éditeur Unreal

Dans l’éditeur, accédez à Edit -> Project Settings. Dans la fenêtre qui s’ouvre, accédez à Packaging sur la gauche. Faites défiler jusqu’au bas de la liste et cochez “Include app-local prerequisites”.

Dans DefaultGame.ini

Vous pouvez également mettre à jour DefaultGame.ini avec le code suivant :

[/Script/UnrealEd.ProjectPackagingSettings]
IncludeAppLocalPrerequisites=True

Si la catégorie existe déjà dans votre DefaultGame.ini, ajoutez-y simplement la deuxième ligne. Cette configuration garantit que toutes les dépendances locales de l’application sont également fournies avec le projet. Si vous utilisez l’intégration continue (CI), vous pouvez l’ajouter à votre configuration de manière à n’activer cet indicateur que lors de la génération d’un serveur dédié ; ainsi, les DLL prérequises ne sont ajoutées que pour les builds de serveur dédié.

Étapes suivantes

Vous êtes maintenant prêt à générer votre projet sur votre machine locale. Vous pouvez également revenir au guide principal du plug-in Unreal GSDK.

XBOX Services

PlayFab

Configuration du GSDK dans le projet

Ajouter le GSDK au projet

Objectifs

Exigences

Implémentation C++

Ajouter le plug-in au projet

Inclure le plug-in dans vos modules

Configuration du projet

Créer/mettre à jour la classe GameInstance

Créer une classe GameInstance

Modifier la classe GameInstance

Implémentation C++

Modifier le fichier d’en-tête de GameInstance

Modifier le fichier CPP de GameInstance

Créer la fonction Init()

Modifier la fonction Init() existante

Implémentation Blueprint

Définir la classe GameInstance

Dans l’éditeur Unreal

Dans DefaultEngine.ini

Inclure les prérequis pour le serveur dédié Windows

Dans l’éditeur Unreal

Dans DefaultGame.ini

Étapes suivantes

​Ajouter le GSDK au projet

​Objectifs

​Exigences

​Implémentation C++

​Ajouter le plug-in au projet

​Inclure le plug-in dans vos modules

​Configuration du projet

​Créer/mettre à jour la classe GameInstance

​Créer une classe GameInstance

​Modifier la classe GameInstance

​Implémentation C++

Modifier le fichier d’en-tête de GameInstance

Modifier le fichier CPP de GameInstance

Créer la fonction Init()

Modifier la fonction Init() existante

​Implémentation Blueprint

​Définir la classe GameInstance

​Dans l’éditeur Unreal

​Dans DefaultEngine.ini

​Inclure les prérequis pour le serveur dédié Windows

​Dans l’éditeur Unreal

​Dans DefaultGame.ini

​Étapes suivantes

Ajouter le GSDK au projet

Objectifs

Exigences

Implémentation C++

Ajouter le plug-in au projet

Inclure le plug-in dans vos modules

Configuration du projet

Créer/mettre à jour la classe GameInstance

Créer une classe GameInstance

Modifier la classe GameInstance

Implémentation C++

Implémentation Blueprint

Définir la classe GameInstance

Dans l’éditeur Unreal

Dans DefaultEngine.ini

Inclure les prérequis pour le serveur dédié Windows

Dans l’éditeur Unreal

Dans DefaultGame.ini

Étapes suivantes