> ## Documentation Index
> Fetch the complete documentation index at: https://docs.immutable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Unreal SDK

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

> [!NOTE]
>
> **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 |

> [!NOTE]
>
> **Platform Requirements**: Requirements depend on your Unreal Engine version. Use the version selector in Unreal's documentation to view requirements for your engine:
>
> * [Windows](https://dev.epicgames.com/documentation/en-us/unreal-engine/setting-up-visual-studio-development-environment-for-cplusplus-projects-in-unreal-engine)
> * [macOS](https://dev.epicgames.com/documentation/en-us/unreal-engine/macos-development-requirements-for-unreal-engine)
> * [Android](https://dev.epicgames.com/documentation/en-us/unreal-engine/android-support-for-unreal-engine)
> * [iOS](https://dev.epicgames.com/documentation/en-us/unreal-engine/setting-up-an-unreal-engine-project-for-ios)

> [!WARNING]
>
> **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.

> [!WARNING]
>
> **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](https://git-lfs.github.com/) to manage `.uasset` and `.umap` files. Install Git LFS before cloning or the plugin may fail to download binary dependencies correctly.

## Installation

1. Install [Git LFS](https://git-lfs.github.com/)

   > [!WARNING]
   >
   > 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.

2. Add the SDK to your project's `Plugins` directory:

> [tab] Git Clone
>
> From your project's root directory:
>
> ```bash theme={null}
> git clone https://github.com/immutable/unreal-immutable-sdk.git Plugins/unreal-immutable-sdk
> ```

> [tab] Git Submodule
>
> From your project's root directory:
>
> ```bash theme={null}
> git submodule add https://github.com/immutable/unreal-immutable-sdk.git Plugins/unreal-immutable-sdk
> ```

> [tab] Download Release
>
> 1. Download from [GitHub Releases](https://github.com/immutable/unreal-immutable-sdk/releases)
> 2. Extract the archive
> 3. Copy to your project's `Plugins/unreal-immutable-sdk` folder

3. Restart the Unreal Editor

   > [!WARNING]
   >
   > **Legacy Unreal Engine Versions (4.26, 4.27, 5.0)**: Additional BLUI plugin installation required. See [Legacy Versions Setup](https://docs.immutable.com/docs/sdks/unreal/overview.md#platform-specific-configuration) in the overview.

Your project structure should look like:

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

4. Enable the Immutable module in your Build.cs:

```cpp title="Source/YourGame/YourGame.Build.cs" theme={null}
PublicDependencyModuleNames.AddRange(new string[] {
    "Core", "CoreUObject", "Engine", "InputCore",
    "Immutable"  // Add this
});
```

For mobile platforms, see [Platform Setup](https://docs.immutable.com/docs/sdks/unreal/overview.md#platform-specific-configuration).

> [accordion] Legacy Versions (4.26, 4.27, 5.0) - BLUI Setup Required
>
> > [!WARNING]
> >
> > **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.
>
> > [!NOTE]
> >
> > More on why we use BLUI plugin can be found in the [FAQ](https://docs.immutable.com/docs/sdks/unreal/faq.md).
>
> **1. Download BLUI**
>
> Download or clone from [immutable-BLUI](https://github.com/immutable/immutable-BLUI) to your project's `Plugins` folder.
>
> **2. Rename the folder**
>
> Rename `immutable-BLUI` to `BLUI`. Your plugins directory should look like:
>
> ```
> MyGame/
> └── Plugins/
>     ├── BLUI/
>     └── unreal-immutable-sdk/
> ```
>
> **3. Disable WebBrowserWidget**
>
> Edit `unreal-immutable-sdk/Immutable.uplugin` and set `WebBrowserWidget` to disabled:
>
> ```json theme={null}
> {
>   "Plugins": [
>     {
>       "Name": "WebBrowserWidget",
>       "Enabled": false
>     }
>   ]
> }
> ```
>
> **4. Configure Hub**
>
> > [!WARNING]
> >
> > **Hub Configuration Required**: In [Immutable Hub](https://hub.immutable.com), 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.
>
> 1. Navigate to your project in Immutable Hub
> 2. Go to **Passport** → **Clients** → Select your client
> 3. Add `file://*` to the **Web Origin URLs** field
> 4. Save changes

## Platform-Specific Configuration

> [!NOTE]
>
> **Unreal Engine 5.3+**: This version uses the [Modern Xcode workflow](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-modern-xcode-in-unreal-engine) with per-project configuration files. Follow the platform-specific instructions below for your target platforms.

> [tab] Windows
>
> ### Platform Requirements
>
> * **Windows**: 10 or later
>
> No additional configuration required for Windows builds.

> [tab] macOS
>
> ### Platform Requirements
>
> * **macOS**: 10.15 or later
>
> ### URL Scheme Configuration
>
> 1. 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
> 2. Add the following inside the root `<dict>...</dict>`:
>
> ```xml theme={null}
> <key>CFBundleURLTypes</key>
> <array>
>     <dict>
>         <key>CFBundleURLSchemes</key>
>         <array>
>             <string>mygame</string>
>         </array>
>     </dict>
> </array>
> ```
>
> > [!NOTE]
> >
> > **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.
>
> > [!WARNING]
> >
> > 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](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-modern-xcode-in-unreal-engine#.plistfiles) for details.

> [tab] Android
>
> ### Platform Requirements
>
> * **Minimum Android Version**: 10 or later (API Level 24+)
> * **Target API**: 33 or higher recommended
>
> ### Deep Link Configuration
>
> 1. Create `Source/<YourProject>/<YourProject>_UPL_Android.xml`:
>
> ```xml theme={null}
> <?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>
> ```
>
> 2. Modify `Source/<YourProject>/<YourProject>.Build.cs`:
>
> ```csharp theme={null}
> 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"));
>         }
>     }
> }
> ```

> [tab] iOS
>
> ### Platform Requirements
>
> * **iOS Version**: 15.2 or later
>
> ### URL Scheme Configuration
>
> > [tab] Extra PList Data (Recommended)
> >
> > 1. Go to **Project Settings** → **Platforms** → **iOS**
> > 2. Under **Extra PList Data**, add:
> >
> > ```xml theme={null}
> > <key>CFBundleURLTypes</key>
> > <array>
> >     <dict>
> >         <key>CFBundleURLSchemes</key>
> >         <array>
> >             <string>mygame</string>
> >         </array>
> >     </dict>
> > </array>
> > ```
>
> > [tab] Template .plist (UE 5.3+)
> >
> > 1. 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`)
> > 2. Add the following inside the root `<dict>...</dict>`:
> >
> > ```xml theme={null}
> > <key>CFBundleURLTypes</key>
> > <array>
> >     <dict>
> >         <key>CFBundleURLSchemes</key>
> >         <array>
> >             <string>mygame</string>
> >         </array>
> >     </dict>
> > </array>
> > ```
> >
> > > [!NOTE]
> > >
> > > **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.
> >
> > > [!WARNING]
> > >
> > > UBT auto-generates the default iOS template and may overwrite changes. See [Epic's Modern Xcode docs](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-modern-xcode-in-unreal-engine#.plistfiles) for details.
>
> > [tab] Premade .plist (UE 5.3+)
> >
> > 1. Create a complete `.plist` file at `<YourProject>/Build/IOS/Resources/MyGameIOS.plist`
> >
> > 2. Add your URL scheme and all required iOS app settings:
> >
> > ```xml theme={null}
> > <?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>
> > ```
> >
> > 3. Edit `<YourProject>/Config/DefaultEngine.ini` and add:
> >
> > ```ini theme={null}
> > [/Script/MacTargetPlatform.XcodeProjectSettings]
> > PremadeIOSPlist=(FilePath="/Game/Build/IOS/Resources/MyGameIOS.plist")
> > ```
> >
> > > [!NOTE]
> > >
> > > **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](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-modern-xcode-in-unreal-engine#useapremade.plist) for details.

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

> [!NOTE]
>
> 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](https://docs.immutable.com/docs/products/passport/authentication.md#initialize-passport) for authentication setup.

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

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

## Next Steps

### Getting Started

> [card] [Configure Your Project](https://hub.immutable.com)
>
> Set up credentials and OAuth client in Immutable Hub

> [card] [Authentication](https://docs.immutable.com/docs/products/passport/authentication.md)
>
> Initialize Passport and implement login

> [card] [Wallet Operations](https://docs.immutable.com/docs/products/passport/wallet.md)
>
> Access wallet addresses and balances

> [card] [Game Bridge Architecture](https://docs.immutable.com/docs/sdks/game-bridge-architecture.md)
>
> Understand SDK internals and custom engine integration

### Additional Resources

> [card] [FAQ](https://docs.immutable.com/docs/sdks/unreal/faq.md)
>
> Common questions and troubleshooting

> [card] [GitHub](https://github.com/immutable/unreal-immutable-sdk)
>
> SDK source code and examples


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.