Configure Project Settings
This topic describes how to configure the Unity Build Settings to utilize Magic Leap features.
The fastest recommended way to set up your project for Magic Leap 2 development is to use the latest version of the Magic Leap Setup Tool.
- Download the Magic Leap Setup Tool from the Unity Asset Store
- After adding it to your asset library, click the Open in Unity button to show the tool inside Unity's Package Manager.
- Select Download then Import to import the tool into your project.
- Keep all of the package contents selected in the Import Unity Package window and select Import.
- After the package is imported, you should see the Magic Leap Project Setup Tool popup window. If you do not see it, go to Magic Leap > Project Setup Tool in the Unity menu.
- The project setup tool will walk you through all of the steps necessary to complete setup. Start by setting the Magic Leap SDK by selecting Locate SDK. Then select the folder containing the latest version of the Magic Leap Unity SDK.
- After setting the SDK folder, you can select the Apply All button on the bottom of the window to quickly change all of the required settings.
- After accepting all prompts and restarting the editor, your project will now be ready for Magic Leap 2 development.
The Magic Leap Setup Tool will import the latest version of the Magic Leap core SDK compatible with your Unity Editor version. If your project requires an older version of the SDK, you can assign the Magic Leap SDK path manually.
Please reference the Magic Leap OS, SDK and Unity SDK compatibility matrix to determine which version is right for you.
This section provides detailed steps on how to manually configure your Unity Project so that you can build and deploy applications for Magic Leap 2.
Import Magic Leap Unity SDK
The Magic Leap SDK provides access to Magic Leap's perception and input API. The Magic Leap Unity SDK can be installed using the Unity Package Manager by importing the SDK from your computer or a scoped registry.
- From Disk
- Scoped Registry
Open the Package Manager window ( Window > Package Manager).
Select the "+" (plus) button in the top-left corner, then Add package from tarball.
- Navigate to the location of the following folders and select the .tgz file within to add the package from
com.magicleap.unitysdk.tgz(downloaded via ML Hub). For example:
- Mac :
- Windows :
You may see the following pop-ups appear:
"This project is using the new input system package, but the native platform backends for the new input system are not enabled in the player settings. This means that no input from native devices will come through. Do you want to enable the backends? Doing so will RESTART the editor and will DISABLE the old UnityEngine.Input APIs."
- Select Yes
"This project may contain an obsolete method to validate interactions between XR Interactors and Interactables. This Update is only required for older projects updating the XR Interaction Toolkit package. If this package was newly installed, please cancel this operation. If you choose 'Go Ahead', Unity will update all Interactors and Interactables in Prefabs and scenes to use the new Interaction Layer instead of the Unity physics Layer. You can always manually run the XR InteractionLayerMask Updater fro... (For the full error message, see the editor log file located at ...)"
- Click I Made a Backup, Go Ahead!
- Navigate to to the Package Manager settings by selecting Edit > Project Settings from the menu. Then choose Package Manager.
- Select the + button at the bottom of the list. A new entry will appear as New Scoped Registry in the list.
- Enter the following details into the Scoped Registry:
Name : Magic Leap
URL : https://registry.npmjs.org
Scope : com.magicleap
- Click Apply.
Now you will be able to view Magic Leap packages in the Package Manager. Follow the steps below to download and import the Magic Leap Unity SDK.
- Open the Package Manger window (Window > Package Manager).
- Click the Packages dropdown and select My Registries.
- Find and select the Magic Leap SDK package from the list.
- Finally select Download and then Import.
You can also add the registry by editing your project's /Packages/manifest.json file directly
- Open the
manifest.jsonfile located in the
/Packages/folder inside your project's root directory.
- Add the following scoped registry
"name": "Magic Leap"
At any time, you can fix any problems with your registry by choosing Reset packages to defaults from the main Unity Help menu. However, be aware that this action resets all changes you made to the dependencies of your project so it is best to do this as a last resort.
XR Plugin Management
The Magic Leap XR Provider needs to be enabled before using Magic Leap's platform features. To do this:
- Go to File > Build Settings > Player Settings > XR Plug-in Management and enable Magic Leap as a Plug-in Provider on the Android platform.
Assign Magic Leap SDK Path
The Magic Leap SDK Path setting will only show once the Magic Leap XR package is imported. If the Magic Leap SDK path setting is not visible, make sure the
com.unity.xr.magicleap packages were imported correctly and that there are no errors in the Unity Console.
- Open Edit > Preferences on Windows (or macOS: Unity > Preferences), then navigate to External Tools > Magic Leap.
- Set the MLSDK path to the Magic Leap SDK you downloaded from the ML Hub earlier. For example:
- In the same window, if the path to the Application Simulator Runtime does not get populated automatically, check the 'Override' box and select the path to the latest version of the App Simulator Runtime package. This location can be found by clicking the 'Open folder' link underneath the package's name inside ML Hub's Package manager.
To locate the Magic Leap C SDK, open the ML Hub application and go to Package Manager> My Tools, under Common Packages expand Magic Leap C SDK and select the Open Folder or Open Shell. Note the path in the file explorer or shell.
This section provides instructions on how to create a custom manifest file and declare Magic Leap 2 specific permissions for your application. For more information, see the Permissions Overview guide.
Editing your application's permissions through the Unity Editor Window is only available if you have a valid MLSDK path assigned the Unity Editor's Preferences Window.
- Enable a custom manifest in your project's settings by going to Edit > Project Settings > Player, then under Publishing Settings select Custom Main Manifest.
- Go to Edit > Project Settings > Magic Leap > Permissions to enable permissions on various features. It is generally recommended to include any additional features based on your application's requirements.
Under the Edit > Project Settings > Player section, make sure the Android tab is selected, then configure the following settings:
- At the top, set the following identifiers:
- Company Name - the name of your company.
- Product Name - the name of your app or product as you want it to appear on the in-device menu.
- Expand Other Settings then Rendering, and set the Color Space property to Linear. This enables more realistic rendering. For more information, read Unity’s gamma and linear color space workflow guide.
- Also under Rendering, disable Auto Graphics API and make sure the only Graphics API listed is Vulkan. Additionally, make sure the Texture Compression Format is set to DXT.
- Under Identification, set the Minimum API Level to 29.
- Under Configuration, set the Scripting Backend to IL2CPP.
- Also under Configuration, check the box next to the Target Architecture x86-64 (Chrome OS and Magic Leap 2) and set the Target Devices dropdown to All Devices.
Build Settings let you set the target platform, configure build-related settings, and start the build process.
- In the menu, go to File and select Build Settings.
- Under Platform, select Android.
- Click Switch Platform.
- You are now ready to add scenes to the build order and build to the device!
Validate Project Settings
Developers can use Unity's Project Validation tool to validate that project's settings have been configured properly.
- Open the Magic Leap Project validation window (Window > XR > Magic Leap > Project Validation).
- Verify that no issues are listed. If there is an issue, select Fix All in the top right of the Project Validation window.
This tool can be used to configure new projects in the future. Note, the validation tool does not check your project's Manifest, API level, or XR Plugin Management settings.
Configure Render Pipeline Settings
After configuring your project's settings, learn how to create and optimize your project's rendering for Magic Leap 2.