Published on
May 17, 2024
This guide is designed to help you navigate the transition from XRI 2.x to XRI 3.0, providing essential information and practical tips for a smooth upgrade. If you are new to working with Unity, please refer to the XRI Installation Guide for basic instructions. For a quick overview of what's new in XRI 3.0, check out our post on What is new in XR Interaction Toolkit 3.0.
XRI 3.0 is not yet recommended or in the release state (we explain the package states further down) for Unity 2022 LTS and contains a dependency on Input System 1.8.1, which is in the same state. However both packages are recommended for Unity 6 Preview.
If you do not plan to update your project to Unity 6, you might not want to update to XRI 3.0. Additionally, the transition to XRI 3.0 is not straightforward, and other XR frameworks might not be ready. As of writing, updates to MRTK and VR Builder are still in progress.
Unity 6 is currently in Preview and is expected to be fully released around Unity Unite in September 2024. Note that Unity has changed its naming conventions with Unity 6. Refer to this forum post from Unity for a better understanding of the terms Unity 6 Beta, Unity 6 Preview, and Unity 6.
Additionally, while the Built-In Render Pipeline is still supported with Unity 6, the Scriptable Render Pipeline will be the default for new projects. For us at Mindport it means that we are considering making the Scriptable Render Pipeline the default for VR Builder as well. Have a look at the GDC Presentation from Unity to get more insights on this and more on the Unity 6 roadmap.
The Package manager shows two states in case of XRI 2.5.4. In the image below it is Released (green label [R]) and Recommended.
In the case of the Release State, Unity’s release management grants a package the “Released” status after thorough testing to ensure compatibility with a specific version of the Editor and all other related packages. Packages in this state appear in the Unity Editor with the green label [R].
The Recommended State is less documented and is bound to the Unity Version you are using. Here is what an official Unity employee wrote on the Unity Forum about this:
“When an editor enters the "f" phase of a release line, focus is put on stability, including feature stability. Doubly so for the LTS stage of an editor's lifecycle. For this reason, newer versions of a package that introduce new features or modify existing features are not proposed as upgrades. Behind the scenes, this is implemented with a hard-coded list in each Editor release with all packages offered by Unity and the version that is pinned for that Editor.”
Note: As I have not seen anything about this convention in the official docs, it might not be fully accurate and subject to changes.
We have been using the following versions when migrating our projects. The steps should be the same if you use similar versions.
Note: I recommend being at the latest at the XRI 2.x version available before updating. For the XRI 3.0.0 pre-release, it was suggested updating your project to the latest 2.x version before moving to version 3.x.
Remove all old XRI Samples before the upgrade. Upgrading from an older version of the Starter Assets to a newer version has known issues. Additionally, the automatic namespace updater will not run on the samples, saving you time during the upgrade process.
In XRI 3.0, many classes, structs, enums, and interfaces have been moved into namespaces that better reflect their use. The automatic namespace updater will help with these changes, but you might need to clean up afterwards by defining usings for the new namespaces.
Unity’s policy is to deprecate code in two steps. The first is to deprecate it with a warning, then to obsolete it with an error in the next major version and only in the following major version will it be removed. If you had any obsolete warnings in XRI 2.x it is now the time to fix them as they are now showing up with an obsolete error like this.
If you are working on a long term project it also makes sense to think of fixing new deprecated warnings now. While you will not get any issues for a long time, fixing the warnings might give you performance improvements or direct you to better tooling like the usage of Near-Far Interactor.
In some cases the XRI Default Input Actions.inputactions in Starter Assets, as well as our custom .inputactions had a JSON parsing issue.
This warning is even shown when the InputActionReference.cs did exist. Reimporting does not help in this case. What will fix this issue is to activate "Generate C# class" and the error should disappear. Afterwards you can deactivate the setting again and delete the generated C# class.
I recommend setting up a new Rig, using the XR Origin (XR Rig) in the Starter Assets as the basis and migrating your customizations over. In our case there were many obsolete warnings in our old rig and replacing them piece by piece felt a lot more tedious and more prone to errors.
If you want to update rig instead here are some tips:
If you are using the Affordance system in your current project, there is no need for concern. As mentioned before, deprecated warnings will change to obsolete errors no earlier than XRI 4.0, and this will take a long time. As mentioned by Eric Provencher, one of the key developers of XRI, "Minor versions of Unity Packages like XRI cannot have functionality deprecated or removed, and major versions need to be tied to major editor releases." (Source).
However, if you are planning your next XR project, it is worth looking at the new feedback system. The new feedback system is in progress on the roadmap and was discussed on the forums in December, even before the release of XRI 3.0. The new feedback system will handle visuals, audio, haptics, and more in upcoming releases of XRI. My personal guess is that it will also be better integrated with visionOS.
If you are extending XRI classes and are using custom Editors as we do within VR Builder, you might get Null Pointer exceptions in your custom Editors.
For example in our implementation of the XRRayInteractor we had code like onHoverEntered = serializedObject.FindProperty("m_OnHoverEntered").
As the SerializedProperty m_OnHoverEntered was renamed we got a Null Pointer exception when trying to access onHoverEntered.
The good thing is that there is an easy solution. You can use base.DrawProperties() instead of OnInspectorGUI(). See the Extending the XR Interaction Toolkit documentation for an example.
Migrating to XRI 3.0 and Unity 6 offers significant improvements and new features but requires careful planning and execution. Ensure you follow best practices and keep your dependencies up to date. Stay informed on updates and community discussions to make the most of these new tools.
For more updates on VR Builder, XRI 3.0 and Unity 6 follow us on Linkedin, join our Discord Community or subscribe to the VR Builder Github repo.