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 RealityKit or Hybrid is selected as the current App Mode in Project Settings > XR Plugin-in Management > Apple visionOS.

Q: I'm targeting visionOS with a RealityKit 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, please contact the Unity team.
  • When using an Unbounded camera, the platform is responsible for choosing the (0,0,0) origin and may choose a position for it that is unexpected. Look around (literally) to see if your content is somewhere other than where 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.
  • 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 open ImmersiveSpace. 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 Build Profiles > visionOS >