XREAL SDK

https://docs.xreal.com/
Admin
XREAL SDK is a development framework for creating mixed reality experiences on XREAL glasses,...
Tokens:29,455
Snippets:328
Trust Score:9.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Legacy NRSDK Anchor Implementation

Source: https://docs.xreal.com/MigratingFromNRSDKToXREALSDK/Migration_Anchors

Example of the previous NRSDK approach using NRWorldAnchor and NRWorldAnchorStore for persistence.

```csharp
public class LocalMapExample : MonoBehaviour  
{  
    private NRWorldAnchorStore m_NRWorldAnchorStore;  
  
    public void AddAnchor()  
    {  
        var go = Instantiate(prefab);  
        NRWorldAnchor anchor = go.AddComponent<NRWorldAnchor>();  
        anchor.UserDefinedKey = key;  
        bool success = anchor.CreateAnchor();  
    }  
  
    public void Save()  
    {  
        m_NRWorldAnchorStore.SaveAllAnchors();  
    }  
  
    public void Load()  
    {  
        var list = m_NRWorldAnchorStore.GetLoadableAnchorUUID();  
        foreach (var item in list)  
        {  
            m_NRWorldAnchorStore.LoadwithUUID(item.Key, (handle) => {  
                // Handle anchor loading  
            });  
        }  
    }  
}  

```

--------------------------------

### Start Mesh Classification

Source: https://docs.xreal.com/Depth%20Mesh/MeshClassification

Initializes the scanning process to begin classifying environment surfaces.

```csharp
public void StartClassification()  
{  
    // Begin scanning and classifying the environment  
    m_MeshClassifier.StartScanning();  
}  
```

--------------------------------

### Implement ARMeshManager Validation

Source: https://docs.xreal.com/MigratingFromNRSDKToXREALSDK/Migration_Meshing

Example of validating the ARMeshManager hierarchy at edit time.

```csharp
void OnValidate()  
{  
    if (!IsValid())  
    {  
        // Display error dialog  
        EditorUtility.DisplayDialog(  
            "Hierarchy not allowed",  
            "An ARMeshManager must be a child of an XROrigin.",  
            "Remove Component");  
          
        // Automatically remove the component  
        DestroyImmediate(this);  
    }  
}
```

--------------------------------

### Configure Gradle packagingOptions for Firebase

Source: https://docs.xreal.com/Spatial%20Anchor/Tutorial-Sharing%20Anchors/Firebase

Add this configuration to the launcherTemplate.gradle file in Unity to resolve build failures after installing Firebase.

```gradle
    packagingOptions   
    {  
        exclude 'META-INF/com.android.tools/proguard/coroutines.pro'  
    }  
```

--------------------------------

### FrameMetrics Log Output

Source: https://docs.xreal.com/Rendering/Render%20Metrics

Example of the log output recorded once every second, containing both instantaneous and cumulative performance metrics.

```text
FrameMetrics: FPS=60, frNum=61, UpdPrd=39198222, prd=30078850, postPrd=28850795, sdkPrd=39802247, FPC=1.081967, EFC=0, early=0, drop=8 frNumA=753, UpdPrdA=41190049, prdA=32105576, postPrdA=30656161, sdkPrdA=41785068, FPCA=1.092961, EFCA=0.1288181, earlyA=70, dropA=76
```

--------------------------------

### Legacy NRSDK Image Tracking Controller

Source: https://docs.xreal.com/MigratingFromNRSDKToXREALSDK/Migration_ImageTracking

Example of manual image tracking management using NRSDK's NRTrackableImage API.

```csharp
public class TrackingImageExampleController : MonoBehaviour  
{  
    public TrackingImageVisualizer TrackingImageVisualizerPrefab;  
    private Dictionary<int, TrackingImageVisualizer> m_Visualizers = new Dictionary<int, TrackingImageVisualizer>();  
    private List<NRTrackableImage> m_TempTrackingImages = new List<NRTrackableImage>();  
  
    public void Update()  
    {  
        NRFrame.GetTrackables<NRTrackableImage>(m_TempTrackingImages, NRTrackableQueryFilter.New);  
        foreach (var image in m_TempTrackingImages)  
        {  
            TrackingImageVisualizer visualizer = null;  
            m_Visualizers.TryGetValue(image.GetDataBaseIndex(), out visualizer);  
            if (image.GetTrackingState() != TrackingState.Stopped && visualizer == null)  
            {  
                visualizer = Instantiate(TrackingImageVisualizerPrefab, image.GetCenterPose().position, image.GetCenterPose().rotation);  
                visualizer.Image = image;  
                m_Visualizers.Add(image.GetDataBaseIndex(), visualizer);  
            }  
        }  
    }  
}  
```

--------------------------------

### NRWorldAnchorStore Class Implementation

Source: https://docs.xreal.com/Spatial%20Anchor/Tutorial-HalloweenTreasureHunt/HandletheSituationofFailedAnchorSaving

The core class for managing world anchors, including initialization, file system path setup, and anchor dictionary management.

```csharp
namespace NRKernal.Persistence  
{  
    using System;  
    using System.Collections.Generic;  
    using System.IO;  
    using System.Linq;  
    using System.Threading;  
    using UnityEngine;  
  using System.Threading.Tasks;  
  
    /// <summary> NR world anchor store. </summary>  
    public class NRWorldAnchorStore : IDisposable  
    {  
        /// <summary> The native mapping. </summary>  
        private NativeMapping m_NativeMapping;  
        /// <summary> Dictionary of anchors. </summary>  
        private Dictionary<UInt64, NRWorldAnchor> m_AnchorDict = new Dictionary<UInt64, NRWorldAnchor>();  
        /// <summary> Dictionary of anchor uuid and UserDefinedKey. </summary>  
        private Dictionary<string, string> m_Anchor2ObjectDict = new Dictionary<string, string>();  
        public static NRWorldAnchorStore Instance;  
  
        /// <summary> Pathname of the map folder. </summary>  
        public const string MapFolder = "XrealMaps";  
        public readonly string MapPath;  
        /// <summary> The anchor 2 object file. </summary>  
        public const string Anchor2ObjectFile = "anchor2object.json";  
  
        private bool saveStatus;  
      // private AliyunOSSManager ossManager;  
      
  
        /// <summary> Default constructor. </summary>  
        internal NRWorldAnchorStore()  
        {  
#if !UNITY_EDITOR  
            m_NativeMapping = new NativeMapping(NRSessionManager.Instance.NativeAPI);  
#endif  
            Instance = this;  
            MapPath =  
#if UNITY_EDITOR  
                Path.Combine(Directory.GetCurrentDirectory(), MapFolder);  
#else  
                Path.Combine(Application.persistentDataPath, MapFolder);  
#endif  
            if (!Directory.Exists(MapPath))  
                Directory.CreateDirectory(MapPath);  
            string path = Path.Combine(MapPath, Anchor2ObjectFile);  
            if (File.Exists(path))  
            {  
                string json = File.ReadAllText(path);  
                NRDebugger.Info("[NRWorldAnchorStore] Anchor2Object json: {0}", json);  
                m_Anchor2ObjectDict = LitJson.JsonMapper.ToObject<Dictionary<string, string>>(json);  
                for (int i = 0; i < m_Anchor2ObjectDict.Count;)  
                {  
                    var item = m_Anchor2ObjectDict.ElementAt(i).Key;  
                    if (File.Exists(Path.Combine(MapPath, item)))  
                        i++;  
                    else  
                        m_Anchor2ObjectDict.Remove(item);  
                }  
            }  
            //ossManager = new AliyunOSSManager();  
        
      //storageManager.storageBasePath = "gs://nrsdk-63305.appspot.com";  
            NRKernalUpdater.OnUpdate += OnUpdate;  
        }  
  
        /// <summary> Cleans up the WorldAnchorStore and releases memory. </summary>  
        public void Dispose()  
        {  
            m_NativeMapping = null;  
            NRKernalUpdater.OnUpdate -= OnUpdate;  
        }  
  
        /// <summary> Executes the 'update' action. </summary>  
        private void OnUpdate()  
        {  
#if !UNITY_EDITOR  
            var listhandle = m_NativeMapping.CreateAnchorList();  
            m_NativeMapping.UpdateAnchor(listhandle);  
            var size = m_NativeMapping.GetAnchorListSize(listhandle);  
            for (int i = 0; i < size; i++)  
            {  
                var anchorhandle = m_NativeMapping.AcquireItem(listhandle, i);  
                if (m_AnchorDict.ContainsKey(anchorhandle))  
                {  
                    m_AnchorDict[anchorhandle].CurrentTrackingState = m_NativeMapping.GetTrackingState(anchorhandle);  
                    if (m_AnchorDict[anchorhandle].CurrentTrackingState == TrackingState.Tracking)  
                    {  
                        Pose pose = ConversionUtility.ApiWorldToUnityWorld(m_NativeMapping.GetAnchorPose(anchorhandle));  
                        m_AnchorDict[anchorhandle].UpdatePose(pose);  
                    }  
                }  
            }  
            m_NativeMapping.DestroyAnchorList(listhandle);  
#endif  
        }  
  
        /// <summary> Creates an NRWorldAnchor. </summary>  
        /// <param name="anchor"> The NRWorldAnchor handler.</param>  
        /// <returns> The new anchor. </returns>  
        public bool CreateAnchor(NRWorldAnchor anchor)  
        {  
            NRDebugger.Info("[NRWorldAnchorStore] Create a new NRWorldAnchor handle");  
            Pose pose = new Pose(anchor.transform.position, anchor.transform.rotation);  
            UInt64 handle = 0;  
#if UNITY_EDITOR  
            handle = (ulong)UnityEngine.Random.Range(1, int.MaxValue);  
#else  
            handle = m_NativeMapping.AddAnchor(pose);  
#endif  
            if (handle == 0)  
                return false;  
#if UNITY_EDITOR
```

--------------------------------

### Implement Cloud Load Test Method

Source: https://docs.xreal.com/Spatial%20Anchor/Tutorial-Sharing%20Anchors/CloudSaveandLoad

Add this method to the local map example to trigger anchor retrieval using a specific UUID.

```csharp
 public string testuuid;  
        public void TestCloudLoad()  
        {  
            CloudLoad(testuuid);  
        }  
```

--------------------------------

### Aliyun OSS Manager Implementation

Source: https://docs.xreal.com/Spatial%20Anchor/Tutorial-Sharing%20Anchors/Aliyun

A singleton manager class for handling file uploads and downloads using the Aliyun OSS .NET SDK. Ensure the Aliyun.OSS.dll is placed in the Assets/Plugins folder before use.

```csharp
using Aliyun.OSS;  
using System;  
using System.IO;  
using System.Threading.Tasks;  
using UnityEngine;  
  
public class AliyunOSSManager  
{  
      
    private static AliyunOSSManager _instance;  
    public static AliyunOSSManager Instance  
    {  
        get  
        {  
            if (_instance == null)  
            {  
                _instance = new AliyunOSSManager();  
            }  
            return _instance;  
        }  
    }  
    private string accessKeyId = "your-access-key-id";  
    private string accessKeySecret = "your-access-key-secret";  
    private string endpoint = "your-endpoint";//similar to：oss-cn-beijing.aliyuncs.com  
    private string bucketName = "your-bucket-name";  
  
    private OssClient client;  
  
    public AliyunOSSManager()  
    {  
        client = new OssClient(endpoint, accessKeyId, accessKeySecret);  
    }  
  
    public Task UploadFile(string objectName, string localFilename)  
    {  
        TaskCompletionSource<bool> tcs = new TaskCompletionSource<bool>();  
  
        try  
        {  
            client.PutObject(bucketName, objectName, localFilename);  
            Debug.Log("File uploaded successfully.");  
            tcs.SetResult(true); // Set the task as successfully completed.  
        }  
        catch (Exception e)  
        {  
            Debug.LogError("Failed to upload file: " + e.Message);  
            tcs.SetResult(false); // Set the task to complete, but failed to return.  
        }  
  
        return tcs.Task;  
    }  
  
    public Task DownloadFile(string objectName, string localFilename)  
    {  
        TaskCompletionSource<bool> tcs = new TaskCompletionSource<bool>();  
  
        try  
        {  
            OssObject ossObject = client.GetObject(bucketName, objectName);  
            using (var requestStream = ossObject.Content)  
            {  
                byte[] buf = new byte[1024];  
                var fs = File.Open(localFilename, FileMode.OpenOrCreate);  
                var len = 0;  
                while ((len = requestStream.Read(buf, 0, 1024)) != 0)  
                {  
                    fs.Write(buf, 0, len);  
                }  
                fs.Close();  
            }  
  
            Debug.Log("File downloaded successfully.");  
            tcs.SetResult(true); // Set the task to be completed successfully.  
        }  
        catch (Exception e)  
        {  
            Debug.LogError("Failed to download file: " + e.Message);  
            tcs.SetResult(false); // Set the task to complete, but the return failed.  
        }  
  
        return tcs.Task;  
    }  
}  
```

--------------------------------

### Implement Room Joining Logic with Photon

Source: https://docs.xreal.com/Spatial%20Anchor/Tutorial-Sharing%20Anchors/SettingUpPhoton

This script handles connecting to the Photon master server and joining or creating a room named 'MyRoom'. It uses a UI button indicator to signal successful connection status.

```csharp
using UnityEngine;  
using Photon.Pun;  
using Photon.Realtime;  
using UnityEngine.UI;  
  
public class JoinRoomButton : MonoBehaviourPunCallbacks  
{  
    public Button joinedRoomIndicator;  
  
    public void OnButtonClick()  
    {  
        // Connect to the Photon master server  
        if (!PhotonNetwork.IsConnected)  
        {  
            PhotonNetwork.ConnectUsingSettings();  
        }  
        else  
        {  
            TryJoinRoom();  
        }  
    }  
  
    public override void OnConnectedToMaster()  
    {  
        Debug.Log("Connected to Photon master server");  
        TryJoinRoom();  
    }  
  
    private void TryJoinRoom()  
    {  
        // Try to join the room "MyRoom"  
        PhotonNetwork.JoinRoom("MyRoom");  
    }  
  
    public override void OnJoinedRoom()  
    {  
        Debug.Log("Joined room: " + PhotonNetwork.CurrentRoom.Name);  
          
        joinedRoomIndicator.image.color = Color.green;  
    }  
  
    public override void OnJoinRoomFailed(short returnCode, string message)  
    {  
        Debug.Log("Failed to join room");  
        // If we failed to join the room, it might not exist, so let's try to create it  
        PhotonNetwork.CreateRoom("MyRoom");  
    }  
  
    public override void OnCreatedRoom()  
    {  
        Debug.Log("Created room: " + PhotonNetwork.CurrentRoom.Name);  
    }  
  
    public override void OnCreateRoomFailed(short returnCode, string message)  
    {  
        Debug.Log("Failed to create room");  
    }  
}  
```

--------------------------------

### Implement CloudLoad Method

Source: https://docs.xreal.com/Spatial%20Anchor/Tutorial-Sharing%20Anchors/CloudSaveandLoad

Downloads a JSON mapping file and the specific anchor file from the cloud, then loads the anchor into the scene using its UUID.

```csharp
public const string CloudAnchor2ObjectFile = "cloud_anchor2object.json";  
public async Task CloudLoad(string uuid)  
{  
    if (m_NRWorldAnchorStore == null)  
    {  
        Debug.Log("[m_NRWorldAnchorStore] is null");  
        return;  
    }  
  
    // Download the cloud anchor to object dictionary from the cloud  
    string path = Path.Combine(m_NRWorldAnchorStore.MapPath, CloudAnchor2ObjectFile);  
    //await ossManager.DownloadFile(CloudAnchor2ObjectFile, path);  
    await storageManager.DownloadFile(CloudAnchor2ObjectFile, path);  
    // Read the dictionary from the downloaded JSON file  
    Dictionary<string, string> m_Anchor2ObjectDict = new Dictionary<string, string>();  
    if (File.Exists(path))  
    {  
        string json = File.ReadAllText(path);  
        m_Anchor2ObjectDict = LitJson.JsonMapper.ToObject<Dictionary<string, string>>(json);  
    }  
  
    // Get the UserDefinedKey for the given uuid  
    string UserDefinedKey;  
      
    if (m_Anchor2ObjectDict.TryGetValue(uuid, out UserDefinedKey))  
    {  
        // Download the anchor file from the cloud  
        string anchorPath = Path.Combine(m_NRWorldAnchorStore.MapPath, uuid);  
        //await ossManager.DownloadFile(uuid, anchorPath);  
        await storageManager.DownloadFile(uuid, anchorPath);  
        Debug.Log("anchorPath: "+anchorPath);  
        Debug.Log("uuid: "+uuid);  
        Debug.Log("UserDefinedKey: "+UserDefinedKey);  
  
        // Create a new dictionary for the specific UUID and Key  
        Dictionary<string, string> specificAnchorDict = new Dictionary<string, string>();  
        specificAnchorDict[uuid] = UserDefinedKey;  
  
        // Save the downloaded dictionary to the NRWorldAnchorStore  
        m_NRWorldAnchorStore.SetAnchor2ObjectDict(specificAnchorDict);  
  
        // Load the anchor  
        m_NRWorldAnchorStore.LoadwithUUID(uuid, (UInt64 handle) =>  
        {  
            var go = Instantiate(m_AnchorPrefabDict[UserDefinedKey]);  
            Debug.Log("cloud load: successful! ");  
#if UNITY_EDITOR  
            go.transform.position = UnityEngine.Random.insideUnitSphere + Vector3.forward * 2;  
#else  
            go.transform.position = Vector3.forward * 10000;  
#endif  
            NRWorldAnchor anchor = go.AddComponent<NRWorldAnchor>();  
            anchor.UserDefinedKey = UserDefinedKey;  
            anchor.UUID = uuid;  
            anchor.BindAnchor(handle);  
            go.SetActive(true);  
  
            NRDebugger.Info("[NRWorldAnchorStore] CloudLoadwithUUID: {0}, UserDefinedKey: {1} Handle: {2}", uuid, UserDefinedKey, handle);  
        });  
    }  
    else  
    {  
        Debug.LogError("No UserDefinedKey found for uuid: " + uuid);  
    }
}
```

--------------------------------

### Retrieving Marker Information

Source: https://docs.xreal.com/Image%20Tracking/Marker

Access properties of the ARTrackedImage object to get reference image details and tracking state.

```csharp
trackedImage.referenceImage.name;  // Reference image name  
trackedImage.trackingState;        // Tracking state  
trackedImage.referenceImage.size;  // Size of the reference image  
trackedImage.size;                 // Actual tracked image size
```

--------------------------------

### Migrate Controller State Queries

Source: https://docs.xreal.com/MigratingFromNRSDKToXREALSDK/intro

Transition from static NRInput position/rotation calls to using XRController device feature values.

```csharp
// Old NRInput code  
Vector3 position = NRInput.GetPosition();  
Quaternion rotation = NRInput.GetRotation();  
  
// New Input System code  
public XRController controller;  
  
void Update() {  
    if (controller.inputDevice.TryGetFeatureValue(CommonUsages.devicePosition, out Vector3 position)) {  
        // Use position  
    }  
    if (controller.inputDevice.TryGetFeatureValue(CommonUsages.deviceRotation, out Quaternion rotation)) {  
        // Use rotation  
    }  
}  
```

--------------------------------

### Implement UUIDManager for Photon Synchronization

Source: https://docs.xreal.com/Spatial%20Anchor/Tutorial-Sharing%20Anchors/SharingAnchorswithPhoton

Create a singleton manager that uses Photon RPCs to broadcast and receive anchor UUIDs across the network.

```csharp
using System.Collections;  
using System.Collections.Generic;  
using UnityEngine;  
using Photon.Pun;  
using Photon.Realtime;  
using NRKernal.NRExamples;  
  
public class UUIDManager : MonoBehaviourPun  
{  
    public static UUIDManager instance; // 单例实例  
  
    private void Awake()  
    {  
        if (instance == null)  
        {  
            instance = this;  
        }  
        else if (instance != this)  
        {  
            Destroy(gameObject);  
        }  
    }  
  
    [PunRPC]  
    public void ShareAnchorUUID(string uuid)  
    {  
        photonView.RPC("ReceiveAnchorUUID", RpcTarget.Others, uuid);  
    }  
  
    [PunRPC]  
    public void ReceiveAnchorUUID(string uuid)  
    {  
        Debug.Log("Received UUID: " + uuid);  
  
        GameObject localMapDemo = GameObject.Find("LocalMapDemo");  
        if (localMapDemo != null)  
        {  
            LocalMapExample localMapExample = localMapDemo.GetComponent<LocalMapExample>();  
            if (localMapExample != null)  
            {  
                localMapExample.CloudLoad(uuid);  
                Debug.Log("CloudLoad:"+uuid);  
            }  
            else  
            {  
                Debug.LogError("LocalMapExample component not found");  
            }  
        }  
        else  
        {  
            Debug.LogError("LocalMapDemo GameObject not found");  
        }  
    }  
  
}  
```

--------------------------------

### Create a Spatial Anchor in C#

Source: https://docs.xreal.com/Spatial%20Anchor/Anchors

Instantiates an ARAnchor prefab at a position relative to the camera's transform.

```csharp
public void OnNewButtonClick()  
{  
    var targetPos = m_Camera.transform.position + m_Camera.transform.forward * 1f;  
    var targetRotation = m_Camera.transform.rotation;  
    var anchor = Instantiate(m_ARAnchorPrefab, targetPos, targetRotation);  
}  
```

--------------------------------

### Create a Color-Switching Script

Source: https://docs.xreal.com/Input%20and%20Interactions/Controller

Attach this script to a GameObject to cycle through colors when the OnMouseDown event is triggered.

```csharp
  using UnityEngine;  
  
  public class ChangeColorOnClick : MonoBehaviour  
  {  
      // Define an array of colors to choose from  
      public Color[] colors;  
  
      // Reference to the Renderer component  
      private Renderer ballRenderer;  
  
      // Index to track current color  
      private int currentColorIndex = 0;  
  
      void Start()  
      {  
          // Get the Renderer component of the GameObject  
          ballRenderer = GetComponent<Renderer>();  
  
          // Initialize the colors array if it's empty  
          if (colors == null || colors.Length == 0)  
          {  
              colors = new Color[] { Color.red, Color.green, Color.blue, Color.yellow };  
          }  
  
          // Set initial color  
          ballRenderer.sharedMaterial.color = colors[currentColorIndex];  
      }  
  
      public void OnMouseDown()  
      {  
          // Change to the next color in the array  
          currentColorIndex = (currentColorIndex + 1) % colors.Length;  
  
          // Update the color of the material  
          ballRenderer.sharedMaterial.color = colors[currentColorIndex];  
      }  
  }  
```

--------------------------------

### Load NRWorldAnchor from Disk

Source: https://docs.xreal.com/Spatial%20Anchor/Tutorial-HalloweenTreasureHunt/HandletheSituationofFailedAnchorSaving

Loads an anchor by UUID asynchronously and executes a callback on the main thread upon success.

```csharp
public void LoadwithUUID(string uuid, Action<UInt64> action)  
        {  
            if (m_Anchor2ObjectDict.ContainsKey(uuid))  
            {  
                string path = Path.Combine(MapPath, uuid);  
                if (File.Exists(path))  
                {  
                    AsyncTaskExecuter.Instance.RunAction(() =>  
                    {  
                        UInt64 handle = 0;  
#if UNITY_EDITOR  
                        handle = (ulong)UnityEngine.Random.Range(1, int.MaxValue);  
#else  
                        handle = m_NativeMapping.LoadAnchor(path);  
#endif  
                        MainThreadDispather.QueueOnMainThread(() =>  

```

--------------------------------

### Estimate Mapping Quality in C#

Source: https://docs.xreal.com/Spatial%20Anchor/Anchors

Assesses environment scanning quality during anchor creation to ensure future reliability.

```csharp
public void OnNewButtonClick()  
{  
    //...  
    var anchor = Instantiate(m_ARAnchorPrefab, targetPos, targetRotation);  
      
    MapQualityIndicator.SetCurrentAnchor(anchor, false);  
    MapQualityIndicator.ShowMappingGuide();  
      
    Debug.Log($"[Anchors] Created Anchor at {targetPos}");  
}  
```

--------------------------------

### Implement Mesh Update Processing

Source: https://docs.xreal.com/MigratingFromNRSDKToXREALSDK/Migration_Meshing

Transition from the IMeshInfoProcessor interface to the AR Foundation meshesChanged event subscription.

```csharp
// Old code - IMeshInfoProcessor implementation  
void UpdateMeshInfo(ulong identifier, NRMeshInfo meshInfo) {  
    switch(meshInfo.state) {  
        case NRMeshingBlockState.NR_MESHING_BLOCK_STATE_NEW:  
        case NRMeshingBlockState.NR_MESHING_BLOCK_STATE_UPDATED:  
            // Process the added and updated mesh  
            break;  
        case NRMeshingBlockState.NR_MESHING_BLOCK_STATE_DELETED:  
            // Process the deleted mesh  
            break;  
    }  
}  
  
// New code - ARMeshesChanged event subscription  
void OnEnable() {  
    meshManager.meshesChanged += OnMeshesChanged;  
}  
  
void OnMeshesChanged(ARMeshesChangedEventArgs args) {  
    // Process the added mesh  
    foreach(var mesh in args.added) {  
        // Process the new mesh  
    }  
      
    // Process the updated mesh  
    foreach(var mesh in args.updated) {  
        // Update the mesh  
    }  
      
    // Process the deleted mesh  
    foreach(var mesh in args.removed) {  
        // Clean up the mesh  
    }  
}
```

--------------------------------

### Save Anchor with Callback

Source: https://docs.xreal.com/Spatial%20Anchor/Tutorial-HalloweenTreasureHunt/HandletheSituationofFailedAnchorSaving

Saves an NRWorldAnchor to local storage and executes a callback upon completion or failure.

```csharp
    public delegate void SaveAnchorCallback(bool success);  
  
        /// <summary>  
        /// Saves the provided NRWorldAnchor with the UserDefinedKey. If the identifier is already  
        /// in use, the method will return false. </summary>  
        /// <param name="anchor"> .</param>  
        /// <returns> True if it succeeds, false if it fails. </returns>  
        public void SaveAnchor(NRWorldAnchor anchor, SaveAnchorCallback callback)  
        {  
            NRDebugger.Info("[NRWorldAnchorStore] Save Anchor: {0}", anchor.UserDefinedKey);  
            if (m_Anchor2ObjectDict.ContainsKey(anchor.UUID))  
            {  
                NRDebugger.Warning("[NRWorldAnchorStore] Save a new anchor that has already been saved.");  
                callback?.Invoke(false);  
            }  
  
            try  
            {  
                m_Anchor2ObjectDict.Add(anchor.UUID, anchor.UserDefinedKey);  
                string json = LitJson.JsonMapper.ToJson(m_Anchor2ObjectDict);  
                string path = Path.Combine(MapPath, Anchor2ObjectFile);  
                NRDebugger.Info("[NRWorldAnchorStore] Save to the path:" + path + " json:" + json);  
                File.WriteAllText(path, json);  
                AsyncTaskExecuter.Instance.RunAction(() =>  
                {  
                    bool success = true;  
#if UNITY_EDITOR  
                    Thread.Sleep(1000);  
                    File.Create(Path.Combine(MapPath, anchor.UUID)).Dispose();  
#else  
                    success = m_NativeMapping.SaveAnchor(anchor.AnchorHandle, Path.Combine(MapPath, anchor.UUID));  
#endif  
                    if (!success)  
                    {  
                        MainThreadDispather.QueueOnMainThread(() =>  
                        {  
                            NRDebugger.Info("[NRWorldAnchorStore] Save Anchor failed.");  
                            m_Anchor2ObjectDict.Remove(anchor.UUID);  
                            saveStatus = false;  
          callback?.Invoke(false);  
                        });  
                    }  
                    else  
                    {  
      callback?.Invoke(true);  
      UnityEngine.Debug.Log("[NRWorldAnchorStore] Save Anchor successfully");  
                        saveStatus = true;  
      bool result=File.Exists(Path.Combine(MapPath, anchor.UUID));  
      if(!result)  
      {  
          
        Debug.LogError($"File {Path.Combine(MapPath, anchor.UUID)} does not exist!");  
      }  
      else{  
        Debug.Log($"File {Path.Combine(MapPath, anchor.UUID)} exist!");  
      }  
                    }  
                });  
            }  
            catch (Exception e)  
            {  
                NRDebugger.Warning("[NRWorldAnchorStore] Write anchor to object dict exception:" + e.ToString());  
                callback?.Invoke(false);  
            }  
        }
```

--------------------------------

### Capture Debug Logs via ADB

Source: https://docs.xreal.com/Frequently%20Asked%20Questions

Commands to connect to a device over TCP/IP, stop existing processes, and capture logs to a text file.

```bash
adb tcpip 5555 
```

```bash
adb connect [IP address]
```

```bash
adb shell ps|findstr [package keywords]
```

```bash
adb shell am force-stop [package name] 
```

```bash
adb logcat > logcat.txt
```

--------------------------------

### Implement Sphere Shooting Logic

Source: https://docs.xreal.com/Depth%20Mesh/Tutorial-Mesh%20Collision

Attach this script to the NRCameraRig to enable shooting spheres from the controller's raycast position upon trigger input.

```csharp
using System.Collections;  
using System.Collections.Generic;  
using UnityEngine;  
using NRKernal;  
  
public class Shoot : MonoBehaviour  
{  
    public float moveSpeed = 10f;  
    public GameObject shootPos;  
    public float force = 1000;  
    public GameObject ballPrefab;  
  
    Vector3 targetObjectNextPosition;  
  
    RaycastHit hit;  
  
    void FixedUpdate()  
    {  
        if (NRInput.GetButtonDown(ControllerButton.TRIGGER))  
        {  
            var handControllerAnchor =  
                NRInput.DomainHand == ControllerHandEnum.Left  
                    ? ControllerAnchorEnum.LeftLaserAnchor  
                    : ControllerAnchorEnum.RightLaserAnchor;  
            Transform laserAnchor = NRInput.AnchorsHelper.GetAnchor(  
                NRInput.RaycastMode == RaycastModeEnum.Gaze  
                    ? ControllerAnchorEnum.GazePoseTrackerAnchor  
                    : handControllerAnchor  
            );  
  
            Ray ray =new Ray(laserAnchor.transform.position, laserAnchor.transform.forward);  
  
            Rigidbody ball = Instantiate(ballPrefab, shootPos.transform.position, Quaternion.identity).GetComponent<Rigidbody>() as Rigidbody;  
            ball.AddForce(force * ray.direction);  
              
        }  
    }  
  
}  
```

--------------------------------

### Implement CloudSaveAnchor in NRWorldAnchorStore

Source: https://docs.xreal.com/Spatial%20Anchor/Tutorial-Sharing%20Anchors/CloudSaveandLoad

Adds the CloudSaveAnchor method to the NRWorldAnchorStore class to handle uploading anchor data to cloud storage.

```csharp
namespace NRKernal.Persistence  
{  
    // ... Other codes ...  
  
    public class NRWorldAnchorStore : IDisposable  
    {   
        // ... Other codes ...  
        public const string CloudAnchor2ObjectFile = "cloud_anchor2object.json";  
    /// <summary>save an anchor to firebase cloud server</summary>  
        public async Task<bool> CloudSaveAnchor(NRWorldAnchor anchor)  
        {  
            NRDebugger.Info("[NRWorldAnchorStore] Cloud save Anchor: {0}", anchor.UserDefinedKey);  
  
            string localFilename = Path.Combine(MapPath, anchor.UUID);  
            Debug.LogError("UploadFile: "+localFilename);  
            NRDebugger.Info("[NRWorldAnchorStore] UploadFile:" + localFilename);  
              
        FirebaseStorageManager storageManager = FirebaseStorageManager.Instance;  
        await storageManager.UploadFile(anchor.UUID, localFilename);  
            // Update the cloud anchor to object dictionary  
  
            // Save the dictionary to a JSON file  
            string json = LitJson.JsonMapper.ToJson(m_Anchor2ObjectDict);  
            string path = Path.Combine(MapPath, CloudAnchor2ObjectFile);  
            NRDebugger.Info("[NRWorldAnchorStore] Save to the path for next upload:" + path + " json:" + json);  
            File.WriteAllText(path, json);  
  
            // Upload the JSON file to the cloud  
          
        await storageManager.UploadFile(CloudAnchor2ObjectFile, path);  
  
            return true;  
        }  
      
    }  
  
        // ... Other codes ...  
    }  
}
```

```csharp
namespace NRKernal.Persistence  
{  
// ... Other codes ...  
  
    public class NRWorldAnchorStore : IDisposable  
    {  
        // ... Other codes ...  
  
        private AliyunOSSManager ossManager;  
  
        // ... Other codes ...  
  
        public const string CloudAnchor2ObjectFile = "cloud_anchor2object.json";  
        /// <summary>save an anchor to Aliyun cloud server</summary>  
        public async Task<bool> CloudSaveAnchor(NRWorldAnchor anchor)  
            {  
                NRDebugger.Info("[NRWorldAnchorStore] Cloud save Anchor: {0}", anchor.UserDefinedKey);  
  
                string localFilename = Path.Combine(MapPath, anchor.UUID);  
                Debug.LogError("UploadFile: "+localFilename);  
                NRDebugger.Info("[NRWorldAnchorStore] UploadFile:" + localFilename);  
  
  
                ossManager = AliyunOSSManager.Instance;  
                // FirebaseStorageManager storageManager = FirebaseStorageManager.Instance;  
                await ossManager.UploadFile(anchor.UUID, localFilename);  
                // Update the cloud anchor to object dictionary  
  
                // Save the dictionary to a JSON file  
                string json = LitJson.JsonMapper.ToJson(m_Anchor2ObjectDict);  
                string path = Path.Combine(MapPath, CloudAnchor2ObjectFile);  
                NRDebugger.Info("[NRWorldAnchorStore] Save to the path for next upload:" + path + " json:" + json);  
                File.WriteAllText(path, json);  
  
                // Upload the JSON file to the cloud  
                await ossManager.UploadFile(CloudAnchor2ObjectFile, path);  
  
                return true;  
            }  
  
        // ... Other codes ...  
        }  
    }
```

--------------------------------

### Configure AndroidManifest.xml for Device Support

Source: https://docs.xreal.com/Frequently%20Asked%20Questions

Add this meta-data tag to your AndroidManifest.xml to ensure your application is recognized as supported by XREAL devices.

```xml
<meta-data android:name="com.nreal.supportDevices" android:value="1|XrealLight|2|XrealAir" />  
```

--------------------------------

### Replace NRInput Calls with XREALInput

Source: https://docs.xreal.com/MigratingFromNRSDKToXREALSDK/intro

Directly swap NRInput class calls for XREALInput to maintain existing logic while using the new SDK.

```csharp
// Old code  
if (NRInput.GetButtonDown(ControllerButton.TRIGGER)) { }  
Vector3 position = NRInput.GetPosition();  
NRInput.TriggerHapticVibration(duration, amplitude);  
  
// New code  
if (XREALInput.GetButtonDown(ControllerButton.TRIGGER)) { }  
Vector3 position = XREALInput.GetPosition();  
XREALInput.TriggerHapticVibration(duration, amplitude);  
```

--------------------------------

### Implement a Button Manager

Source: https://docs.xreal.com/Input%20and%20Interactions/Controller

Use this manager to locate scene objects and expose methods for UI button OnClick() callbacks.

```csharp
using System.Collections;  
using System.Collections.Generic;  
using Unity.VisualScripting;  
using UnityEngine;  
  
public class Manager : MonoBehaviour  
{  
    // Start is called before the first frame update  
    ChangeColorOnClick cube;  
    void Start()  
    {  
        cube = FindObjectOfType<ChangeColorOnClick>();  
    }  
  
    // Update is called once per frame  
    void Update()  
    {  
          
    }  
  
    public void changeColor()  
    {  
        cube.OnMouseDown();  
    }  
  
}  
```

--------------------------------

### AR Foundation Image Tracking Event Handling

Source: https://docs.xreal.com/MigratingFromNRSDKToXREALSDK/Migration_ImageTracking

Implementation of image tracking lifecycle management using AR Foundation's trackedImagesChanged event.

```csharp
using UnityEngine;  
using UnityEngine.XR.ARFoundation;  
  
public class ImageTrackingExample : MonoBehaviour  
{  
    private ARTrackedImageManager m_TrackedImageManager;  
  
    void Awake()  
    {  
        m_TrackedImageManager = GetComponent<ARTrackedImageManager>();  
    }  
  
    void OnEnable()  
    {  
        m_TrackedImageManager.trackedImagesChanged += OnTrackedImagesChanged;  
    }  
  
    void OnDisable()  
    {  
        m_TrackedImageManager.trackedImagesChanged -= OnTrackedImagesChanged;  
    }  
  
    private void OnTrackedImagesChanged(ARTrackedImagesChangedEventArgs args)  
    {  
        foreach (var trackedImage in args.added)  
        {  
            // Handle newly detected images  
            Debug.Log($"Detected image: {trackedImage.referenceImage.name}");  
        }  
  
        foreach (var trackedImage in args.updated)  
        {  
            // Handle updated images  
        }  
  
        foreach (var trackedImage in args.removed)  
        {  
            // Handle removed images  
        }  
    }  
}  
```

--------------------------------

### AR Foundation Anchor Management

Source: https://docs.xreal.com/MigratingFromNRSDKToXREALSDK/Migration_Anchors

Implementation using ARAnchorManager to handle anchor lifecycle events and creation.

```csharp
using UnityEngine;  
using UnityEngine.XR.ARFoundation;  
  
public class AnchorManager : MonoBehaviour  
{  
    private ARAnchorManager m_AnchorManager;  
  
    void Awake()  
    {  
        m_AnchorManager = GetComponent<ARAnchorManager>();  
    }  
  
    void OnEnable()  
    {  
        m_AnchorManager.anchorsChanged += OnAnchorsChanged;  
    }  
  
    void OnDisable()  
    {  
        m_AnchorManager.anchorsChanged -= OnAnchorsChanged;  
    }  
  
    public void AddAnchor(Vector3 position, Quaternion rotation)  
    {  
        var pose = new Pose(position, rotation);  
        var anchor = m_AnchorManager.AddAnchor(pose);  
    }  
  
    private void OnAnchorsChanged(ARAnchorsChangedEventArgs args)  
    {  
        foreach (var anchor in args.added)  
        {  
            // Handle newly added anchors  
        }  
  
        foreach (var anchor in args.updated)  
        {  
            // Handle updated anchors  
        }  
  
        foreach (var anchor in args.removed)  
        {  
            // Handle removed anchors  
        }  
    }  
}  

```

--------------------------------

### NRSDK Plane Detection Implementation

Source: https://docs.xreal.com/MigratingFromNRSDKToXREALSDK/Migration_PlaneDetection

Legacy implementation using NRSDK's NRFrame to manually query and instantiate trackable planes.

```csharp
public class PlaneDetector : MonoBehaviour  
{  
    public GameObject DetectedPlanePrefab;  
    private List<NRTrackablePlane> m_NewPlanes = new List<NRTrackablePlane>();  
  
    public void Update()  
    {  
        NRFrame.GetTrackables<NRTrackablePlane>(m_NewPlanes, NRTrackableQueryFilter.New);  
        for (int i = 0; i < m_NewPlanes.Count; i++)  
        {  
            GameObject planeObject = Instantiate(DetectedPlanePrefab, Vector3.zero, Quaternion.identity, transform);  
            planeObject.GetComponent<NRTrackableBehaviour>().Initialize(m_NewPlanes[i]);  
        }  
    }  
}  
```

--------------------------------

### Implement Custom Button Functionality in C#

Source: https://docs.xreal.com/Input%20and%20Interactions/Controller

Use this script to handle input actions from a custom button, such as changing a GameObject's color upon interaction.

```csharp
using System.Collections;  
using System.Collections.Generic;  
using UnityEngine;  
using UnityEngine.InputSystem;  
public class CustomButtonActionHandler : MonoBehaviour  
{  
    public InputActionReference buttonAction; // Drag your InputAction here in the Inspector  
    public GameObject sphere; // Drag your sphere GameObject here in the Inspector  
    public Color targetColor = Color.red; // Color to change to when button is pressed  
  
    private Renderer sphereRenderer;  
    private Color originalColor;  
  
    private void Awake()  
    {  
        if (sphere != null)  
        {  
            sphereRenderer = sphere.GetComponent<Renderer>();  
            originalColor = sphereRenderer.material.color;  
        }  
    }  
  
    private void OnEnable()  
    {  
        buttonAction.action.performed += OnButtonPressed;  
        buttonAction.action.Enable();  
    }  
  
    private void OnDisable()  
    {  
        buttonAction.action.performed -= OnButtonPressed;  
        buttonAction.action.Disable();  
    }  
  
    private void OnButtonPressed(InputAction.CallbackContext context)  
    {  
        if (sphereRenderer != null)  
        {  
            sphereRenderer.material.color = targetColor;  
        }  
    }  
}  
```

--------------------------------

### Cloud Anchor Persistence

Source: https://docs.xreal.com/Spatial%20Anchor/Tutorial-HalloweenTreasureHunt/HandletheSituationofFailedAnchorSaving

Uploads an anchor file and the associated metadata dictionary to cloud storage.

```csharp
        public const string CloudAnchor2ObjectFile = "cloud_anchor2object.json";  
      /// <summary>save an anchor to aliyun cloud server</summary>  
        public async Task<bool> CloudSaveAnchor(NRWorldAnchor anchor)  
        {  
            NRDebugger.Info("[NRWorldAnchorStore] Cloud save Anchor: {0}", anchor.UserDefinedKey);  
  
            string localFilename = Path.Combine(MapPath, anchor.UUID);  
            Debug.LogError("UploadFile: "+localFilename);  
            NRDebugger.Info("[NRWorldAnchorStore] UploadFile:" + localFilename);  
            //ossManager.UploadFile(anchor.UUID, localFilename);  
      FirebaseStorageManager storageManager = FirebaseStorageManager.Instance;  
      await storageManager.UploadFile(anchor.UUID, localFilename);  
  
            // Save the dictionary to a JSON file  
            string json = LitJson.JsonMapper.ToJson(m_Anchor2ObjectDict);  
            string path = Path.Combine(MapPath, CloudAnchor2ObjectFile);  
            NRDebugger.Info("[NRWorldAnchorStore] Save to the path for next upload:" + path + " json:" + json);  
            File.WriteAllText(path, json);  
  
            // Upload the JSON file to the cloud  
            //ossManager.UploadFile(CloudAnchor2ObjectFile, path);  
      await storageManager.UploadFile(CloudAnchor2ObjectFile, path);  
  
            return true;  
        }
```

--------------------------------

### Resolve Unity Build Errors in mainTemplate.gradle

Source: https://docs.xreal.com/Frequently%20Asked%20Questions

Update the aaptOptions in your mainTemplate.gradle file to fix build failures related to the noCompress property.

```text
UnityException: Error  
mainTemplate.gradle file is using the old aaptOptions noCompress property definition which does not include types defined by unityStreamingAssets constant.  
UnityEngine.GUIUtility:ProcessEvent(Int32, IntPtr, Boolean&) (at /Users/bokken/build/output/unity/unity/Modules/IMGUI/GUIUtility.cs:189)  
```

```gradle
aaptOptions {  
        noCompress = ['.unity3d', '.ress', '.resource','unityStreamingAssets', '.obb'**STREAMING_ASSETS**]  
    }**SIGN**  
```

--------------------------------

### Migrate NRInput Button Checks to Input Actions

Source: https://docs.xreal.com/MigratingFromNRSDKToXREALSDK/intro

Replace legacy NRInput button polling with the Unity Input Action system using InputActionProperty.

```csharp
// Old NRInput code  
if (NRInput.GetButtonDown(ControllerButton.TRIGGER)) {  
    // Handle trigger press  
}  
  
// New Input Action code  
[SerializeField]  
private InputActionProperty m_TriggerAction;  
  
private void OnEnable() {  
    m_TriggerAction.action.performed += OnTriggerPressed;  
}  
  
private void OnTriggerPressed(InputAction.CallbackContext context) {  
    // Handle trigger press  
}  
```

--------------------------------

### Implement CloudSaveAnchor in NRWorldAnchor

Source: https://docs.xreal.com/Spatial%20Anchor/Tutorial-Sharing%20Anchors/CloudSaveandLoad

Adds the CloudSaveAnchor method to the NRWorldAnchor class. Ensure the System.Threading.Tasks namespace is included.

```csharp
public async Task<bool> CloudSaveAnchor()  
        {  
            return await NRWorldAnchorStore.Instance.CloudSaveAnchor(this);  
        }
```

--------------------------------

### Implement Automatic Sphere Destruction

Source: https://docs.xreal.com/Depth%20Mesh/Tutorial-Mesh%20Collision

Attach this script to the sphere prefab to ensure it is destroyed 10 seconds after instantiation to conserve scene resources.

```csharp
using System.Collections;  
using System.Collections.Generic;  
using UnityEngine;  
  
public class sphere : MonoBehaviour  
{  
    // Start is called before the first frame update  
    void Start()  
    {  
        Invoke("DelayDestroy", 10); // * destroy the prefab after 10 seconds  
    }  
  
    // Update is called once per frame  
    void DelayDestroy()  
    {  
        Destroy(this.gameObject);  
    }  
}  
```

--------------------------------

### Update Namespace References for Compatibility Layer

Source: https://docs.xreal.com/MigratingFromNRSDKToXREALSDK/intro

Switch namespace imports when using the XREALInput compatibility layer.

```csharp
// Old code  
using NRInput;  
  
// New code  
using Unity.XR.XREAL.Samples;  
```

--------------------------------

### Replace Meshing Manager Component

Source: https://docs.xreal.com/MigratingFromNRSDKToXREALSDK/Migration_Meshing

Replace the NRSDK NRMeshingManager with the AR Foundation ARMeshManager.

```csharp
// Old code  
NRMeshingManager meshingManager;  
  
// New code  
ARMeshManager meshManager;
```

--------------------------------

### Load Spatial Anchors in C#

Source: https://docs.xreal.com/Spatial%20Anchor/Anchors

Triggers the loading process for all previously saved anchors.

```csharp
public void OnLoadAllButtonClick()  
{  
    LoadAllAnchors();  
}  
```

--------------------------------

### Migrate Haptic Feedback

Source: https://docs.xreal.com/MigratingFromNRSDKToXREALSDK/intro

Update haptic vibration triggers to use the XRController SendHapticImpulse method.

```csharp
// Old NRInput code  
NRInput.TriggerHapticVibration(duration, amplitude);  
  
// New Input System code  
public XRController controller;  
  
void TriggerHaptic() {  
    controller.SendHapticImpulse(0, amplitude, duration);  
}  
```

--------------------------------

### Configure Android Manifest for Vibration

Source: https://docs.xreal.com/Input%20and%20Interactions/Controller

Include this XML in the AndroidManifest.xml file located in Assets/Plugins/Android/ to request vibration permissions.

```xml
<?xml version="1.0" encoding="utf-8"?>  
<manifest xmlns:android="http://schemas.android.com/apk/res/android"  
    package="com.DefaultCompany.xrealsdktest">  
  
    <!-- Request vibration permission -->  
    <uses-permission android:name="android.permission.VIBRATE"/>  
  
</manifest>
```
Tokens:
Raw