Update to VR Builder 4

Updating your VR Builder projects is not a complicated process, but in case you get stuck, you can always find help in our community.

This guide explains how to update from VR Builder 3 to VR Builder 4. Most of it is also valid for updating to a minor release. We don’t recommend updating to a new major release during production unless you need some of the new features, but if that’s the case this document has you covered.

Summary

To correctly update to VR Builder 4, you will need to:

• Remove old Asset Folders
• Import VR Builder
• Update your processes

Detailed steps and fixes are provided below.

Step 1: Make a backup

You probably hear it all the time, but a reminder never hurts. Before making any potentially breaking changes, back up your project! Or even better, use a source control system like Git.

Step 2: Remove old Asset Folders

VR Builder 4 switched to a hybrid package, which means it’s not stored anymore in the Assets folder, but in the Packages folder instead.

Due to the update mechanism of the Unity Asset Store, old files will not be removed when updating an asset. Therefore, you should delete the old files before you update.

The folder you want to delete is Assets\MindPort\VR Builder\Core if you are updating from VR Builder 3 or earlier, or Packages\co.mindport.vrbuilder.core if you are updating from an earlier VR Builder 4 version.

Also, delete any MindPort\VR Builder\Add-ons\ that you want to update, or the corresponding package in the Packages folder.

Note that you shouldn’t delete the Assets\MindPort\VR Builder\Resources as it contains your settings and your snap zone preview objects, so avoid deleting the MindPort folder altogether!

Step 3: Import VR Builder

Now you can import VR Builder. Open the Package Manager and import the latest version of VR Builder.

Note: This update guide was created for updating from VR Builder 3 to VR Builder 4. The output might change slightly when updating to or from different versions.

The following section explains how to troubleshoot some issues that might arise after importing the new version.

It is possible that some compile errors will be displayed after importing the new package. Just restart Unity.

When restarting, if you are asked to go into Safe Mode, ignore it.

Now, Unity will fetch new dependencies that were added since your last version update.

Unity might get stuck during this process. If “busy for …s” remains for too long, you can restart Unity.

After the restart, Unity will continue to fetch new dependencies.

When XRI is updated you will be notified.

After all dependencies have been fetched, the Project Wizard will show up. Click through it, as you might find new features that you want to activate.

Step 4: Update Add-ons

After importing VR Builder, you should update any VR Builder add-ons in the project as well. This can be done easily by opening the Package Manager and updating the relevant packages.

Note: If you have not already done so, you should delete the old files before you update. The folders are Assets\MindPort\VR Builder\Add-ons\[addon name] for earlier add-ons, or a corresponding folder in Packages for add-ons released after VR Builder 4.

Step 5: Delete demo processes

Demo processes might have received some minor updates. To ensure the most recent file is copied to the StreamingAssets folder, close Unity then navigate to Assets\StreamingAssets\Processes and delete all “Demo” folders. Then to get the new files open demo scenes from the VR Builder menu.

Step 6: Update your processes

This is only needed when updating from VR Builder 3 or earlier to VR Builder 4 or later.

To make an old process work in VR Builder 4, you will need to perform at least the following:

‍

1. Import scene object tags
2. Upgrade the process
3. Update the rig

Import scene object tags

With VR Builder 4, scene object tags have been replaced by object groups. Functionally they are pretty similar - you can edit groups in the Scene Object Groups section of the Project Settings. However, you will notice that tags have disappeared. You can easily import your tags in the new Scene Object Groups list by clicking Tools > VR Builder > Developer > Update Object Groups.

Note: This is different from recreating new groups with the same names as the old tags, and is required to maintain compatibility with your process scene objects using those tags.

Upgrade the process

VR Builder 4 overhauled the process scene object referencing system. If you open an earlier process in VR Builder 4, all scene object references will be null, as they have been created with the old system. This also includes manually unlocked objects, as they are object references themselves.

We provide a tool that attempts to upgrade older processes to be compatible with VR Builder 4. To use it, it is necessary that the process is loaded in the scene where it’s used - that way, the tool will be able to look for the referenced objects and create a reference compatible with the new system. 

Once the process and the scene are loaded, select Tools > VR Builder > Developer > Update Process in Scene. You’ll be able to review the changes made to the process in the console. Let us stress again you should to back up your process files before running the tool on them.

Note: This upgrade tool only works on official and partner add-ons. If you created your own behaviors/conditions, you will have to update them to be compatible with VR Builder 4.0 before running the tool to upgrade your processes.

Update the rig

To update the rig, start by ensuring you have the latest version. If you're using the default rig, the process is straightforward. Simply delete the current rig from your scene. Then, locate the prefab with the same name in the VR Builder package and drag it into your scene. This ensures you have the most up-to-date default rig. 

If you are using a custom rig, test its functionality and compare it to the default rig to see if some components need to be updated.

Conclusion

Congratulations! Now your project is updated to the latest VR Builder version.

• Feel free to have a look at the release notes. You can find them on the Asset Store or on GitHub.
• 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 immensely to further grow our community and ecosystem and maintain the free and open source VR Builder project in the future.

‍