🚧

Deprecated Guide

This guide is deprecated and no longer used! You're probably in the wrong place, but we're leaving this here in case there's some info you need in here.

You might be looking for the Migrating from 2018 LTS to 2019 LTS guide.

If you are starting a new project you can just follow the instructions below to install Unity Hub and Unity 2018.4.x and then consult the doc Choosing your SDK to get the SDK.

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

Install Unity Hub (Really!)

Unity Hub is a separate application that allows you to seamlessly install and work with multiple Unity versions at one time. We strongly recommend using it!

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 2018.4.x Installed!

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

Install Unity 2018.4.x LTS

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

1. Install Unity - Head over to the doc Current Unity Version to learn what the current version of Unity is, and 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. But 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 2018, you need to prepare your project using the previous version of Unity.

1. Make a copy of your project! - When migrating an old project from Unity 2017 the first step is to duplicate the whole project folder and give it a new name. Adding "-2018" would work well. Do not export your old project as a UnityPackage, that can take forever/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.

2. Clean up assets/scripts! - Some assets/scripts don't work in Unity 2018. Open the new copy of your project inside of Unity 2017 and take care of the following:

Remove Post Processing Stack v1 - If your project uses Post Processing Stack v1, you must remove it before migrating. PPv1 is no longer supported by Unity (or VRChat) in Unity 2018 and will cause issues with importing the new SDK due to script errors. Remove PPv1 by deleting its folder from your assets.

Once you have your project migrated in Unity 2018 you should switch to Post Processing v2. It can be installed via the new [Package Manager](https://docs.unity3d.com/Packages/[email protected]/manual/Installation.html) in Unity 2018.

In addition, you must move your global Post Process Volume component to a game object other than your Refrence Camera. You should keep the Post Process Layer component on your Reference Camera.

The Reference Camera is specified in the Scene Descriptor component. The camera you specify is disabled at runtime and components on disabled GameObjects do not run. The Reference Camera is only used to copy various view settings to the player's view camera.

The VRChat SDK will warn you if your Post Processing Volume is on the Reference Camera.

Remove Shader Forge - Shader Forge has been discontinued and may have script errors in Unity 2018. These errors will cause issues importing the new SDK. Remove Shader Forge by deleting its folder from your assets.

Remove Dynamic Fog & Mist - This asset is no longer supported by VRChat in Unity 2018. Remove it.

Update Dynamic Bone - You'll want to update your version of Dynamic Bone to the latest version on the Asset Store. Doing so is pretty easy-- just find Dynamic Bone on the Asset Store window inside of Unity, click Update, and then import the update. Done!

Make sure other assets/scripts work in Unity 2018 - You may have other older assets or scripts that are not compatible with Unity 2018. Either update these or remove them to prepare for the migration to Unity 2018. If upon opening your project in 2018 you find your scene is filled with missing references, you should go to your Console to see what assets/scripts are causing errors and remove them from your project.

The Migration Process

Now that you have installed Unity Hub, the correct version of Unity 2018 and prepared your project, you are ready to begin migrating!

1. Grab the latest VRChat SDK - Consult the doc Choosing your SDK for the latest download links to get the latest version of VRCSDK2.

❗️

Don't use VRCSDK3 for Migration

We do not support the migration of VRCSDK2 worlds to VRCSDK3.

If you're migrating a project, you should use VRCSDK2.

Don't attempt to use VRCSDK3 for migration-- it is meant for new projects.

2. 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.

3. Set your project to the correct Unity version in Unity Hub - Ensure that you select the current version as the Unity Version for your project in Unity Hub.

4. Open your project - Click your project in Unity Hub to open it. This step may take a while as Unity reimports assets and updates your project for Unity 2018. Be patient! The process may take 30min+ for large projects! Once your project is open, you are ready to continue.

🚧

Did you prepare your project?

As noted above, if you have editor scripts or add-ons that are not compiling correctly, they can get in the way of Unity 2018 importing your assets during the upgrade.

5. Create an empty scene - To be extra careful, we are going to create a new empty scene and save our project with it open. From the File menu, select New Scene. Then save your scene/project.

6. Close Unity - We are going to remove the old VRChat SDK next, and this should be done while Unity is closed.

7. Remove the old VRChat SDK - There are a few things to remove:
   a. Navigate to your project's Assets outside of Unity.
   b. Delete the folder VRCSDK and the file VRCSDK.meta located in Assets.
   c. Navigate to the Plugins folder inside of Assets.
   d. Delete the VRCSDK folder and VRCSDK.meta file located here too.

8. Reopen your project, and stay in the empty scene - Stay in the empty scene for the next two steps.

9. Import VRCSDK2 - Import the new SDK you downloaded earlier as normal. From the Assets menu, select Import Package and then Import Custom Package.

10. Update the Unity Scripting Runtime version - Press Play at the top of Unity to enter Play Mode. Press it again to exit Play Mode. This will cause Unity to ask you to Restart the editor to update your project's Scripting Runtime version. Click Restart and Unity will reload your project. This will take a moment while Unity recompiles scripts. Unity may also ask you to re-login to your Unity account at this point.

🚧

If you can't enter Play Mode because of compile errors, you may need to go to Project Settings > Player > Other Settings and set the Scripting Runtime version to ".NET 4.x Equivalent".

11. Open your scene - Once Unity is back up, open the scene for your world/avatar. You should be good to go. Get back to creating!

Issues Migrating

If you are having issues installing the SDK (Steps 6-9 above) and you are sure you removed all broken assets/scripts from your project, we recommend trying the following process that includes a few more steps:

1. Close Unity - The following steps should be done while Unity is closed.

2. Remove the old VRChat SDK - There are a few things to remove:
   a. Navigate to your project's Assets folder outside of Unity.
   b. Delete the folder VRCSDK and the file VRCSDK.meta located in Assets.
   c. Navigate to the Plugins folder inside of Assets.
   d. Delete the VRCSDK folder and VRCSDK.meta file located here too.

3. Open "Regedit" - You can do this by typing regedit in your Start menu.

4. Set the path in Regedit - If you're running Windows 10, paste this into the top bar:
   Computer\HKEY_CURRENT_USER\Software\Unity Technologies\Unity Editor 5.x
   If you're not running Windows 10, go to the path manually. Yes, this path is correct even for Unity 2018.

5. Delete keys - Delete all keys starting with VRC in that directory. Highlight them by dragging a box over them, right-click, and click delete. ONLY DELETE the keys starting with VRC. Very important.

6. Close Regedit

7. Reopen your project

8. Import VRCSDK2 - Import the new SDK you downloaded as normal. From the Assets menu, select Import Package and then Import Custom Package.

9. The SDK should now be properly installed.

Do I need to migrate and reupload my content?

That depends. Below is a list of things you should consider when assessing if you should migrate and reupload your world or avatars:

Post Processing

You must remove Post Processing Stack v1 - It is no longer supported by Unity or VRChat. See the prepare your project for migration section above for important details.

Crunch Compression

Unity didn't upgrade Crunch Compression for 2018, so you should be fine if you're using Crunch.

UVs and Wrapping

We've seen rare issues where UVs on materials may have become corrupted or mangled. Re-uploading fixes this. You might also want to ensure your texture is set to the proper wrapping mode (Clamp, Repeat, etc).

HDR Colors

Unity 2018 requires that you do a bit of work to fix HDR color selections. Due to a change in HDR values being considered linear instead of gamma space in Unity 2018, your colors in materials may not be correct.

The VRChat SDK menu contains a tool to swap color space on materials. It is located in the Utilities sub-menu.

Lights Using Light Temperature

Unity 2018 removes the "Use Color Temperature" mode from all lights. This means you will need to convert all light temperatures to RGB. This script provided by the community member ScruffyRules will convert all of the lights in a scene to RGB. This script is not authored by VRChat.

Note: Projects migrated from Unity 2017 may still show the "Use Color Temperature" controls on your lights. These are non-functional and show in an upgraded project due to the quirks of Unity.

Dynamic Fog & Mist

The asset "Dynamic Fog & Mist" is not supported.

Shaders

Unity has fixed a huge amount of shader bugs with the Unity engine that affected us during the 2018 Beta process! Most (if not all) 2017 content should appear with little to no issue.

Our advice for content is to always migrate and reupload if you are having shader issues.

Keywords

Clearing Keywords

When you change or upgrade your shader, ensure that you remove old, unused keywords from your materials. Having excessive keywords in use is very bad for performance and optimization. Not only will it cause issues with your own avatar, but it may prevent others from seeing all shaders properly.

The VRChat SDK contains a tool to remove keywords from materials on your avatar. This tool can also remove keywords you need, so be careful!

Usually, it is best to check the keywords with this tool-- if you've got too many keywords, you probably need to find another shader. Swap to Standard, clear keywords, then swap to your new shader.

Note for Shader Authors

You may want to consider using the keywords reserved by the Standard shader as your own keywords. These are essentially guaranteed to already be reserved, so if you must use keywords, use the ones already defined by Standard and Post Processing v2. Here's a list of recommended keywords to use.

Shader Compatibility

Check the following tables to see if it is a good idea to re-upload your content.

This list is not comprehensive or complete, and we don't plan on maintaining a full list of shaders you'll need to re-upload your content for . However we know many users use these shaders, so we tried to cover the most common ones and list what steps may be necessary to get them working in Unity 2018.

📘

Community-Provided Information

The information below this notification has been provided in whole or in part by our Community and may contain links to software or files that have not been authored by VRChat.

Ready to go for 2018!

These shaders are mostly good to go. If you run into problems, it might be best to try updating these and re-uploading, just in case.

Unsupported

These shaders meet one of the following conditions:

• The shader does not work in Unity 2018.
• The author has explicitly stated support has ended for the shader.
• The shader's project appears to be abandoned and no updates have occurred in a large amount of time (2 LTS releases)

You must replace following shaders with another shader and reupload using the latest Unity version.

* Video was not produced by VRChat, and may present information or opinions that are not held by VRChat as an organization. This video has been provided as-is to provide information to creators.