docs.unity3d.com
Search Results for

    Show / Hide Table of Contents

    Frequently Asked Questions (FAQ)

    Q: I see different results running in the visionOS simulator than on Hardware

    • Note that when running in Simulator, some hardware-specific features are not available - most notably AR data. This could mean that the simulated outcomes in the visionOS simulator may be different from the simulation on the Vision Pro headset. Check out Apple’s guide on running your app in the simulator to learn more.
    • Please note that Unity is still building towards feature parity with the Metal API on XCode, so you might observe warnings from Metal’s API validation layer. To work around this, you can turn off the Metal API Validation Layer via XCode’s scheme menu.

    Q: How can I bring an existing mobile project to the visionOS Mixed Reality platform?

    Please check the Project conversion guide on the getting started page for information on enabling and using PolySpatial.

    Q: How can I bring an existing XR project to the visionOS Mixed Reality platform?

    You can check for a Project conversion guide on the getting started page

    Q: I enter Play Mode and see no visual or execution difference in my project!

    Ensure that you have visionOS as your active build target, and that Mixed Reality is selected as the current App Mode in Project Settings > XR Plugin-in Management > Apple visionOS.

    Q: I'm targeting visionOS with a Mixed Reality app, but nothing shows up!

    • Ensure you have a Volume Camera in your scene. An Unbounded Volume Camera with its origin positioned in the middle of your scene is a good starting point. If one is not present a default one will be created that will include the bounds of every object in the scene, but this may cause objects in the scene within the bounds of the volume camera to be too small to see.
    • Verify that the in-editor preview runtime is functioning. Open the “DontDestroyOnLoad” scene in the hierarchy while playing, and check if there is a "PolySpatial Root” object present. If there is not, ensure that the PolySpatial runtime is enabled. If it is enabled and nothing shows up, please contact the Unity team.
    • When using an Unbounded camera, the platform is responsible for choosing the (0,0,0) origin and may choose position for it that is unexpected. Look around (literally) to see if your content is somewhere other than here you think it should be. Rebooting the device can also help to reset its session space. It can be helpful to ensure that it is in a consistent location (for example, sitting on the desk, facing forward) every time you boot it up.

    Q: Skinned Meshes are not animating!

    • On the Animator component, ensure Culling Mode is set to Always Animate.
    • If the model is imported, navigate to the Import Settings for the model. Under the Rig tab, ensure Optimize Game Objects is unticked. Some models may not even have this setting; in that case, it should be good as-is.
    • Certain models may contain a skeleton (a set of bones in a hierarchy) that are incompatible with RealityKit. To be compatible, a skeleton must have the following attributes:
      1. A group of bones must have a common ancestor GameObject in the transform hierarchy.
      2. Each bone in the skeleton must be able to traverse up the transform hierarchy without passing any non-bone GameObjects.
    • In general, skeletons that have a non-bone GameObject somewhere in the skeleton (often used for scaling or offsets on bones) are not supported.

    Q: I see an error on build about ScriptableSingleton

    • This comes from the AR Foundation package and is benign. You can ignore this error.

    Q: I see a NullReferenceException or other issues in the log related to XXXX Tracker (Mesh Tracker, Sprite Tracker, etc)*

    • Please file a bug with reproduction steps using the bug reporter found in the Help menu. If this error is blocking you and you don't need the particular feature, you can disable the feature in Player Settings > PolySpatial > Disabled Features.

    Q: My TextMeshPro text shows up as Pink glyph blocks or My TextMeshPro text is blurry**

    • Locate the shader graphs included in the visionOS Package (visionOS/Resources/Shaders) and right click -> Reimport.

    Q: My content is too dark in visionOS simulator**

    • In the visionOS simulator, try using Device -> Erase All Content and Settings and/or switching to a different environment (Museum (Day) versus Living Room (Day), for instance).

    Q: Objects that are supposed to face the camera (transform.LookAt) are not working

    • Head pose tracking on visionOS is provided via ARKit, and is only available when your application has an ImmersiveSpace is open. In Unity, this is enabled by having a VolumeCamera active in Unbounded mode. You also need an ARSession component in your scene to start the ARKit session and enable head pose tracking. When these requirements are met, you can use a TrackedPoseDriver to update any transform based on head pose, and use that object as a lookAt target.

    Q: Transparent objects, sprites, or canvas elements are flickering with inconsistent sorting

    • Flickering can occur in transparent objects, sprites, and canvas elements, especially when intermixed with each other. You can prevent this by explicitly setting the sorting order using a VisionOSSortingGroup component.

    Q: I have built an XCode Project, but there is no option to run on the simulator

    • Check that Project Settings > Other > Target SDK is set to Simulator SDK
    • You can only create VisionOS builds with the Unity editor for Apple Silicon. Check that the title bar in Unity does not contain "<Rosetta>". If it does, use the Unity Hub to download the Apple Silicon version.
    • Make sure you have the VisionOS Simulator installed. In XCode, open Window > Devices and Simulators, and select the Simulators tab. If there is nothing listed, add one using the + button. If the Device Type menu has no Apple Vision Pro option available, you are likely using a non-beta version of XCode. Only beta versions currently support the VisionOS simulator.

    Common Errors

    Error: xcrun: error: unable to find utility "actool", not a developer tool or in PATH

    • Make sure you have XCode Beta installed
    • Open XCode, navigate to Settings > Locations > Command Line Tools and ensure XCode beta is selected. You may need to de-select and re-select the XCode version for the change to take effect.

    Error: Failed to find a suitable device for the type ...

    • This sometimes happens after an XCode upgrade. Restarting your computer usually fixes it.

    Play to Device Host

    I'm having trouble connecting to the Play to Device Host

    • Make sure both the host machine and the mobile device are connected to the same LAN. If they are not on the same LAN, you can add a direction connection using Advanced Settings in the Play To Device Editor Window.
    • Make sure your firewall is not blocking the connection. If it is, then you may have to temporarily disable it using the appropriate tool for your OS.

    I'm observing lag, or my editor seems to hang.

    In Unity Editor, try enabling Run in Background under Project Settings > Player > Resolution and Presentation. While this setting is not currently exposed under the visionOS platform, it is shared for all build targets. You can enable it under the Standalone build target tab.

    My app doesn't seem to receive any input once connected to the host.

    If your app is not receiving input from the Play To Device host (especially when using the visionOS Simulator), you may need to change your input settings. The PolySpatial package contains a preset input asset in its Package Manager samples, but the important settings to check are:

    • Background Behavior: Ignore Focus
    • Play Mode Input Behavior: All Device Input Always Goes To Game View

    Did you find this page useful? Please give it a rating:

    Thanks for rating this page!

    Report a problem on this page

    What kind of problem would you like to report?

    • This page needs code samples
    • Code samples do not work
    • Information is missing
    • Information is incorrect
    • Information is unclear or confusing
    • There is a spelling/grammar error on this page
    • Something else

    Thanks for letting us know! This page has been marked for review based on your feedback.

    If you have time, you can provide more information to help us fix the problem faster.

    Provide more information

    You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:

    You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:

    You've told us there is information missing from this page. Please tell us more about what's missing:

    You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:

    You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:

    You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:

    You've told us this page has a problem. Please tell us more about what's wrong:

    Thank you for helping to make the Unity documentation better!

    Your feedback has been submitted as a ticket for our documentation team to review.

    We are not able to reply to every ticket submitted.

    In This Article
    • Frequently Asked Questions (FAQ)
      • Q: I see different results running in the visionOS simulator than on Hardware
      • Q: How can I bring an existing mobile project to the visionOS Mixed Reality platform?
      • Q: How can I bring an existing XR project to the visionOS Mixed Reality platform?
      • Q: I enter Play Mode and see no visual or execution difference in my project!
      • Q: I'm targeting visionOS with a Mixed Reality app, but nothing shows up!
      • Q: Skinned Meshes are not animating!
      • Q: I see an error on build about ScriptableSingleton
      • Q: I see a NullReferenceException or other issues in the log related to XXXX Tracker (Mesh Tracker, Sprite Tracker, etc)*
      • Q: My TextMeshPro text shows up as Pink glyph blocks or My TextMeshPro text is blurry**
      • Q: My content is too dark in visionOS simulator**
      • Q: Objects that are supposed to face the camera (transform.LookAt) are not working
      • Q: Transparent objects, sprites, or canvas elements are flickering with inconsistent sorting
      • Q: I have built an XCode Project, but there is no option to run on the simulator
    • Common Errors
      • Error: xcrun: error: unable to find utility "actool", not a developer tool or in PATH
      • Error: Failed to find a suitable device for the type ...
    • Play to Device Host
    Back to top
    Copyright © 2025 Unity Technologies — Trademarks and terms of use
    • Legal
    • Privacy Policy
    • Cookie Policy
    • Do Not Sell or Share My Personal Information
    • Your Privacy Choices (Cookie Settings)