Skip to main content

Updating the SDK

If you need to update your SDK, it is important that you follow these steps to ensure the update proceeds properly and you don't have any old/conflicting files.

Version Control​

If you know how to use it, you may find it beneficial to use version control software like Git to manage your project. You don't need to upload your repository to Github or similar service to gain the benefits of version control. Create a commit before you upgrade SDKs just to be sure.

VRChat Creator Companion​

Keeping your SDK up to date is extremely easy with the VCC. See the VRChat Creator Companion docs to learn how to use it!

Migrating to the VCC​

If you want to learn how to migrate your project to use the VCC, check out the guide here.

Manual Updates​

If you're using the VCC, you don't need to worry about manual updates.

Legacy SDK3​

caution

These instructions only apply to users of our Legacy SDK (Assets\VRCSDK). If your SDK is in your Packages folder (Packages\com.vrchat.base), do not follow the instructions below.

For SDK3, you should be able to update by simply importing the new SDK over the old one, also known as an in-place upgrade. This is especially important for SDK3-Avatars, as you may lose State Behaviors on your animators if you incorrectly update!

If you want to be super careful, always back up your projects before updating the SDK.

SDK3 - World​

  1. Close Unity.
  2. Back up your Unity project! You don't have to backup your Library folder, these files are auto-generated by Unity.
Pre-2020.3.2 SDK3 Upgrade

This is an uncommon step and you probably don't need to do it.

If you are upgrading from an SDK older than 2020.3.2, go into your project's Assets folder and delete the VRCSDK and Udon folders as well as the VRCSDK.meta and Udon.meta files.

  1. Open your Unity project.
  2. Import the new SDK3 - World over the old one.

SDK3 - Avatars​

Do not perform "Deletion Reinstalls" For SDK3 - Avatars!

If you delete the SDK folders with Unity closed and open Unity without the SDK installed, you will lose State Behaviors. They are fragile and do not persist through full deletion upgrades. Make sure you back up your projects often, and save/document your state behavior setups.

If you must perform a full deletion reinstall of your SDK3 - Avatars package, back up your project first. You will have to set up your State Behaviors again, so ensure you have documented them well.

  1. Close Unity.
  2. Back up your Unity project! You don't have to backup your Library folder, these files are auto-generated by Unity.
  3. Open your Unity project.
  4. Import the new SDK3 - Avatars over the old one. If you get errors after import is complete, try restarting Unity afterward.
SDK3 Expected Errors on Avatar Dynamics Upgrade

It is expected to have a handful of errors when you first upgrade SDK3 for Avatars to the Avatar Dynamics SDK. This is due to the SDK installing the Burst and Mathematics packages during the install process, and Unity getting a bit ahead of itself in importing them early.

If you clear the errors or restart Unity, they should go away.

SDK3 - Avatars - Separate Project Process​

If you run into issues with upgrading via the above process, try this instead:

  1. Close Unity.
  2. Make a new, blank project.
  3. Import the new SDK3 - Avatars package into that project.
  4. Close that Unity project.
  5. Using Explorer (Do not open Unity yet!), delete the VRCSDK3 folders from the project you're upgrading. Until this guide says otherwise, do not open Unity.
  6. From your new blank project that you imported the SDK into, copy the VRCSDK3 folders into your project that you're upgrading.
  7. Once the copy completes, open Unity and open your upgraded project. You may delete the blank project.

Advanced Update Process​

If you're reinstalling the SDK in a project that contains a world using complex trigger setups, here's a safer way to update your SDK.

  1. Close Unity
  2. Back up project to another folder (do not back up the Library folder, these files are auto-generated by Unity)
  3. Delete SDK and Plugins folder, as well as the the associated .META files
  4. Create a new dummy Unity Project
  5. Install the latest SDK on the dummy project
  6. Copy the newly added SDK/Plugin and associated .META files from the dummy project into your original project
  7. Done. Now you can open your upgraded project, and there will be no crash no matter how complex your trigger work!

Updating Unity​

If you are updating from a previous version of Unity, we have a guide for updating to our latest version we support!