📘

If you are starting a new project, you can just follow the instructions in Setting up the SDK. This page is for upgrading existing projects from an older version of Unity.

For more information about VRChat's upgrade to Unity 2019, read our blog post!

Install Unity Hub

Unity Hub is a separate application that allows you to seamlessly install and work with multiple Unity versions at one time. If you're not using it already, you really should.

1. Grab Unity Hub - Download Unity Hub from the Download Unity page. Click the green "Download Unity Hub" button to download only Unity Hub.
2. Install Unity Hub - Run the downloaded installer. Once installed you are ready to get Unity 2019.4.x Installed!

You can learn more about Unity Hub in the official Unity documentation.

Install Unity 2019.4.x LTS

Now that you have Unity Hub installed, you are ready to install the correct version of Unity 2019!

To install Unity, head over to the Current Unity Version page. There, you'll learn what the current version of Unity is. Follow the instructions to install via Unity Hub.

If you're having trouble finding the right version, refer to the Direct Downloads section of the Current Unity Version doc for instructions. Keep in mind you'll have to manually add the install to Unity Hub.

Prepare Your Project for Migration

Before you jump into migrating a project with your fresh install of Unity 2019, you need to prepare your project using the previous version of Unity.

Step 1: Make a copy of your project.

When migrating an old project from Unity 2018 the first step is to duplicate the whole project folder and give it a new name. Adding "-2019" would work well.

Do not export your old project as a UnityPackage, that can take forever and have other errors.

Keeping a backup of your project before migration is important! Importing a project into a newer version of Unity will make it very difficult/impossible to port it back to older versions. We cannot help you with reverting your projects.

After making the "-2019" version of your project folder, add it to Unity Hub.

❗️

BACK UP YOUR PROJECT.

Do not skip creating a copy of your project. Do not attempt to upgrade a project without backing it up first.

Although the upgrade process is fairly painless, unrecoverable errors are possible. We cannot help you recover projects lost in this manner.

Step 2: If your project uses SDK2 or SDK3-Avatars, import the 2019 SDK before upgrading.

🚧

This step only applies to SDK3-Avatars and SDK2. If you're upgrading a SDK3-Worlds project (as in, Udon-powered worlds), skip to the below Migration Process section. You'll import the new SDK after the upgrade process is complete.

If you're upgrading a project using SDK3-Avatars or SDK2, import the new 2019 SDK while you're still running 2018. You may experience some errors here after import, but you can ignore them. Close Unity after you're done.

Our SDKs are available at the locations listed on the Choosing your SDK page. Import the .unitypackage into your project as usual, overwriting any older files.

Step 2.5: Preparing to Upgrade

Create an Empty Scene

Follow these steps if you are using UdonSharp in your project. Skipping this step will result in all U# behaviors in the scene to lose references and become corrupted.

To be extra careful, we are going to create a new empty scene and save our project with that scene open. This will cause the new, blank scene to load first when Unity is opened after the upgrade instead of a scene with a bunch of work in it.

From the File menu, select New Scene. Then, save your scene/project. Do this right before you close Unity to upgrade to 2019.

This is done to prevent Unity from attempting to open the scene before all assemblies are compiled, which causes all scripted behaviors in the scene to lose references and become corrupted.

Cloth

Follow these steps for every Cloth mesh in your project. Skipping this step will result in all Cloth objects in the scene to lose data and become corrupted.

A community-created tool by Hai is available here. It covers all of the steps below automatically. If you choose to use it, read their instructions carefully!

If you have Unity Cloth on anything in your project (avatar or worlds), it will be lost when you upgrade your project. However, the Cloth can be recovered by taking some steps before upgrading.

This must be done for every Skinned Mesh Renderer in the project that has a Cloth component.

1. For every Skinned Mesh Renderer with a Cloth component, find the Mesh slot.
2. Open the Project tab.
3. Click the white area of the mesh box, so it highlights the mesh in your Project assets. It will probably be a mesh inside a FBX model.
4. Select the mesh that got highlighted, and press Ctrl-D to duplicate that mesh asset.
5. Copy your Cloth component by clicking the gear in the top right of the component and selecting Copy.
6. Click the gear again and click Remove Component.
7. Drag the duplicated mesh into the mesh slot of your Skinned Mesh Renderer.
8. Click on the gear in the top right of the Skinned Mesh Renderer or Transform component, and click Paste As New. This will re-add the Cloth component and put all the component values back in.

If you do this, cloth will not be lost on upgrade.

This is due to a change to the FBX importer in Unity 2019, documented here.

Step 3: Upgrade your project to Unity 2019.

Alright! We're all ready now. Now that you have installed Unity Hub, the correct version of Unity 2019, upgraded to the 2019 SDK, and otherwise prepared your project, you are ready to begin migrating!

The migration process for all three SDKs (SDK2, SDK3-Avatars, and SDK3-Worlds) is very similar. Only SDK3-Worlds is different. Follow the steps below carefully.

Hey. You. Yeah, you, the person who thought they'd speed through this and skip past preparing your project before doing the upgrade. Go back and follow those steps, otherwise all you'll be doing below is messing up your project irrevocably and we cannot help you recover it. Sorry to be pushy, but we don't want you to lose all your hard work. Take your time and follow the steps.

❗️

Don't Change SDK Type During Migration

When migrating a project, use the same SDK type that you were using in the previous Unity version.

1. Add your project to Unity Hub. In Unity Hub, click the Add button on the main screen, then find the directory of the project copy you prepared.

2. Set your project to the new Unity version in Unity Hub. Ensure that you select the current version as the Unity Version for your project in Unity Hub.

3. Open your project. Click your project in Unity Hub to open it.

4a. A prompt will ask if you want to upgrade your Project to a newer version of Unity. Select "Confirm".

4b. A prompt will ask if you want to upgrade the project to use Asset Database Version 2 - **select "Yes".

4c. You may get a prompt warning that you're Opening a Project in Non-Matching Editor Installation. Choose 'Continue'.

4d. You may get a prompt warning you that an API Update is Required. Choose "I made a backup, go ahead".

4e. The import may take a while! Unity will reimport assets and update your project for Unity 2019. Be patient! The process may take 30min+ for large projects, and even longer if you're using a mechanical hard drive. Once your project is open, you are ready to continue.

As an aside, this is a pretty good reason to keep your projects separated reasonably instead of having one or two mega-projects for your VRChat work.

5. Open your scene. Once Unity is back up, you should be able to open your scenes and access your content.

6. If you're upgrading a world project, import the 2019 SDK3-Worlds package now. You skipped importing the new SDK back in the prep stage. Go ahead and install the new 2019 SDK over the old 2018 SDK now.

🚧

Quest Projects

If you're upgrading a Quest project, you'll probably run into some issues. Check out the "Clearing the Library Folder" section below, which should help you out.

Troubleshooting

Clearing the Library Folder

We've seen some bugs with SDK2 where the Library folder won't rebuild properly. This is easy to solve, as the Library folder is just temporary files.

To delete the Library folder, simply go to your Project folder and delete the folder named Library. It won't be under Assets, it'll be under the root of your project folder ("next to" Assets).

Also, deleting your Library folder before migrating to 2019 is a bad idea, so don't do that. Don't delete it unless you've already gotten to step 5 above and you're still having problems.

The SDK2 library deletion process might be helpful for SDK3 as well, but you shouldn't do it unless you need to. SDK3 handles the migration a lot better, and shouldn't need this step.

I'm seeing tons of errors in the console!

Don't panic! The first error that you see is usually the important one. Click Clear a few times and see what the first one (the top one) is. It probably isn't pointing at a VRChat SDK component-- usually, these errors result from third-party components and scripts.

Remove those components and scripts and/or update them from their original source. Keep in mind it might take a bit for people to update their tools.

If your 2018 Unity Project is using an older SDK, it might not migrate over cleanly, which is another cause of errors. Download and update to the latest public 2018 SDK with the project open in Unity 2018, then follow the migration steps to see if that fixes it.

Do I need to migrate and reupload my content?

That depends. In this particular upgrade, there actually aren't many things that'll necessitate a reupload! Below is a list of things you should consider when assessing if you should migrate and reupload your world or avatars:

Shaders

A lot of work has been done to make VRChat's update to Unity 2019 easy for everyone! Unity 2018 content should appear normally as it did before the update. With that in mind, there is an incredible amount of variety and depth to shaders, and we can't guarantee that everything will work exactly as it did before. Our advice for content is to always migrate and reupload if you are having shader issues.

Terrain

Unity 2019 has once again made some changes to how Terrain works, in particular with shaders and vertex shading. If you use Unity Terrain with the built-in shaders, you should be fine. If you're doing anything special with Unity Terrain, their shaders, or using vertex-based shading, you will probably need to reupload.

Other Issues

If you test your content in 2019 and see issues, please try re-uploading your content before reporting it as a bug. There are many things that we might not be able to fix from older content that a reupload will solve.

Empty Control Panel or Missing VRCUrlInputField

If your control panel is blank like in the above image, try this:

• In the Project window, navigate to Assets/VRCSDK/Plugins
• Select all DLLs, right click > Reimport

This should also fix the issue if your Video Players no longer have a VRCUrlInputField.

If I upload, does it overwrite my current content?

Nope! We keep assets per-version. You can upload to the same IDs and your 2018 content will be untouched. If you're on a 2019 version of VRChat, you'll get 2019 content if its available. Nothing about that's changed.