Documentation

Did you find this helpful?

Unreal CPP Getting Started

This guide will help you make your first API call in Unreal, using the PlayFab C++ SDK.

Unreal Project Setup

  • OS: This guide is written for Windows 10, however steps should be similar for Mac
  • This guide is created for using Visual Studio 2017, and Unreal Engine 4.x (Usually latest)
  • Download Unreal Engine
    • Register and log in on the Unreal website
    • Download the Epic Games Launcher
      • https://www.unrealengine.com/dashboard
      • Open Epic Games Launcher
        • Select the "Unreal Engine" tab, and "Library" from the left-navigation-bar
        • Click "+Add Versions"
        • Select the latest version supported by the SDK readme
        • Click the "Launch" button, and run Unreal Engine
        • Select all the optons as seen here:
          • New Project tab, C++ sub-tab, No Starter Content
          • Remember your path - referenced as {UeCppLocation} for the rest of this guide
            NewProjectCpp.png#asset:862
        • This will launch an Unreal Editor window, and Visual Studio
          • Stop, and close everything
  • Install the PlayFab Plugin into your project
    • Download and extract the PlayFab UnrealCppSdk - Extracted location referenced as {PlayFabSdkLocation} for the rest of this guide
    • Open two windows explorer folders, {UeCppLocation} and {PlayFabSdkLocation}
      • In {UeCppLocation}, create a new subfolder called "Plugins", and open it
      • In {PlayFabSdkLocation}, navigate to the {PlayFabSdkLocation}/PlayFabSDK/Plugins subfolder
      • Select the "PlayFab" folder from {PlayFabSdkLocation}/PlayFabSDK/Plugins and copy it into {UeCppLocation}/Plugins
      • Navigate back up to {UeCppLocation}, and right-click your "GettingStartedUeCpp.uproject" (your .uproject file name will match your project name from earlier)
      • Select "Generate Visual Studio project files"
      • When the popup completes, re-open GettingStartedUeCpp.sln in Visual Studio
        GenVsProjCpp.png#asset:863
  • Run Unreal, Create a new actor, and place it in the scene
    • We are using an actor to trigger an API call - You can make API calls from any C++ code
    • From Visual Studio, Run Unreal Engine (Debug -> Start Debugging)
    • Create a new actor (This screenshot shows multiple sequential popups, you won't see all of this at once):
      NewActorCpp.png#asset:864
    • Place the actor in the scene
      PlaceActor.png#asset:865
    • Once again, stop and close Unreal (Keep Visual Studio open)
      • We need to modify LoginActor in Visual Studio in the next section
  • PlayFab Installation Complete!

Set up your first API call

This guide will provide the minimum steps to make your first PlayFab API call. Confirmation will be done via a debug print in the Output Log.

  • Update the contents of {UeCppLocation}/Source/GettingStartedUeCpp/GettingStartedUeCpp.Build.cs
    • Find a line that starts with: PublicDependencyModuleNames, It will look something like this:
      • PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore" });
    • Add "PlayFab" to this list:
      • PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore", "PlayFab" });
    • Save and close the file
  • Navigate to the LoginActor.h and LoginActor.h files created in the previous section
    • They are most likely located here:
      • {UeCppLocation}/Source/GettingStartedUeCpp/Private/LoginActor.h
      • {UeCppLocation}/Source/GettingStartedUeCpp/Private/LoginActor.cpp
  • Replace the contents of LoginActor.h with the following:

#pragma once

#include "GameFramework/Actor.h"

#include "PlayFab.h"
#include "Core/PlayFabClientDataModels.h"
#include "Core/PlayFabClientAPI.h"

#include "LoginActor.generated.h"

UCLASS()
class ALoginActor : public AActor
{
    GENERATED_BODY()
public: 
    ALoginActor();
    virtual void BeginPlay() override;
    void OnSuccess(const PlayFab::ClientModels::FLoginResult& Result) const;
    void OnError(const PlayFab::FPlayFabError& ErrorResult) const;

    virtual void Tick( float DeltaSeconds ) override;
private:
    PlayFabClientPtr clientAPI = nullptr;
};

  • And Replace the contents of LoginActor.cpp with the following:

#include "GettingStartedUeCpp.h"
#include "LoginActor.h"

ALoginActor::ALoginActor()
{
    PrimaryActorTick.bCanEverTick = true;
}

void ALoginActor::BeginPlay()
{
    Super::BeginPlay();

    clientAPI = IPlayFabModuleInterface::Get().GetClientAPI();
    clientAPI->SetTitleId(TEXT("144"));

    PlayFab::ClientModels::FLoginWithCustomIDRequest request;
    request.CustomId = TEXT("GettingStartedGuide");
    request.CreateAccount = true;

    clientAPI->LoginWithCustomID(request,
        PlayFab::UPlayFabClientAPI::FLoginWithCustomIDDelegate::CreateUObject(this, &ALoginActor::OnSuccess),
        PlayFab::FPlayFabErrorDelegate::CreateUObject(this, &ALoginActor::OnError)
    );
}

void ALoginActor::OnSuccess(const PlayFab::ClientModels::FLoginResult& Result) const
{
    UE_LOG(LogTemp, Log, TEXT("Congratulations, you made your first successful API call!"));
}

void ALoginActor::OnError(const PlayFab::FPlayFabError& ErrorResult) const
{
    UE_LOG(LogTemp, Error, TEXT("Something went wrong with your first API call.\nHere's some debug information:\n%s"), *ErrorResult.GenerateErrorReport());
}

void ALoginActor::Tick( float DeltaTime )
{
    Super::Tick( DeltaTime );
}

  • Run the Unreal Editor (Debug -> Start Debugging)

Finish and Execute

  • Earlier, you created a level with a LoginActor entity already placed in the world
    • Load this level
  • Press Play
    • You will immediately see the following in the output log:
    • LogTemp: Congratulations, you made your first successful API call!
  • Done! Press any key to close

Deconstruct the code

This optional last section describes the code in this project line by line.

  • GettingStartedUeCpp.Build.cs
    • To reference code from a plugin in your project, you have to add the plugin to your code dependencies. The Unreal build tools do all the work, if you add the "PlayFab" string to your plugins
  • LoginActor.H
    • includes
      • The LoginActor includes are default includes that exist for the template file before we modified it
      • The PlayFab includes are neccessary to make PlayFab API calls
    • UCLASS ALoginActor
      • Most of this file is the default template for a new actor; the only exceptions to this are:
    • OnSuccess and OnError
      • These are the asynchronous callbacks that will be invoked after PlayFab LoginWithCustomID completes
    • PlayFabClientPtr clientAPI
      • This is an object that lets you access the PlayFab client API
  • LoginActor.cpp
    • Most of this file is the default template for a new actor; the only exceptions to this are:
    • clientAPI = IPlayFabModuleInterface::Get().GetClientAPI();
      • This fetches the clientAPI object from the PlayFab plugin, so you can make API calls with it
    • clientAPI->SetTitleId(TEXT("xxxx"));
      • Every PlayFab developer creates a title in Game Manager. When you publish your game, you must code that titleId into your game. This lets the client know how to access the correct data within PlayFab. For most users, just consider it a mandatory step that makes PlayFab work.
    • PlayFab::ClientModels::FLoginWithCustomIDRequest request;
      • Most PlayFab API methods require input parameters, and those input parameters are packed into a request object
      • Every API method requires a unique request object, with a mix of optional and mandatory parameters
        • For LoginWithCustomIDRequest, there is a mandatory parameter of CustomId, which uniquely identifies a player and CreateAccount, which allows the creation of a new account with this call.
    • clientAPI->LoginWithCustomID(request, {OnSuccess delegate}, {OnFail delegate});
    • {OnSuccess delegate}: PlayFab::UPlayFabClientAPI::FLoginWithCustomIDDelegate::CreateUObject(this, &ALoginActor::OnSuccess)
      • combined with: void ALoginActor::OnSuccess(const PlayFab::ClientModels::FLoginResult& Result) const
      • These create a UObject callback/delegate which is called if your API call is successful
      • An API Result object will contain the requested information, according to the API called
        • FLoginResult contains some basic information about the player, but for most users, login is simply a mandatory step before calling other APIs.
    • {OnFail delegate} PlayFab::FPlayFabErrorDelegate::CreateUObject(this, &ALoginActor::OnError)
      • combined with: void ALoginActor::OnError(const PlayFab::FPlayFabError& ErrorResult) const
      • API calls can fail for many reasons, and you should always attempt to handle failure
      • Why API calls fail (In order of likelihood)
        • PlayFabSettings.TitleId is not set. If you forget to set titleId to your title, then nothing will work.
        • Request parameters. If you have not provided the correct or required information for a particular API call, then it will fail. See error.errorMessage, error.errorDetails, or error.GenerateErrorReport() for more info.
        • Device connectivity issue. Cell-phones lose/regain connectivity constantly, and so any API call at any time can fail randomly, and then work immediately after. Going into a tunnel can disconnect you completely.
        • PlayFab server issue. As with all software, there can be issues. See our release notes for updates.
        • The internet is not 100% reliable. Sometimes the message is corrupted or fails to reach the PlayFab server.
      • At this time, the PlayFab Unreal C++ SDK maintains state with static variables which are non atomic and are not guarded by synchronization techniques. For this reason, we recommend limiting PlayFab calls to within the main Unreal thread.
      • If you are having difficulty debugging an issue, and the information within the error information is not sufficient, please visit us on our forums



Did you find this helpful?