[Unity SDK 2.3.0] Unity Namespace Changes

Announcements
1

Important Notice: Namespace Changes in Unity SDK 2.3.0

The upcoming version of the Magic Leap SDK (version 2.3.0) will include a namespace change that will affect developers using OpenXR in Unity. To ensure a smooth transition, we have provided tools to update your scripts automatically.

Namespace Changes

The Magic Leap OpenXR scripts have been migrated from the UnityEngine.XR.OpenXR.MagicLeapSupport namespace to MagicLeap.OpenXR and MagicLeap.OpenXR.Features.x, where x is the specific feature you are accessing. This change requires developers to update their scripts to be compatible with the latest SDK version.

Example Namespace Update

Here is an example of how your scripts will need to be updated:

using UnityEngine;
using UnityEngine.XR.OpenXR;
- using UnityEngine.XR.OpenXR.Features.MagicLeapSupport;
+ using MagicLeap.OpenXR.Features.LightEstimation;

public class LightEstimationSampleCode : MonoBehaviour
{
    private MagicLeapLightEstimationFeature _lightEstimationFeature;

-    private MagicLeapLightEstimationFeature.HDRCubemapFaceResolution cubemapFaceResolution;
+    private HDRCubemapFaceResolution cubemapFaceResolution;

    void Start()
    {
        // Obtain the Light Estimation Feature.
        _lightEstimationFeature = OpenXRSettings.Instance.GetFeature<MagicLeapLightEstimationFeature>();

        // Create the light estimation.
        _lightEstimationFeature.CreateLightEstimation(cubemapFaceResolution);
    }
}

Actions Required

Before updating to the latest Magic Leap SDK, please make sure to import one of the following packages:

  1. Upgrade Unity Setup Tool (version 2.0.11 or higher) : Use the latest version to manage the namespace changes. Version 2.0.11 will provide access to the Namespace Migration Option in Unity's Menu bar under Magic Leap >API Updater.
  2. Namespace Migration Tool (8.9 KB): Use the package linked in this post to access the migration tool separately or if the Setup Tool is not available.

About the Namespace Migration Tool

This tool is designed to help developers migrate Magic Leap OpenXR scripts to new namespaces which help identify Magic Leap SDK components and Unity Engine scripts.

Downloading the Tool

  1. Visit the Repository: Navigate to the official Magic Leap GitHub repository where the Namespace Migration Tool is hosted.
  2. Download the Package: Download the latest version of the magicleap-namespace-tool.unitypackage.

magicleap-namespace-tool.unitypackage (8.9 KB)

Importing the Tool into Your Unity Project

  1. Open Your Unity Project: Launch the Unity Editor and open the project where you intend to use the Namespace Migration Tool.
  2. Import the Package:
    • In the Unity Editor, go to Assets > Import Package > Custom Package.
    • Locate and select the magicleap-namespace-tool.unitypackage file you downloaded.
    • In the Import Unity Package window, ensure all items are selected and click Import.

Using the Namespace Migration Tool

Updating Namespaces

  1. Access the Tool: Navigate to Magic Leap API Updater > Migrate Namespaces.
  2. Backup Prompt: A prompt will appear recommending you back up your project before proceeding. (The tool will preserve a copy of your original scripts.)
  3. Choose Update Scope: Select to update all scripts in your Assets/ folder or choose a specific directory.
  4. Monitor Progress: The tool will display a progress bar indicating the status of the namespace migration.

Restoring Original Scripts

  1. Access the Restore Option: Select the Magic Leap API Updater > Restore Original Script Files.
  2. Confirmation Dialog: A dialog will inform you that the current versions of the scripts will be reverted and cannot be restored unless tracked by source control tools.
  3. Restore Scripts: If you choose to continue, the original scripts will be restored from the backups.

Deleting Backup Files

  1. Access the Delete Option: Select the Magic Leap API Updater > Delete Script Backups.
  2. Confirmation Dialog: A dialog will inform you that the original versions of the scripts cannot be restored unless tracked by other source control tools.
  3. Confirm Deletion: Confirm your intention to delete the backup files.
  4. Delete Backups: All backup files and the tracking JSON file will be deleted.

Additional Details

  • Backup Your Project: It is highly recommended to back up your project before using the Namespace Migration tool to avoid any unintended data loss.
  • Modified Scripts: When migrating the namespaces in you scripts, the tool will preserve the unmodified versions by adding a . character at the front of the original file names. A json file will be created in your Assets/ directory that includes a list of the modified scripts their original copies. (Do not edit this file manually)
  • Tool Version Compatibility: The Namespace Migration Tool is designed to work with Magic Leap SDK v2.3.0 or higher. Namespace changes will not be performed if the version requirement is not met.

Using Migration Tool After Updating

If you have updated to the latest SDK version and are presented with errors in your project, you can still use either the setup tool or the Namespace Migration package. However, you may need to restart your Unity editor after importing the package for the Menu Options to appear. Note: The menu options will not appear if you open the editor in SafeMode.