FAQ
Frequently asked questions about the MeshMap Unity SDK.
General
Which Unity version should I use?
MeshMap XR targets Unity 6000.0.50f1 LTS (Unity 6).
Core and Building Blocks work on Unity 2022.3.11 LTS or later.
ML2 Support supports 2022.3.11 LTS or later.
For new projects, we strongly recommend using Unity 6000.0.50f1 LTS.
Make sure to include the Android Build Support module.
For more information, see Getting Started.
Which render pipeline should I use?
All of MeshMap's packages, samples, and example projects use the Universal Render Pipeline (URP).
For more information, see Getting Started.
How do I add the packages to my project?
The recommended and easiest way to get started is by downloading one of our Example Projects.
Alternatively, you can add individual packages by Git URL in the Package Manager window. Make sure to include the VContainer scoped registry first in the Project Settings, and satisfy all package dependencies.
The SDK assets are added to the Packages folder.
For more information, see Using Our Packages.
Should I start from scratch or a sample?
We highly encourage starting with an Example Project so all the device settings, permissions, and profiles are pre-configured. Starting from a sample will reduce the likelihood of avoidable Project Settings errors arising.
From there, you can change the project to match your unique vision!
Core
Why aren't Auth and Scans working?
You must create a MeshMap account and configure your API key in the MeshMap Hub (MeshMap > MeshMap Hub). Without that, Auth and Scans features won’t function.
Add user.keystore and Assets/Resources/ApiKeyConfig.asset to .gitignore. Otherwise API credentials or user keys may leak/change across versions and machines.
Where in my project are the imported scans saved?
Using the Scan Importer tool saves imported files under Assets/Resources/MeshMap/Scans/.
For more information, see Scans.
XR
How do I safely run multiple XR device SDKs in one project?
Use the MeshMap XR packages' Cross-platform Management system with Unity 6 build profiles to automatically wrap each SDK in scripting defines and use custom Android manifests and Gradle templates.
This will prevent duplicate native libs and wrong platform plugins from being included in the build process.
Why isn't my project building or running correctly?
Carefully follow the steps in Cross-platform Management that are relevant to your target device(s). Refer to the screenshots to review each setting.
We highly recommend using version control, such as Git, for your project. If something goes wrong, you can reclone your project from the last stable version.
Which plugins and feature groups do I need to change for different target devices?
Magic Leap 2: Enable OpenXR and Magic Leap 2 feature group.
Meta Quest 3: Enable OpenXR and Meta Quest feature group. Some Project Validation checks should remain unfixed if you’re using the Marker Tracker feature.
XREAL Air 2 Ultra: Enable XREAL plugin and disable OpenXR. Failing to disable OpenXR may break runtime.
Which XR rig should I use?
Use the Cross-platform XR Rig prefab. XRRigPlatformProvider ensures the correct device-specific setup is active at runtime.
Custom rigs without this pattern may lose input/tracking per device.
For more information, see Rigs.
How do I enable hand tracking and controllers?
Use CustomXRInputModalityManager to smoothly switch between hand tracking and controllers. It includes quality of life features like fallback to controller input when a button is pressed.
Hand-only or controller-only input setup may strand users.
For more information, see Rigs and Interactors.
XR - Marker Tracking
Which devices support Marker Tracking?
The XR package currently supports marker tracking on Magic Leap 2 and Meta Quest 3.
XREAL has its own native image and marker tracking solution.
How do I start using the Marker Tracking feature?
The easiest way to get started is to download the Location-based AR Sample or import the Marker Tracking sample and use the Marker Tracker prefab.
The prefab manages marker detection, tracking, localization, and calibration, including dependency injection and UI.
For more information, see Marker Tracking.
If you are only targeting Magic Leap 2, you can instead use the Magic Leap 2 Support package, but it is no longer being updated. We recommend new projects use the XR package.
How do I link markers, visuals, and content groups correctly?
Use MarkerTrackingControls to map Marker IDs → Visuals → Content Groups.
It supports single and multiple marker tracking.
For more information, see Marker Tracking Setup.
Which fiducial marker type should I use?
AprilTags are recommended for accurate pose detection and supported for Magic Leap 2 and Magic Quest 3. Print the tags at ~17 cm size with ~2 cm margins.
Magic Leap 2 also supports ArUco markers and QR codes. The latter can be encoded with a ? parameter (e.g., ?marker=) so that phone cameras open a custom URL while marker tracking decodes only the ending.
For more information, see Marker Tracking.
How can I make custom fiducial markers?
The custom AR Marker Generator tool allows you to generate and save markers with your desired type, ID, size, and encoding.
For more information, see AR Marker Generator.
Magic Leap 2 Support
Why does my official Magic Leap Unity SDK not match the version that MeshMap uses?
The ML2 Support package uses a modified Magic Leap SDK to prevent compilation errors with Unity OpenXR 1.15.0. Always use the modified package with the MeshMap SDK.
Will the Magic Leap 2 Support package continue to receive new features?
No, the ML2 Support package has been deprecated in favor of the MeshMap XR package. If you are starting a new cross-platform project, we recommend primarily using the XR package.
Building Blocks
Why isn't my app's audio working?
There are several potential reasons why audio may be disabled in your app.
First, if you are using the Building Blocks's Audio Manager, make sure that you have an AudioRegistry asset in a Resources folder. Without it, key-to-clip lookups fail silently. See Audio.
If that doesn't solve it, make sure any platform-specific settings are correctly configured. See Cross-platform Management. Also refer to the official documentation for your target device.
There is a rare bug that mutes audio only in Meta Quest 3 and XREAL Air 2 Ultra app builds that we are still working to fix. Deleting and recloning your project will resolve this bug. As such, we highly recommend using Git version control to save your project.
Why aren't the trigger events in my scene being triggered?
Make sure that each trigger event (e.g., ShowObjectsTriggerEvent) has a Collider with IsTrigger set to True. If necessary, increase the bounds of the Collider to be large enough for the player to enter/exit.
Make sure the player's XR Rig has a GameObject with the tag (e.g., "Player") that is set in the event's PlayerTag field ("Player" by default). This same object should have a Collider with IsTrigger set to True and a RigidBody with UseGravity set to False.
Confirm in the Inspector that none of the other fields are empty, which would result in a NullReferenceException error code.
Review the setup of any of the Events prefabs in the Building Blocks package.
For more information, see Events.
Why aren't my settings and progress being saved?
Make sure you have a SaveManager in your scene and the data you are trying to save is done so through a component that implements ISaveable (or inherits SaveableMonoBehaviour) with unique SaveIds.
Check that every ISaveable instance has a unique ID assigned in the Inspector. Use the Assign IDs and Clear and Reassign IDs buttons in the Inspector to auto-set these.
For more information, see Save System.
Last updated