Skip to main content
Version: 20 Mar 2024

Getting Started With Unreal Engine

The Magic Leap 2 SDK for Unreal Engine 5 (Magic Leap 2 Unreal SDK) lets you create apps for Magic Leap 2 devices using Unreal Engine, the game engine created by Epic Games.

Most functionality in the Magic Leap 2 Unreal SDK is exposed through OpenXR, the Android dependencies required for Unreal Engine, or built-in features of Unreal Engine. Some optional functionality requires the Magic Leap Native API SDK (Magic Leap 2 C SDK). For a list of supported features and description of how they are exposed, see Supported Features for Unreal Engine.

note

If you're new to developing apps for the Magic Leap 2 devices, see our Developer Tools guides for more information on getting started.

Prerequisites​

  • This release is supported only on Windows. For information on system requirements for running Unreal Engine 5 on Windows, see Hardware and Software Requirements in the Unreal Engine 5 documentation site.
  • To clone the Magic Leap fork of the Unreal Engine source code from the Unreal Engine repository, you need a GitHub account and an Epic Games account.
  • Visual Studio 2022 is recommended. Visual Studio 2019 is also supported. If you want to use Visual Studio 2019, customize your Unreal Engine GenerateProjectFiles.bat file for that version. If you haven’t installed Visual Studio for use with Unreal Engine before, see Setting Up Visual Studio in the Unreal Engine 5 documentation site.
  • Android dependencies. Setting up Android for this release requires different versions of Android Studio and Android SDK and NDK than what’s described in How to Set Up Android SDK and NDK For Your Unreal Engine Development Environment in the Unreal Engine 5 documentation site. See Install Android dependencies in this guide for instructions.
tip

You’ll be building the Unreal Engine from source code, which can take several hours or more.

Setup Unreal Engine and the Magic Leap 2 Unreal SDK​

The version of Unreal Engine for Magic Leap is located in a fork of the Epic Games Unreal Engine GitHub repository. The Magic Leap 2 Unreal SDK is available from the Magic Leap Hub.

Remote Rendering and Unreal Engine​

Magic Leap Remote Rendering runs apps you create on a desktop computer and streams them to Magic Leap 2 devices.

Starting with Magic Leap 2 Unreal SDK version 1.3.0, you use either the Unreal Engine binary available to download on the Unreal Engine website or the Unreal Engine source code in the Unreal Engine repository to create apps that run using Remote Rendering. Apps created with the Unreal Engine binary can't be packaged to run directly on Magic Leap 2 devices. To package apps to run on Magic Leap 2 devices, you'll need the Unreal Engine source code in the Unreal Engine repository.

If you are using a verison of the Magic Leap 2 Unreal SDK prior to 1.3.0, you'll need Unreal Engine source code to create apps to run using Remote Rendering or package to run on Magic Leap 2 devices.

You can find instructions for setting up Magic Leap Remote Rendering and using it with Unreal Engine 5 on the Magic Leap 2 developer portal. See Remote Rendering service and Remote Rendering with Unreal Engine 5.

note

The Magic Leap Application Simulator is not supported for Unreal Engine.

Get access to the Unreal Engine repository​

To get access to the Epic Games Unreal Engine GitHub repository, follow the instructions on this page on the Unreal Engine website: Accessing Unreal Engine source code on GitHub.

Install the Magic Leap Hub​

You’ll need the Magic Leap Hub to download the Magic Leap 2 Unreal SDK and examples. If you don’t already have the Magic Leap Hub installed:

  1. Go to the developer tools download page on the Magic Leap 2 developer portal and install the Windows version of the Magic Leap Hub.
  2. Run the installer and complete the setup wizard.
  3. Go to the Microsoft Visual C++ Redistributable latest supported downloads page. Install the X64 redistributables for Visual Studio 2015, 2017, 2019, and 2022.

Install the ML C SDK (optional)​

Installing the ML C SDK is optional. If you aren't going to use the features supported through the ML C SDK, you don't need to install it. See Supported Features for Unreal Engine.

  1. Launch the Magic Leap Hub. Click Open on the Package Manager tile.
  2. Click the Native tile.
  3. Download and install ML C SDK.
  4. Set the ML C SDK environment variable to the download location.

You can use Windows Settings to add a persistent environment variable:

  1. In the Windows Settings search field, search for "environment".
  2. Choose Edit the system environment variables. In the System Properties dialog that appears, make sure the Advanced tab is selected.
  3. Click Environment Variables.
    The Windows System Properties window with Environment Variables selected
  4. In the Environment Variables dialog that appears, click New under this list of users variables.
    New User Variable window in Environment Variables setting
  5. Create a user variable named MLSDK with value %USERPROFILE%\MagicLeap\mlsdk\<MLSDK_VERSION>.
  6. Click OK to close each of the dialogs.

Install Android dependencies​

If you don’t already have OpenJDK-11 installed:

  1. Download the Windows binary of OpenJDK-11 from https://jdk.java.net/java-se-ri/11.
  2. Extract the zip file and move the jdk-11 folder to your %USERPROFILE% directory.
  3. Set your JAVA_HOME environment variable to the path of the jdk-11 folder. You can do this through Windows Settings.

When you install Android Studio, you'll need to install it in the default location. If you already have a version of Android Studio installed, this might prevent the version you need for Unreal Engine from being installed in the default location. For example, if you have Unity Editor installed, then you already have Android Studio installed. If you already have Android Studio installed, we recommend uninstalling it or renaming the directory where it is installed to a name that is different from the default install location. Note that this means you won't be able to use Unreal Engine at the same time as Unity Editor or other software that requires a different version of Android Studio than the one Unreal Engine uses.

To set up the versions of the Android SDK and Android NDK required for this release, you’ll need to install Android Studio Electric Eel, 2022.1.1 Patch 2. This isn’t the latest version or the version recommended in the Unreal Engine 5 documentation.

  1. Go to the Android Studio download site. You might have to accept the terms and conditions to see the list of releases.
  2. In the list of Android Studio downloads, find Android Studio Electric Eel, 2022.1.1 Patch 2. Download the Windows (64-bit) installer.
  3. Install Android Studio Electric Eel, 2022.1.1 Patch 2. Accept the default installation location. Start Android Studio when the installation is complete.
  4. In the Android Studio welcome window, click More Actions and select SDK Manager.
  5. In the SDK Platforms tab of the Android SDK Manager, select Android SDK 10 (Q) API Level 29.
  6. Select the SDK Tools tab of the Android SDK Manager. Select Show Package Details.
  7. Scroll down to NDK (side by side). Select Android NDK version 25.1.8937393 and install it.
  8. Scroll down to Android SDK Command-line Tools and select *9.0**.
  9. Scroll down to Cmake. Select Cmake version 3.22.1.
  10. Click OK to install everything you selected in the Android SDK Manager. Click OK to confirm the changes.
  11. Click Finish to close the Android SDK Manager.

Download the Unreal Engine source code​

To download the version of the Unreal Engine source code for this release, clone it from the Magic Leap fork of the Epic Games GitHub repository:

  1. Log in to GitHub with the credentials for your public GitHub account.
  2. In Windows Command Prompt, run this command:
git clone --single-branch -b 5.3-release-ml2-updated https://github.com/MagicLeapUnreal/UnrealEngine.git

The --single-branch argument is optional. It reduces the size of the download.

note

This GitHub branch has been update since the initial general availability release of Magic Leap 2 Unreal SDK. If you are using Magic Leap 2 Unreal SDK version 1.3.0 or later, clone branch 5.3-release-ml2-updated. For any earlier version, clone branch 5.3-release-ml2.

Optional: Switching to another branch​

The --single-branch argument reduces the size of the download by pulling only the target branch. If you used the --single-branch argument and then want to switch to a different branch, you can do either of the following:

  • Clone the repo again using the new branch.

  • Use these commands in your existing repo and then check out the new branch:

git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"

git fetch origin

Download the Magic Leap 2 Unreal SDK​

To download the Magic Leap 2 Unreal SDK from the Magic Leap Hub:

  1. Launch the Magic Leap Hub. Click Open on the Package Manager tile.

  2. In the Bundles tab, select the Unreal tile.

  3. Select Unreal in Change Summary to download the ML Unreal SDK, documentation, sample apps, and integration tests. Click Apply Changes to download.

    The Package Manager with Unreal selected

Set up plugins​

Set up the plugins in the ML Unreal SDK as Engine plugins. You can copy the ML Unreal SDK plugins to your preferred location or create a symbolic link.

To copy the ML Unreal SDK plugins to the Unreal Engine folder as engine plugins:

  1. In the unreal-sdk folder, copy the Plugins folder and move it to this folder within the UnrealEngine folder: Engine\Plugins\Runtime.
  2. Rename the copied folder in the UnrealEngine folder to MagicLeap.

To link ML Unreal SDK plugins as engine plugins:

  1. Open the Windows Command Prompt.
  2. Change to this folder within the UnrealEngine folder: Engine\Plugins\Runtime
  3. Run this command:
mklink /d MagicLeap $UNREAL-SDK\Plugins
tip

You might need elevated privileges to create a symbolic link. Make sure you run the Windows Command prompt from an account that has administrator privileges. If you still get a message saying you don’t have sufficient privileges to run the mklink command, make sure your Windows computer has the Developer Mode setting enabled.

Run the setup and project generation files​

  1. In the Windows Command Prompt window, go to the UnrealEngine folder. The setup and project generation files are in this folder.

  2. Go to the Engine\Extras\Android folder. Open SetupAndroid.bat in notepad or another text editor.

  3. Change the path on line 86 from set SDKMANAGER=%STUDIO_SDK_PATH%\cmdline-tools\latest\bin\sdkmanager.bat to reflect the version of the Android SDK Command Line tools that you have installed. If, for example, you have version 9.0 installed, then you would change the line to set SDKMANAGER=%STUDIO_SDK_PATH%\cmdline-tools\9.0\bin\sdkmanager.bat.

  4. You can then run SetupAndroid.bat to ensure that the correct version of the Android SDK is installed.

  5. Go back to the UnrealEngine folder. Run Setup.bat. This downloads binary content for Unreal Engine, installs prerequisites, and sets up Unreal file associations. It might take a few minutes to run.

  6. If you’re prompted to register the Unreal Engine file type or install prerequisites, click Yes.

  7. Run GenerateProjectFiles.bat. This creates a file called UE5.sln in the same directory.

    You can use the UE5.sln file to build Unreal Engine using Visual Studio.

Build Unreal Engine​

You can build Unreal Engine from the source file using Visual Studio or from the command line. Either way, this step can take several hours to complete.

If you have never built Unreal Engine from source code before, we recommend using Visual Studio.

To build Unreal Engine using Visual Studio, follow the instructions in this article from the Unreal Engine 5 documentation site: Building Unreal Engine from Source. Use the UE5.sln file you created when you ran the GenerateProjectFiles.bat file.

To build Unreal Engine from the command line, run the Build.bat file. Run these two commands:

Engine\Build\BatchFiles\Build.bat UnrealEditor Win64 Development

Engine\Build\BatchFiles\Build.bat ShaderCompileWorker Win64 Development

The executable file created is located in the UnrealEngine folder at \Engine\Binaries\Win64\UE5Editor.exe.

tip

To view logcat for Unreal Engine logs, run this command:

adb logcat -s UE:*

Limitations and work-arounds​

Mixed reality streaming and capture​

If your project uses any mixed reality streaming or capture features, turn off the Mobile HDR rendering setting when packaging your app.This disables post-processing. If you don’t do this, you get a virtual reality capture with a black background instead of a mixed reality capture on a real-world background.

This happens because Unreal Engine does not propagate the alpha channel from the base pass through the post-processing pipeline. Instead, the tonemapper sets a default alpha of 1.0 for every pixel. Unreal Engine uses inverted alpha in OpenXR, so this sets all pixels to fully opaque.

You can leave the Mobile HDR setting on if you just want to see how your content looks on the Magic Leap 2 device and don’t mind if it appears on a black background in captures.

To turn off the Mobile HDR setting when you package your app:

  1. In the Unreal Editor main menu, select Edit > Project Settings.
  2. In the project settings window, go to Engine. Select Rendering. Under VR, deselect Mobile HDR.

Next steps​

For step-by-step instructions on creating a simple app with the version of Unreal Engine you just built, see Create an app using Unreal Engine.

You can also try examples located in the Magic Leap 2 Unreal SDK at unreal-sdk\Projects\HelloCube and unreal-sdk\Projects\Examples. Examples for the Controller, hand interactions, marker tracking, and planes can be accessed from the unreal-sdk\Projects\Examples\Example.uproject file. To access them, open the file in Unreal Engine, select File > Open Level, and go to the Levels folder.