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.
⚠ 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.
manifest.json file and modify the files to specify AR Foundation dependencies explicitly. Save your changes and open Unity Editor.
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
- Change the script reference of
XROrigin. In order to do this, first enable
Debugmode from the Inspector window. Then select
AR Session Origingame object.
- By enabling
Debugmode, you will now be able to change the
Scriptreference of the deprecated
Debugmode to return to normal mode.
Create an empty game object as a child of
AR Session Origingame object, and name it
Camera Offset. Reparent your
AR Cameragame object under this new
Camera Offsetgame object.
- Set the
Camera Offsetgame object as the
Camera Floor Offset Objectfield in the
XROrigincomponent from the Inspector.
- Select the
AR Cameragame object and remove deprecated
AR Pose Drivercomponent
- Add the
Tracked Pose Driver (Input System)component
Tracked Pose Driver (Input System)to use
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
XROrigingame object by right-clicking on the
Hierarchywindow and select
XR > XROrigin (Mobile AR). Then navigate to the
Main Cameragame object under the generated XR Origin, and copying from the generated
Tracked Pose Driver (Input System)component by right-clicking the component.
- Select your
AR Cameragame object and paste the component configuration by right-clicking the
Tracked Pose Driver (Input System)component and selecting
Paste Component Values
- Delete the temporary
XR Origingame 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
Inputclass 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.