Setting Up the Niantic SDK for Unity

To set up the SDK, you will download and install Unity, then install the ARDK Unity packages and set up Unity for the platform your AR experience will run on. After that, you will authenticate Lightship in Unity with your API key, perform any additional setup your platform device requires, and set up the basic requirements for an AR scene in Unity.

Beta Content

The Lightship Magic Leap 2 integration is in beta, so some features may not work as expected.

Download and Install Unity

Download Unity. We support Unity 2022 LTS (with 2022.3.37f1) and 2021 LTS (with 2021.3.37f1).

Attention!

Unity 2022 LTS users will need to manually upgrade Visual Scripting from 1.9.0 to 1.9.1 or higher via the Package Manager to avoid a SessionStateChangedEventUnit error.

Create a Project and Install ARDK

Android

Create a Project and Install ARDK

1. Create a new Unity project with the Universal 3D (Core) template.
2. In your Unity project, open the Window top menu, then select Package Manager.
3. From the plus menu on the Package Manager tab, select Add package from git URL....

   

4. Enter https://github.com/niantic-lightship/ardk-upm.git.
   1. If prompted, click Yes to activate the new Input System Package for ARFoundation 5.0. This may require a restart of the Unity Editor.
5. To add the SharedAR package, repeat these steps using the following URL instead: https://github.com/niantic-lightship/sharedar-upm.git.

To use a specific ARDK version, download its .tgz from our release pages (ardk-upm, sharedar-upm). Then, follow the installation instructions above and select "Add package from tarball" instead of the Git URL.

iOS

Create a Project and Install ARDK

1. Create a new Unity project with the Universal 3D (Core) template.
2. In your Unity project, open the Window top menu, then select Package Manager.
3. From the plus menu on the Package Manager tab, select Add package from git URL....

   

4. Enter https://github.com/niantic-lightship/ardk-upm.git.
   1. If prompted, click Yes to activate the new Input System Package for ARFoundation 5.0. This may require a restart of the Unity Editor.
5. To add the SharedAR package, repeat these steps using the following URL instead: https://github.com/niantic-lightship/sharedar-upm.git.

To use a specific ARDK version, download its .tgz from our release pages (ardk-upm, sharedar-upm). Then, follow the installation instructions above and select "Add package from tarball" instead of the Git URL.

Magic Leap 2

Lightship's Magic Leap plugin is compatible with ML OS version 1.10 with the ML Unity SDK version 2.5.

In the Magic Leap Hub

1. Download and install Magic Leap Hub 3 from the Magic Leap developer portal.
2. Turn on your Magic Leap 2 and connect using USB. You may need to authorize the connection to your computer in an on-device prompt.
3. Verify the installed Magic Leap OS version is correct.
   1. In the Settings app, find the About section.
   2. Scroll down to OS Version. If it says 1.10, you're done!
   3. If the version is lower than 1.10, follow these instructions to update your device using the Magic Leap 2 Updater.
   4. If the version is higher than 1.10, connect your device to your machine, then follow these instructions to downgrade your OS using Magic Leap Hub 3.
4. Enable Developer Mode and USB Debugging on your Magic Leap 2:
   1. Return to the About section in the Settings app.
   2. Scroll down to Build Number. Click on it seven times to enable Developer Mode.
   3. Open the System settings menu, then scroll down to Advanced and open Developer Options.
   4. Under Debugging, enable USB Debugging.
   5. When you connect your device, select Allow USB Debugging in the prompt that opens. You can check Always allow to skip this step in the future.
5. Open Unity and create a new project using the 3D (Built-In Render Pipeline) template. Lightship also supports Magic Leap applications built using URP, but it's samples are not set up to run in URP.
6. Install the Magic Leap SDK and dependencies:

   1. Open the Magic Leap Hub, then, in the Packages left-hand menu, scroll down and select Unity Package. From the Version drop-down menu, select 2.5.0, then install it.

      

   2. After installing the Unity package, find ML C SDK in the Packages menu. Select it, then choose 1.10.0 from the Version drop-down menu and install it.

      

In Unity

1. Add the Magic Leap Setup Tool to your Unity account from the Unity Asset Store.
2. Import the Magic Leap Setup Tool into your Unity project:
   1. In Unity, open the Window top menu and select Package Manager.
   2. Expand the Packages: In Project drop-down menu, then select My Assets.
   3. Select the Magic Leap Setup Tool, then click Import.
   4. Select Use OpenXR when asked.
   5. Once it finishes, the Magic Leap Project Setup window will open automatically.
   6. Troubleshooting: If the setup tool is stuck in the "Loading and Importing..." phase, try forcing the Unity Editor to recompile by changing the platform target.
3. Use the Magic Leap Setup Tool to set up your project:
   1. Click the Set Magic Leap SDK Folder button, which should open the mlsdk folder on your machine. On macOS, this is located at ~/MagicLeap/mlsdk. Select the v1.10.0 folder.
   2. Next to Set build target to Android, click Fix Setting.
   3. Import the Magic Leap SDK:
      1. Click Import Package.
      2. When prompted to use the Magic Leap Registry, select Use Local Copy. (Selecting the Use Magic Leap Registry option will install the newest version available, which may not be compatible with your version of the Lightship plugin.)
      3. The Magic Leap unity directory should open automatically. On macOS, this is located at ~/MagicLeap/tools/unity. Open the v2.5.0 folder, then select the com.magicleap.unitysdk.tgz package.
      4. If prompted, click Yes to activate the new Input System Package. This may require a restart of the Unity Editor.
   4. Click Apply All to automate the remaining setup steps. Select Continue and Yes for any setup prompts that appear.
4. Import the Niantic SDK for Unity packages:
   1. In Unity, open the Window top menu and select Package Manager.
   2. From the plus menu on the Package Manager tab, select Add package from git URL....

      

   3. To add the Niantic Lightship AR plugin, enter https://github.com/niantic-lightship/ardk-upm.git.
      1. If prompted, click Yes to activate the new Input System Package for ARFoundation 5.0. This may require a restart of the Unity Editor.
   4. To add the Magic Leap package, repeat these steps using the following URL instead: https://github.com/niantic-lightship/ardk-ml2-upm.git.

To use a specific ARDK version, download its .tgz from our release pages (ardk-upm, ml2-upm). Then, follow the installation instructions above and select "Add package from tarball" instead of the Git URL.

Create a Lightship Account and Add API Key

1. Open the Lightship top menu, then select Settings to open the Lightship Settings menu. Click on Get API Key under Credentials. This should open the lightship.dev website in a browser window.
2. Create a new Lightship account if you need to, then log in.
3. Open the Projects page, then select an existing project or create a new one by clicking New Project.
4. In your project's Overview, copy the API Key by clicking the copy icon next to it.
5. Return to the Lightship Settings window in Unity and paste your API Key into the API Key field.

Activate the XR Loader for Your Mobile Platform

caution

In Unity version 2022.3.10f1 or newer, you might see a benign error in the console after following these steps.

Android

1. Open the Lightship top menu, then select XR Plug-in Management.
2. In the XR Plug-in Management menu, select the Android tab, then check the box labeled Niantic Lightship SDK + Google ARCore.

iOS

1. Open the Lightship top menu, then select XR Plug-in Management.
2. In the XR Plug-in Management menu, select the iOS tab, then check the box labeled Niantic Lightship SDK + Apple ARKit.

Magic Leap 2

1. From the Lightship menu in the top toolbar, click the Set Up ML2 button.
2. From the same Lightship menu, select XR Plug-in Management.
3. In the XR Plug-in Management menu, select the Android tab, then check the box labeled OpenXR if it's not already enabled. 1.Check the boxes labeled Magic Leap 2 feature group and Niantic Lightship support for Magic Leap feature group.

1.Ensure that the following Unity settings are correct. These should be properly set already, but we recommend double-checking these settings first if any issues arise.

1. From the top toolbar, open Unity -> Settings -> External Tools:
   1. Check to make sure that Gradle, the Android SDK, and the NDK are set to the Unity defaults.
2. In the Project Settings menu:
   1. Expand the Magic Leap menu, then select Permissions. Make sure the CAMERA permission is enabled.
   
   1. Expand the XR Plug-in Management menu, then select OpenXR and open the Android tab. Make sure that at least the Magic Leap 2 Reference Spaces, Magic Leap 2 Support, and Lightship Magic Leap Features integration Feature Groups are enabled.
   2. Open the Magic Leap 2 Support settings. Check the box labeled Perception Snapshots.
   3. Select Project Validation from the left-hand menu. Select the Android tab, and make sure the window has no errors in it. The warning for "If using Lightship ARDK for Android..." should be ignored when building for ML2.

Configure the Build Platform

1. Open the Build Settings window by selecting File > Build Settings.
2. Select iOS or Android, then click Switch Platform. After the progress bar finishes, click Player Settings. Select your platform from the tabs, scroll down to Other Settings, and change the following settings:

Android

• Rendering - Uncheck Auto Graphics API. If Vulkan appears in the Graphics API list, remove it.
• Identification - Set the Minimum API Level to Android 7.0 'Nougat' (API Level 24) or higher.
• Configuration - Set the Scripting Backend to IL2CPP, then enable both ARMv7 and ARM64.

Attention!

If you are using Unity 2022.3.15f1 or older, building to Android requires a custom Gradle installation.

Click here to reveal the Gradle installation instructions

1. Download and install Gradle 6.7.1 from the Gradle Releases page.
2. Replace the default Gradle install in Unity:
3. In Unity, open Preferences > External Tools > Android.
4. Uncheck the box labeled Gradle installed with Unity (recommended), then replace the path with your local installation of Gradle 6.7.1.

tip

If you are building through the command line, you can customize the Gradle path by setting AndroidExternalToolsSettings.gradlePath in your Unity build script.

1. Set your Build Target to Android.

iOS

• Identification > Signing Team ID - Enter your iOS app developer key from developer.apple.com.
• Camera Use Description - Write a description for how you're using AR, such as "Lightship ARDK".
• Target Minimum iOS Version - Set to 14.0 or higher.
• Architecture - Select ARM64.

Magic Leap 2

Nothing to do here. All configurations should have been taken care of by the Magic Leap Setup Tool.

Next Steps

Setting Up a Basic AR Scene

Android

To get started creating your own AR project, begin by creating an empty AR scene:

1. Create a new Basic scene:
   1. From the main menu, choose File > New Scene.
   2. Select Basic (Built-in) and click Create.
2. Right-click on the Main Camera and select Delete.
3. Add an ARSession and XROrigin to your new scene
   1. Select the new scene in the Hierarchy.
   2. From the main menu, select Game Object > XR > AR Session.
   3. Repeat to add an XR Origin (Mobile AR).
4. Save the scene using File > Save.

tip

If you choose Save As Scene Template, you can select this scene in the New Scene dialog next time.

iOS

To get started creating your own AR project, begin by creating an empty AR scene:

1. Create a new Basic scene:
   1. From the main menu, choose File > New Scene.
   2. Select Basic (Built-in) and click Create.
2. Right-click on the Main Camera and select Delete.
3. Add an ARSession and XROrigin to your new scene
   1. Select the new scene in the Hierarchy.
   2. From the main menu, select Game Object > XR > AR Session.
   3. Repeat to add an XR Origin (Mobile AR).
4. Save the scene using File > Save.

tip

If you choose Save As Scene Template, you can select this scene in the New Scene dialog next time.

Magic Leap 2

To get started creating your own AR project, beging by setting up a simple scene using the instructions located in the Magic Leap Developer Docs.

Then check out the Lightship sample scenes for Magic Leap 2 or learn more about developing in Lightship for the Magic Leap 2.

Further Reading

From here, proceed to the Sample Projects page to try out the features or to the How-To page to experiment with a guided tutorial. If you instead have a previous ARDK project you would like to convert to ARDK 3, see our Migration Guide.