> ## 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.

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

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

<Info>
  **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)
</Info>

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

<Warning>
  **Mobile Platforms (iOS & Android)**: Not officially supported.
</Warning>

## 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.
   </Warning>

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

<Tabs>
  <Tab title="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>

  <Tab title="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>

  <Tab title="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
  </Tab>
</Tabs>

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](/docs/sdks/unreal/overview#platform-specific-configuration) in the overview.
   </Warning>

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](/docs/sdks/unreal/overview#platform-specific-configuration).

<Accordion title="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.
  </Warning>

  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.

  <Info>
    More on why we use BLUI plugin can be found in the [FAQ](/docs/sdks/unreal/faq).
  </Info>

  **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.
  </Warning>

  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
</Accordion>

## Platform-Specific Configuration

<Info>
  **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.
</Info>

<Tabs>
  <Tab title="Windows">
    ### Platform Requirements

    * **Windows**: 10 or later

    No additional configuration required for Windows builds.
  </Tab>

  <Tab title="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>
    ```

    <Info>
      **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.
    </Info>

    <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.
    </Warning>
  </Tab>

  <Tab title="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>

  <Tab title="iOS">
    ### Platform Requirements

    * **iOS Version**: 15.2 or later

    ### URL Scheme Configuration

    <Tabs>
      <Tab title="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>

      <Tab title="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>
        ```

        <Info>
          **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.
        </Info>

        <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.
        </Warning>
      </Tab>

      <Tab title="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")
        ```

        <Info>
          **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.
        </Info>
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

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

<Info>
  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](/docs/products/passport/authentication#initialize-passport) for authentication setup.
</Info>

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

<CardGroup cols={2}>
  <Card title="Configure Your Project" icon="gear" href="https://hub.immutable.com">
    Set up credentials and OAuth client in Immutable Hub
  </Card>

  <Card title="Authentication" icon="key" href="/docs/products/passport/authentication">
    Initialize Passport and implement login
  </Card>

  <Card title="Wallet Operations" icon="wallet" href="/docs/products/passport/wallet">
    Access wallet addresses and balances
  </Card>

  <Card title="Game Bridge Architecture" icon="sitemap" href="/docs/sdks/game-bridge-architecture">
    Understand SDK internals and custom engine integration
  </Card>
</CardGroup>

### Additional Resources

<CardGroup cols={2}>
  <Card title="FAQ" icon="circle-question" href="/docs/sdks/unreal/faq">
    Common questions and troubleshooting
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/immutable/unreal-immutable-sdk">
    SDK source code and examples
  </Card>
</CardGroup>