Unreal SDK

Native C++ and Blueprint support for Passport authentication, wallet operations, and blockchain data queries.

Who is this for? Game developers using Unreal Engine who want to integrate web3 features, NFTs, and blockchain functionality into their games.

Platform Compatibility

Unreal Engine Version	Windows	macOS	iOS	Android
5.5.x	✅ Full support	✅ Full support	⚠️ Beta	⚠️ Beta
5.4.x	✅ Full support	✅ Full support	⚠️ Beta	⚠️ Beta
5.3.x	✅ Full support	✅ Full support	⚠️ Beta	⚠️ Beta
5.2.x and below	❌ Not supported	❌ Not supported	❌ Not supported	❌ Not supported

Platform Requirements: Requirements depend on your Unreal Engine version. Use the version selector in Unreal’s documentation to view requirements for your engine:

Legacy Versions (4.26, 4.27, 5.0): These versions are not officially supported and require the BLUI plugin workaround. We strongly recommend using UE 5.3+ for new projects. See the Legacy Versions accordion below.

Mobile Platforms (iOS & Android): Not officially supported.

Prerequisites

Unreal Engine: 5.3 or later (5.4 and 5.5 recommended)
Git LFS: The SDK repository uses Git Large File Storage to manage .uasset and .umap files. Install Git LFS before cloning or the plugin may fail to download binary dependencies correctly.

Installation

Install Git LFS
Git LFS must be installed before adding the SDK. The SDK contains .uasset and .umap files stored in Git LFS that won’t download correctly otherwise.
Add the SDK to your project’s Plugins directory:

Git Clone
Git Submodule
Download Release

From your project’s root directory:

git clone https://github.com/immutable/unreal-immutable-sdk.git Plugins/unreal-immutable-sdk

From your project’s root directory:

git submodule add https://github.com/immutable/unreal-immutable-sdk.git Plugins/unreal-immutable-sdk

Download from GitHub Releases
Extract the archive
Copy to your project’s Plugins/unreal-immutable-sdk folder

Restart the Unreal Editor
Legacy Unreal Engine Versions (4.26, 4.27, 5.0): Additional BLUI plugin installation required. See Legacy Versions Setup in the overview.

Your project structure should look like:

Root/
└── Plugins/
    └── unreal-immutable-sdk/

Enable the Immutable module in your Build.cs:

Source/YourGame/YourGame.Build.cs

PublicDependencyModuleNames.AddRange(new string[] {
    "Core", "CoreUObject", "Engine", "InputCore",
    "Immutable"  // Add this
});

For mobile platforms, see Platform Setup.

Legacy Versions (4.26, 4.27, 5.0) - BLUI Setup Required

Not Officially Supported: Unreal Engine 4.26, 4.27, and 5.0 are not officially supported. We strongly recommend using UE 5.3+ for new projects.

For Unreal Engine 4.26, 4.27, and 5.0, you must install the BLUI plugin because Epic’s WebBrowserWidget uses an outdated CEF version incompatible with the SDK.

More on why we use BLUI plugin can be found in the FAQ.

1. Download BLUIDownload or clone from immutable-BLUI to your project’s Plugins folder.2. Rename the folderRename immutable-BLUI to BLUI. Your plugins directory should look like:

MyGame/
└── Plugins/
    ├── BLUI/
    └── unreal-immutable-sdk/

3. Disable WebBrowserWidgetEdit unreal-immutable-sdk/Immutable.uplugin and set WebBrowserWidget to disabled:

{
  "Plugins": [
    {
      "Name": "WebBrowserWidget",
      "Enabled": false
    }
  ]
}

4. Configure Hub

Hub Configuration Required: In Immutable Hub, you MUST add file://* to the Web Origin URLs field in your Passport client configuration. Without this, the BLUI embedded browser cannot communicate with the Passport SDK and authentication will fail.

Navigate to your project in Immutable Hub
Go to Passport → Clients → Select your client
Add file://* to the Web Origin URLs field
Save changes

Platform-Specific Configuration

Unreal Engine 5.3+: This version uses the Modern Xcode workflow with per-project configuration files. Follow the platform-specific instructions below for your target platforms.

Windows
macOS
Android
iOS

Platform Requirements

Windows: 10 or later

No additional configuration required for Windows builds.

Platform Requirements

macOS: 10.15 or later

URL Scheme Configuration

Locate your project’s .plist template file at <YourProject>/Build/Mac/Resources/Info.Template.plist
- You can find the path in Mac: Info.plist Template in Project Settings (shows as /Game/Build/Mac/Resources/Info.Template.plist)
- If it doesn’t exist, Unreal will create it when you first generate project files
Add the following inside the root <dict>...</dict>:

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>mygame</string>
        </array>
    </dict>
</array>

Using a custom file: You can create your own .plist file and update Mac: Info.plist Template in Project Settings to point to your custom file for more control.

Editing the engine’s Info.plist at Engine/Source/Runtime/Launch/Resources/Mac/Info.plist will affect all projects using that engine installation. Use project-specific .plist files instead. See Epic’s Modern Xcode docs for details.

Platform Requirements

Minimum Android Version: 10 or later (API Level 24+)
Target API: 33 or higher recommended

Deep Link Configuration

Create Source/<YourProject>/<YourProject>_UPL_Android.xml:

<?xml version="1.0" encoding="utf-8"?>
<root xmlns:android="http://schemas.android.com/apk/res/android">
  <androidManifestUpdates>
    <addElements tag="application">
      <activity android:name="com.immutable.unreal.RedirectActivity" android:exported="true">
        <intent-filter android:autoVerify="true">
          <action android:name="android.intent.action.VIEW" />
          <category android:name="android.intent.category.DEFAULT" />
          <category android:name="android.intent.category.BROWSABLE" />
          <data android:host="callback" android:scheme="mygame" />
          <data android:host="logout" android:scheme="mygame" />
        </intent-filter>
      </activity>
    </addElements>
  </androidManifestUpdates>
</root>

Modify Source/<YourProject>/<YourProject>.Build.cs:

public class YourProject : ModuleRules
{
    public YourProject(ReadOnlyTargetRules Target) : base(Target)
    {
        if (Target.Platform == UnrealTargetPlatform.Android)
        {
            string PluginPath = Utils.MakePathRelativeTo(ModuleDirectory, Target.RelativeEnginePath);
            AdditionalPropertiesForReceipt.Add("AndroidPlugin", Path.Combine(PluginPath, "YourProject_UPL_Android.xml"));
        }
    }
}

Platform Requirements

iOS Version: 15.2 or later

URL Scheme Configuration

Extra PList Data (Recommended)
Template .plist (UE 5.3+)
Premade .plist (UE 5.3+)

Go to Project Settings → Platforms → iOS
Under Extra PList Data, add:

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>mygame</string>
        </array>
    </dict>
</array>

Locate your project’s .plist template file at <YourProject>/Build/IOS/UBTGenerated/Info.Template.plist
- You can find the path in IOS / TVOS: Info.plist Template in Project Settings (shows as /Game/Build/IOS/UBTGenerated/Info.Template.plist)
Add the following inside the root <dict>...</dict>:

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>mygame</string>
        </array>
    </dict>
</array>

Using a custom file: If you want to avoid UBT potentially overwriting the default template, create your own .plist file (you can use Info.Template.plist as a starting point) and update IOS / TVOS: Info.plist Template in Project Settings to point to your custom file.

UBT auto-generates the default iOS template and may overwrite changes. See Epic’s Modern Xcode docs for details.

Create a complete .plist file at <YourProject>/Build/IOS/Resources/MyGameIOS.plist
Add your URL scheme and all required iOS app settings:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleURLTypes</key>
    <array>
        <dict>
            <key>CFBundleURLSchemes</key>
            <array>
                <string>mygame</string>
            </array>
        </dict>
    </array>
    <!-- Add other required iOS app settings here -->
</dict>
</plist>

Edit <YourProject>/Config/DefaultEngine.ini and add:

[/Script/MacTargetPlatform.XcodeProjectSettings]
PremadeIOSPlist=(FilePath="/Game/Build/IOS/Resources/MyGameIOS.plist")

Premade vs Template: A premade .plist is a complete, finalized file that Xcode will NOT modify. This gives you absolute control but requires managing all iOS app settings yourself. See Epic’s Modern Xcode docs for details.

The SDK handles deep links automatically. Ensure your redirect URIs match your configured URL scheme.

Your redirect URIs (like mygame://callback) must use the same URL scheme that you configure in your platform settings:

iOS: Only the scheme needs to match (e.g., mygame in mygame://callback)
Android: Both the scheme AND host must match (e.g., mygame and callback in mygame://callback)

See Initialize Passport for authentication setup.

auto InitData = FImmutablePassportInitData
{
    TEXT("YOUR_CLIENT_ID"),
    TEXT("mygame://callback"),
    TEXT("mygame://logout"),
    TEXT("sandbox"),
    ...
};

Passport->Initialize(InitData, ...);

Next Steps

Getting Started

Configure Your Project

Set up credentials and OAuth client in Immutable Hub

Authentication

Initialize Passport and implement login

Wallet Operations

Access wallet addresses and balances

Game Bridge Architecture

Understand SDK internals and custom engine integration

Additional Resources

Sample Game

Complete sample project

FAQ

Common questions and troubleshooting

GitHub

SDK source code and examples

TypeScript

Unity

Unreal

Platform Compatibility

Prerequisites

Installation

Platform-Specific Configuration

Platform Requirements

Platform Requirements

URL Scheme Configuration

Platform Requirements

Deep Link Configuration

Platform Requirements

URL Scheme Configuration

Next Steps

Getting Started

Configure Your Project

Authentication

Wallet Operations

Game Bridge Architecture

Additional Resources

Sample Game

FAQ

GitHub

TypeScript

Unity

Unreal

​Platform Compatibility

​Prerequisites

​Installation

​Platform-Specific Configuration

​Platform Requirements

​Platform Requirements

​URL Scheme Configuration

​Platform Requirements

​Deep Link Configuration

​Platform Requirements

​URL Scheme Configuration

​Next Steps

​Getting Started

Configure Your Project

Authentication

Wallet Operations

Game Bridge Architecture

​Additional Resources

Sample Game

FAQ

GitHub

Platform Compatibility

Prerequisites

Installation

Platform-Specific Configuration

Platform Requirements

Platform Requirements

URL Scheme Configuration

Platform Requirements

Deep Link Configuration

Platform Requirements

URL Scheme Configuration

Next Steps

Getting Started

Additional Resources