Skip to main content

Unreal SDK

The Immutable SDK for Unreal helps you integrate your game with Immutable Passport.

Sections

Compatibility and Suport Details​

💡Supported Platforms
  • Windows (64-bit)
  • macOS (minimum version 10.5)
  • Android (minimum version 8.0)
  • iOS (minimum version 15.2)
💡Supported Unreal Versions
💡Note
Our Unreal SDK is designed to be compatible with all versions of Unreal Engine. While the SDK is intended to work seamlessly across all versions, we have conducted comprehensive testing with the following versions. If you encounter compilation errors or any issues integrating with the Immutable plugin, you can report them directly through the issues section in our GitHub repository.
💡Unreal Engine SDK Compatibility
Build PlatformUnreal Engine VersionPackage Platform
WindowsMacOSiOSAndroid
Windows4.2.6✅❌❌❌
5.0.3✅❌❌✅
5.2.1✅❌❌✅
5.3.2✅❌❌✅
macOS5.3.2❌✅✅✅

Registering your game​

Authentication methods​

There are two methods to authenticate and authorise players into Passport:

  1. Authorisation Code Flow with Proof Key for Code Exchange (PKCE) is available for Android, iOS, macOS. This method provides a seamless and secure authentication experience by opening a pop-up window on macOS or an in-app browser on mobile devices. Players are automatically redirected back to the game once authenticated, eliminating manual switching.

  2. Device Code Authorisation is available for Windows, Android, iOS and macOS. This method opens the player's default browser and guides them through the authentication flow.

💡Recommendation
Whenever possible, use the PKCE flow as it is the most secure and seamless method for authentication on Android, iOS and macOS.

Configure your application in Immutable Hub​

To configure your application, follow these steps: head to the Immutable Hub and proceed with the following:

  1. Go to the Immutable Hub and create a new project along with a testnet environment.
  2. Register your application as an OAuth 2.0 Native client
  3. Go to the Passport configuration screen and create a Passport client for the testnet environment you just set up. Refer to the table below for guidance.
PropertyField RequiredDescription
Application TypeYesYou must register your application as an OAuth 2.0 Native client.
Client NameYesThe name you wish to use to identify your application.
Logout URLsYesThe deep link where the browser will redirect to after logout is complete. It can be mygame://logout.
Note: replace mygame with your application name.
Redirect URLsYesThe deep link where the browser will redirect to after login is complete. It can be mygame://callback.
Note: replace mygame with your application name.
Web Origin URLsDepends- For Unreal Engine versions 4.26 - 5.0 (inclusive). Add file://* to the list of Web Origins URLs. This is required to work with BLUI browser.
- For Unreal Engine 5.1 and above you may leave it blank.

  1. If you're using PKCE and working on Android, iOS, or macOS, you'll need to follow these additional steps. Please refer to the collapsible sections corresponding to your platform.

    Android
    1. Create an Unreal Plugin Language XML file (e.g. Source/MyGame/MyGame_UPL_Android.xml) and add the following code:
    <?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>
    1. Open your game's build file (e.g. Source/MyGame/MyGame.Build.cs) and add:
    if (Target.Platform == UnrealTargetPlatform.Android)
    {
      string MyPath = Utils.MakePathRelativeTo(ModuleDirectory, Target.RelativeEnginePath);
      AdditionalPropertiesForReceipt.Add("AndroidPlugin", Path.Combine(MyPath, "MyGame_UPL_Android.xml"));
    }

    Your game will now open when the device processes any link that starts with mygame://callback or mygame://logout.

    iOS
    1. In Unreal Editor go to Project Settings -> iOS -> Extra PList Data
    2. Add the following code inside the Additional Plist Data field:
    <key>CFBundleURLTypes</key><array><dict><key>CFBundleURLSchemes</key><array><string>mygame</string></array></dict></array>

    After this set-up and the redirect URI you set in Initialize Passport, your game can log in using mygame://callback.

    macOS

    Since there is no way to add extra plist data like iOS from the Unreal Editor Project Settings, you will need to edit the Engine's default Info.plist.

    1. In your preferred IDE, open the engine's Info.plist file (e.g. Engine/Source/Runtime/Launch/Resources/Mac/Info.plist)
    2. Add the following code inside the root <dict>...</dict>:
    <key>CFBundleURLTypes</key>
    <array>
        <dict>
            <key>CFBundleURLSchemes</key>
            <array>
                <string>mygame</string>
            </array>
        </dict>
    </array>

    After setting up and specifying the redirect URI in Initialize Passport, the user will be automatically redirected back to the game through mygame://callback upon completing the login process.

💡Tip
See the Sample Game for an example of how to set up Device Code Authorisation Flow on Windows and macOS.

Installation​

  1. Since .uasset and .umap files are stored on Git Large File Storage, you must download and install git-lfs from here before cloning the respository
  2. Clone the unreal-immutable-sdk repository or download the zip/tarball from one of the versions here
  3. Copy the cloned repo into your project's Plugins folder, e.g.: MyGame/Plugins/unreal-immutable-sdk
  4. Restart your project (Unreal Editor & Jetbrains Rider IDE), upon restart it should load the unreal-sdk-plugin and should be good to use
💡Unreal Engine 4 and 5.0 additional requirements
  • For Unreal Engine 4.26, 4.27, and 5.0, we use BLUI plugin instead of WebBrowserWidget plugin.
  • Please disable WebBrowserWidget plugin in the immutable.uplugin file, which can be found at the root of the unreal-immutable-sdk folder, e.g. MyGame/Plugins/unreal-immutable-sdk/immutable.uplugin, and restart your UE4 editor.
    {
      "Plugins": [
      {
       "Name": "WebBrowserWidget"
       "Enabled": false
      }
     ]
    }
  • Download or clone BLUI from https://github.com/immutable/immutable-BLUI to your project's Plugins folder. Then rename the folder immutable-BLUI folder to BLUI. Your projects plugin directory should look like
    MyGame/
    |__Plugins/
      |__BLUI/
      |__unreal-immutable-sdk/
⚠️Warning
Please make sure your project is properly configured in the Immutable Hub before attempting to log in to Passport, especially if you're developing your game in Unreal Engine 4.26, 4.27, or 5.0. Pay special attention when configuring Web Origins URLs.
💡Note
More on why we use BLUI plugin can be found in the FAQ
⚠️Warning
The Xsolla plugin is not compatible with the Immutable plugin. For more information, please refer to the FAQ

Setup​

Blueprint​

See the included sample widgets in All->Plugins->Immutable Content in the Unreal Editor content browser for examples of how to use the plugin in Blueprint. If you don't see a Plugins folder under All you may need to enable Show Plugin Content in the content browser's Settings menu.

C++​

Check out the ImmutablePassport.h file for the C++ Passport API. In order to know the list of methods to call for the Passport Login Flow and the Passport Log out Flow, follow the same sequence of steps as the Blueprint widget examples below.

Quick Start​

Log into Passport​

PKCE (Recommended for Android, iOS and macOS)
Device Code Authorisation
💡Info
The environment argument can be one of the following:

EnvironmentDescription
sandboxThe default test network (currently, it is Sepolia)
productionThe Ethereum mainnet network

Stored Credentials​

Once the gamer is connected to Passport, the SDK will store your credentials (access, ID, and refresh tokens). If you assign UseCachedSession to true, while using Login blueprint node, stored credentials will be used to re-login the gamer. If re-login fails, it will fall back to Device Code Authorisation.

💡Note
To re-login the gamer to Passport using the saved credentials, you may use one of the following functions:
- UImmutablePassport::ConnectPKCE
- UImmutablePassport::LoginPKCE

Initialise the provider and wallet​

In order to interact with Immutable zkEVM, you will need to instantiate the Passport's zkEVM provider via ConnectEvm. Then, ZkEvmRequestAccounts blueprint node must be called to initialise the gamer's wallet and retrieve their wallet address.

PKCE (Recommended for Android, iOS and macOS)
Device Code Authorisation
⚠️Warning
The gamer will not have a wallet unless ZkEvmRequestAccounts is called.
⚠️Warning
ZkEvmRequestAccounts is a resource-intensive function. To ensure optimal gaming experience and performance, it is recommended to call this function separately or asynchronously from the login process. For example, call Login to log users into the game and let them start playing:
  • In the background, call ConnectEvm and ZkEvmRequestAccounts functions to initialise their wallet and get their address.
  • Or later, when users need to use their wallet, call ConnectEvm and ZkEvmRequestAccounts functions to initialise their wallet and get their address.

Log out of Passport​

To initiate the logout process in Passport, utilise the Logout node demonstrated below. Two logout options are available:

  1. Hard Logout: This option clears sessions from both the SDK (local) and the browser used for login. The SDK will open a browser to clear the browser session during the logout process.
    • Note, after the browser session has been cleared, the browser will redirect back to the Logout Uri configured in the Initialize Passport Blueprint node. If the Logout Uri is not set, Passport will use the logout URI configured in the Immutable Hub client settings.
    • When performing a hard logout on Windows, it's recommended to have a dedicated logout page to redirect users to.
    • See the Passport Logout docs for more info.
  2. Soft Logout: If there is a desire to bypass opening the browser during the logout process, set the DoHardLogout parameter to false. This will perform only a local logout, and gamers will remain logged in to Passport in the browser until the session expires.
    • If a user attempts to log back in before the session in the browser expires, they will be automatically logged back in with the session stored in the browser. Please use the hard logout method above if you want the next login to go through the complete login flow.

Passport Logout Blueprint

zkEVM Send Transaction​

💡Note

Games can only use ERC-20 tokens issued by the game itself, meaning currencies like ETH, USDC, IMX, USDT, etc. cannot be used in-game.

📋Prerequisites
  • The zkEVM send transaction requires pre-approval.
  • Must have first called ConnectEvm to set up the zkEVM provider and ZkEvmRequestAccounts to login the user.

To send a transaction on zkEVM use UImmutablePassport::ZkEvmSendTransaction or UImmutablePassport::ZkEvmSendTransactionWithConfirmation methods. There are three parameters you need to provide in order to execute one of the send transaction methods :

  • to: The destination address
  • value: The value to transfer for the transaction in wei
  • data: Byte string containing the associated data of the message

This method does not support the gas, gasPrice, maxPriorityFeePerGas, or maxFeePerGas properties as the relayer abstracts these away from the user. Additionally, the from property is not supported as the user's Passport wallet address is used instead.

See the blueprint examples below, demonstrating how to use zkEVM send transaction methods.

Sends a transaction to the network, signs it using the logged-in Passport account, and waits for the transaction to be included in a block.

Zk Evm Send Transaction with Confirmation

Supported Functionality​

MethodDescription
InitializePassportInitialises Passport
LoginLogs into Passport using Device Code Authorisation.

If useCachedSession is true, stored credentials will be used to re-login the gamer. If re-login fails, it will fall back to Device Code Authorisation.
LoginPKCE(Android, iOS and macOS only) Logs into Passport using Authorization Code Flow with Proof Key for Code Exchange (PKCE)
LogoutLogs out Passport
HasStoredCredentialsChecks if there are stored credits from the previous login
GetEmailGets the email address associated with the wallet address
GetAccessTokenGets Passport user's access token
GetIdTokenGets Passport user's ID token
GetLinkedAddressesGets the list of external wallets the user has linked to their Passport account via the Dashboard.
ConnectEvmInitialises the zkEVM provider
ZkEvmRequestAccountsInitialises the gamer's Passport wallet and retrieves their wallet address
ZkEvmGetBalanceGets the balance of the given address in wei
ZkEvmSendTransactionSends a transaction to the network and signs it using the logged-in Passport account.
ZkEvmSendTransactionWithConfirmationSimilar to ZkEvmSendTransaction.

Sends a transaction to the network, signs it using the logged-in Passport account, and waits for the transaction to be included in a block.
ZkEvmGetTransactionReceiptRetrieves the transaction information of a given transaction hash. This function uses the Ethereum JSON-RPC eth_getTransactionReceipt method.
ZkEvmSignTypedDataV4Signs the EIP-712 structured message in JSON string format using the logged-in Passport account.

Examples​

  • Sample Blueprints - see the sample blueprints for examples of how to use the Immutable Unreal SDK.
  • Sample Game - see the sample game for an example of how to use the Immutable Unreal SDK.

Further documentation​

IMX Whitepaper • IMX Tokenomics • Block Explorer • Careers • Contact Us