Updated on
March 28, 2023
VR Builder 2.0 brings two fundamental changes to VR Builder projects. First, we removed all external downloads from the importing process - now everything is included in the package you download from the Unity Asset Store. All code will be stored in the Assets folder. Second, the default XR Interaction Component is now based on the stable release of the XR Interaction Toolkit, version 2.0.
Due to these changes in the VR Builder architecture, you shouldn’t simply upgrade the package from the Package Manager. However, VR Builder 2.0 is still fundamentally compatible with existing VR Builder processes, so it is possible to upgrade to the new version with a few manual operations.
Updating your VR Builder projects is not a difficult process, but in case you get stuck you can always find help in our community.
To correctly update to VR Builder 2.0, you will need to:
These steps and fixes are detailed below.
You probably hear it all the time, but a reminder never hurts. Before making any potentially breaking changes, you should back up your project! Or even better, use a source control system like Git.
Then, you will need to remove VR Builder’s external packages, as they are now obsolete and will result in duplicate code. Open the Package Manager and select In Project from the drop-down on the top left.
You will see one or two packages from MindPort GmbH in addition to anything else you may have installed: VR Builder itself, and the XR Interaction Component unless you were using a custom replacement. Remove them both, starting from the XR Interaction Component if it is present. The project should still compile, even if other VR Builder add-ons are installed. If the project doesn’t compile anymore, possibly because of your custom VR Builder extensions, ensure it does by temporarily commenting out or fixing the problematic parts. This will ensure VR Builder is able to perform setup correctly and import the required dependencies.
You can also remove the MindPort package registry from the Project Settings at this point, as it won’t be used by VR Builder 2.0.
Because everything is now included in the Unity package itself, the downloader becomes obsolete. You can now delete it so it won’t prompt you to download the registry packages anymore. Go to Assets/MindPort/VR Builder/Add-ons and delete the Downloader folder.
Settings files will need to be recreated by VR Builder 2.0. The old ones will not work and prevent importing, so they should be deleted. Navigate to Assets/MindPort/VR Builder/Resources and delete all settings asset files present, like BuilderProjectSettings, LanguageSettings, LifeCycleLoggingConfig, SnapZoneSettings and TextToSpeechConfiguration.
Unfortunately this means you will lose any custom VR Builder settings in your project, so make sure to restore those after importing the new version.
Demo processes might have received some small updates with VR Builder 2.0. To ensure the more recent file is copied to the StreamingAssets folder, navigate to Assets/StreamingAssets/Processes and delete all “Demo” folders.
You will need to re-open demo scenes from the VR Builder menu in order to copy the new files the first time you access them after updating.
Now you can finally import VR Builder 2.0. Ensure your project still compiles, then open the Package Manager and import the latest version of VR Builder.
This will cause the XR Interaction Toolkit to be updated to version 2.0.1.
In doing so, you will be asked to automatically update the XR Interaction Layer Mask for compatibility with the new version.
What you choose here depends on your existing data. Normally, when importing VR Builder in a new project the I Made a Backup, Go Ahead! option is the one to choose. In case you used many custom layers and/or changed the default interaction layers, you might want to click No Thanks and fix things manually. You can still run this update manually later. Refer to the section about interaction layers for more information.
After importing VR Builder 2.0, you should update any VR Builder add-ons in the project to a compatible version. You can do this easily by opening the Package Manager and updating the relevant packages.
This step applies if you can’t teleport or you can’t interact with specific objects in an existing scene after updating. XRIT 2.0 doesn’t use normal layers anymore as interaction layers, but a separate set of interaction-specific layers.
The aforementioned automatic upgrade attempts to create interaction layers for the layers you were using for XR interaction, and might actually fix things on its own.
In case it doesn’t, review your interactor and interactables and ensure proper layers are selected. Note that raycasts for e.g. teleporting still use normal layers as well.
Snap zones work a little differently in VR Builder 2.0. While before they put an object in place and then disabled themselves, now the object stays snapped until it’s unsnapped, either by the user grabbing it or by an explicit behavior.
This means that if your existing process interacts with snapped objects, for example moving them through an animation, it won’t work as intended anymore. In this example, the object will not move as it will stay snapped in position.
To fix this issue, you will need to manually unsnap objects before doing anything else with them. You can do so by inserting a Unsnap Behavior where needed in the process. This behavior will immediately unsnap the specified object or the specified snap zone. If both an object and a snap zone are specified, the unsnap will occur only if that specific object is snapped to that specific snap zone.
If you get a series of error messages similar to the following when you import VR Builder 2.0, chances are you didn’t delete the settings files in the Assets/MindPort/VR Builder/Resources folder. Delete them and restart the Unity Editor, the wizard will open automatically.
Congratulations! Now your project is updated to the latest VR Builder version, and you will be able to update to future versions easily through the Package Manager.
You can see our plans for the future of VR Builder in our roadmap.
If you like what we are doing and enjoy VR Builder, please leave a positive review on the Unity Asset Store. This would help us a lot to further grow our community and ecosystem and maintain the free and open source VR Builder project in the future.