Skip to main content

AR Foundation 5.0 Support (Experimental)

Along with the release of Pretia SDK v0.8.0, we have added support for the SDK to be compatible with AR Foundation 5.0.

In general, there are some changes we need to be mindful of while migrating AR Foundation 4 to 5. This document will walk you through a step-by-step guide in how you can safely migrate your Unity project using AR Foundation 4 to AR Foundation 5, and what needs to be done in correlation with Pretia SDK within the process.

AR Foundation 5 Changes​

In order to better understand what are the changes included in AR Foundation, please refer to Unity's documentation on what's new in AR Foundation 5.

It is also recommended to read Unity's documentation on AR Foundation 5.x migration guide.

Migration Steps​

⚠ This migration process will bring a lot of changes to your Unity project. It is highly recommended to have a backup of your project before proceeding with the migration steps. ⚠

Upgrade Unity Version​

AR Foundation 5 is only supported on Unity v2021.2 or higher. If you're using an older version that 2021.2, download and install a newer Unity version. We recommend using the latest 2021.3 LTS for the most up-to-date compatibility with AR Foundation 5.

Import Pretia SDK v0.8.0 or Higher​

Follow the steps listed on Importing Pretia SDK to import the latest version of Pretia SDK. Make sure that the version is at least v0.8.0 or higher.

Upgrade AR Foundation​

At the time of writing, AR Foundation 5 does not appear in the Package Manager window and needs to be installed by manually modifying manifest.json file in the Unity project directory.

Copied verbatim from Unity's documentation:

AR Foundation 5.0 is compatible with Unity 2021.2 and 2021.3, but it does not appear in the Package Manager window of these Editor versions. See access AR Foundation 5.0 in Unity 2021 to learn how to edit your project manifest.

Open your manifest.json file and modify the files to specify AR Foundation dependencies explicitly. Save your changes and open Unity Editor.

com.unity.xr.arfoundation: 5.0.3,
com.unity.xr.arcore: 5.0.3
com.unity.xr.arkit: 5.0.3

Upon completing the importing process, you will see a warning dialogue saying that the project is using the new input system, and asks to restart the editor to enable them. Select the 'Yes' button to proceed.

Modify AR Session Origin​

One of the big change from previous versions of AR Foundation is that Unity is deprecating AR Session Origin, and will use a generalized XROrigin implementation instead.

In order to migrate safely, you will need to

  1. Change the script reference of ARSessionOrigin to XROrigin. In order to do this, first enable Debug mode from the Inspector window. Then select AR Session Origin game object.

  1. By enabling Debug mode, you will now be able to change the Script reference of the deprecated ARSessionOrigin to XROrigin.

  1. Disable Debug mode to return to normal mode.

  2. Create an empty game object as a child of AR Session Origin game object, and name it Camera Offset. Reparent your AR Camera game object under this new Camera Offset game object.

  1. Set the Camera Offset game object as the Camera Floor Offset Object field in the XROrigin component from the Inspector.

  1. Select the AR Camera game object and remove deprecated AR Pose Driver component

  1. Add the Tracked Pose Driver (Input System) component

  1. Configure Tracked Pose Driver (Input System) to use centerEyePosition/Rotation and devicePosition/Rotation. While it is possible to manually configure the component, we found that the easiest way to do this is to temporarily create an XROrigin game object by right-clicking on the Hierarchy window and select XR > XROrigin (Mobile AR). Then navigate to the Main Camera game object under the generated XR Origin, and copying from the generated Tracked Pose Driver (Input System) component by right-clicking the component.

  1. Select your AR Camera game object and paste the component configuration by right-clicking the Tracked Pose Driver (Input System) component and selecting Paste Component Values

  1. Delete the temporary XR Origin game object that was generated.

(Tentative) Replace Event System Input​

If you have an Event System component in your Scene, you might need to update your Event System to use the new Input System. Select your Event System game object and press the Replace with InputSystemUIInputModule button on the component.

Do note that since AR Foundation is using the new input system, any calls to Unity's legacy Input class would generate error at runtime. Please thoroughly go through your project and make modifications accordingly

Once you have done all the steps above, you are ready to use AR Foundation 5 in your Unity project. Depending on your implementations, there might be some changes you need to make in your codebase. Please follow Unity's migration guide for this part.

After your project is clear of any errors, you have successfully migrated your project to use AR Foundation 5.0. Doing it this way would ensure that your scenes and components keeps all previous references to the new XROrigin component, and thus minimize the amount of potential broken references.

As long as the reference is not broken, Pretia SDK components should be able to work with the new XROrigin component, so there is no further changes required in regards to specific Pretia SDK requirements.