Set up the Unreal SDK #

This tutorial involves setting up and integrating the Pragma Unreal SDK. This includes generating the Pragma SDK sources, integrating it into an Unreal project, initializing it, and logging in to the Pragma backend with a test user.

Unreal example project #

This tutorial is based on a new Unreal project using the Third Person Unreal project template. The example project is named ‘Unicorn’, update your references accordingly.

This tutorial was built and tested using Unreal 5.3.X, see the SDK overview for the full sdk compatibility chart.

Relative paths #

Relative paths start from the pragma engine repo root or the Unreal project root respectively.

  • pragma-engine\platform\pragma-cli.ini -> ~\[pragma_repo_root_dir]\pragma-engine\platform\pragma-cli.ini
  • Plugins\PragmaSDK -> ~\[game_repo_root_dir]\Unicorn\Plugins\PragmaSDK

SDK code generation config #

In your pragma project config file, ensure the sdk type is set to Unreal:

pragma-engine\platform\pragma-cli.ini

sdk = unreal

Set up the Pragma SDK Plugin #

  1. Copy pragma-engine\sdk\unreal4\update-pragma-sdk.sh to your Unreal project Plugins directory (Unicorn\Plugins)
    • The Pragma sdk unreal4 directory is compatible with Unreal 5– it hasn’t been renamed for compatibility reasons.
    • Create the Plugins directory at the top of your Unreal project if it is absent.
  2. Update the copied update-pragma-sdk.sh file:
    • Uncomment and set SOURCE_ENGINE_RELATIVE_FOLDER to the relative path of your pragma-engine directory.
      • eg. SOURCE_ENGINE_RELATIVE_FOLDER="../../pragma-engine"
    • Uncomment and set TARGET_PRAGMA_SDK_DIR to PragmaSDK
      • eg. TARGET_PRAGMA_SDK_DIR="PragmaSDK"
  3. Stop pragma engine if it’s running locally.
  4. Run update-pragma-sdk.sh in git bash from the plugins directory
    cd Unicorn/Plugins
./update-pragma-sdk.sh
  5. Confirm the PragmaSDK folder and sources now exist in your Unreal Plugins directory.

Configure the Pragma SDK #

  1. In Unreal, add PragmaSDK and PragmaSDKAux to the PublicDependencyModuleNames array:

Source\Unicorn\Unicorn.Build.cs

PublicDependencyModuleNames.AddRange(
    new string[] {
        // ...
        , "PragmaSDK", "PragmaSDKAux"
    }
);
  1. Add the following configuration properties.

Config\DefaultGame.ini

[/Script/PragmaSDK.PragmaSdkConfig]
BackendAddress="http://127.0.0.1:10000"
GameClientVersion="DefaultGameClientVersion"

Enabling verbose logging will log all backend API calls which is helpful during integration. This can be reduced / disabled later to reduce noise.

Config\DefaultEngine.ini

[Core.Log]
LogPragma=VeryVerbose
  1. Build your Unreal project now that the PragmaSDK plugin is included.

Initialize the Pragma LocalPlayerSubsystem #

Pragma provides a LocalPlayerSubsystem that initializes the Pragma SDK and establishes a connection to the backend.

This code can be placed wherever it makes sense based on how the game is initialized, this example uses a PlayerController and GameModeBase.

Set up the Player Controller #

  1. If one doesn’t already exist, create a PlayerController class (eg. UnicornPlayerController)
  2. Add the following code:

Source\Unicorn\UnicornPlayerController.h

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/PlayerController.h"
#include "PragmaPtr.h"
#include "UnicornPlayerController.generated.h"

PRAGMA_FWD(FPlayer);

UCLASS()
class UNICORN_API AUnicornPlayerController : public APlayerController
{
    GENERATED_BODY()

public:
    virtual void BeginPlay() override;
    
    UFUNCTION(Exec)
    void LogIn(const FString& Username);
    
    UFUNCTION(Exec)
    void LogOut();
    
private:
    Pragma::FPlayerPtr Player;
};

Source\Unicorn\UnicornPlayerController.cpp

#include "UnicornPlayerController.h"
#include "PragmaPlayer.h"
#include "PragmaLocalPlayerSubsystem.h"

void AUnicornPlayerController::BeginPlay()
{
    Super::BeginPlay();
    
    const auto* Pragma = GetLocalPlayer()->GetSubsystem<UPragmaLocalPlayerSubsystem>();
    Player = Pragma->Player();
    
    // Log in using a built-in test account.
    // Accounts test01 - test20 are available by default.
    LogIn("test01");
}

void AUnicornPlayerController::LogIn(const FString& Username)
{
    Player->LogIn(
        EPragma_Account_IdProvider::UNSAFE,
        Username,
        Pragma::FPlayer::FLoggedInDelegate::CreateWeakLambda(
            this, [this, Username = Username](const TPragmaResult<>& Result)
            {
                if (Result.IsSuccessful())
                {
                    UE_LOG(LogTemp, Display, TEXT("Pragma -- Logged in as user %s."),
                        *Username);
                }
                else
                {
                    UE_LOG(LogTemp, Error, TEXT("Pragma -- Login failed: %s"),
                        *Result.GetErrorAsString());
                }
            }));
}

void AUnicornPlayerController::LogOut()
{
    Player->LogOut(
        Pragma::FPlayer::FLoggedOutDelegate::CreateWeakLambda(
            this, []
            {
                UE_LOG(LogTemp, Display, TEXT("Pragma -- Logged out."));
            }));
}
  1. If not already completed, register the PlayerController with your GameMode

Source\Unicorn\UnicornGameMode.cpp

#include "UnicornPlayerController.h"

// ...

AUnicornGameMode::AUnicornGameMode()
{
    // ...
    PlayerControllerClass = AUnicornPlayerController::StaticClass();
}

Run the game #

  1. Ensure Pragma is running via ./pragma run or the Intellij run-pragma run configuration.
  2. Run the game
  3. Confirm the login was successful via the log: Pragma -- Logged in as user test01.
  4. Success!

Recap #

We’ve generated the Pragma SDK, initialized the LocalPlayerSubsystem and logged in using a test account. Move this functionality to its proper lifecycle location within the game flow as needed and build out from there.

Next we’ll demonstrate how to initialize and call Pragma services.


Overview
Invoke a Pragma RPC