Upgrading your project to Unity 2022 without issues.

Or check out my assets!

Today the VRChat SDK for Unity 2022, FINALLY dropped. I’m going to write a quick little how-to on how to get set up without causing any errors, so long as you can verify all of your sources are compatible.

This guide will have a strong focus on creating a boilerplate project that can be used as a strong foundation for any 2022 project. Specifically focused on avatars here as that is what we do.

| Thanks to Auros for fact-checking this page.

⚠️ WARNING!

Before following this guide, be sure to check all tools you rely on are up-to-date. At this point (Late December), most tools I use personally can be verified as compatible. VRCFury, and Modular Avatar being two of the biggest.

Prerequisites

VRC Creator Companion (VCC) >= v2.21
Unity 2022.3.(>=6f1)

Warnings!

DO NOT upgrade your project using ONLY the creator companion’s “upgrade” button. Chances of this automation going wrong are unfortunately too high, and it most likely will not account for every edge-case. This should only be used if you are using a VPM-based project with no external dependencies. Please do not trust the creator companion to do your work for you!

DO NOT expect things to work perfectly if you are not using the exact recommended Unity Version by VRChat. If there are version-specific bugs, you should not report them unless you are using the exact recommended version.

Generally, I would use 2022.3.15f1 for this project, as it’s the latest version with Shader Graph fixes and some other bugfixes, but I want to participate in the Open-Beta responsibly and part of that is submitting bug reports.

Initializing our Project

In order to have a strong starting point for your project, I highly recommend creating a new project and transferring items over. The process is generally the same if you were to attempt to upgrade-in-place, but this way we can check for any issues along the way, and fix them before we get too far ahead and lost.

Unity 2022 imports assets much faster than 2019, so don’t worry about the extra time this will take comparatively.

Creating a project

While the VCC will give you a starting point, I recommend creating a vanilla project with Unity Hub first, to avoid any issues. This way we can validate our starting point before VCC interacts with anything at all.

Open Unity Hub
Verify you have Unity 2022.3.6f1 installed. If not you can get it from here
Be sure to install “Android Build Support” if you are targeting quest. Also install the Visual Studio Community 2022 editor if you do not have your own preferred IDE.

After this is complete we can create our project by heading to the “Projects” tab and clicking the “Create new project” button.

Use the template “3D (Core)”
Name your project something without spaces in it.

a. Avoid using any special characters, including underscores as well for cleanliness.
Save your project in a User-Accessible location, such as your Documents or an external drive. Now is the time to reorganise things, so choose wisely!
Create your project, and let it initialize…

A quick note on naming.

Naming conventions are important and can greatly improve the organization of a project. I recommend using CSharp naming conventions, such as using UpperCamelCase (Also known as Pascal Case) for your project name (i.e. MyProjectFile). More Info.

Setting things up for VCC

Before we can add VCC, we want to make sure a few things are set up correctly. Some of this the SDK will automatically handle, but it’s recommended to check everything first so nothing will break.

Project Settings (`Edit > Project Settings`)

- `Editor`

Ensure Reload Scene is ENABLED! I have no idea when this trend started with creators in the VRChat community, but disabling Reload Scene WILL cause issues with various tools. To name a few:

VRCFury (Will never launch / run in play mode)
Modular Avatar (The same as the former, though I haven’t tested it personally.)

Reload Domain disabled works fine with most tools. You can disable this here to speed up playmode launch pretty dramatically, as most well-made tools should handle things accordingly. If you run into errors, such as things scaling out of control, or animators baking twice, turn this setting back on.

- Editor Preferences `(Edit > Preferences)`

These should mostly be the same as your last project, but we can run over a couple to double-check.

General

Disable Analytics: ✅
Script Changes while Playing: Stop Playing and Recompile
- This one is optional, and may not be recommended by all, but I do this to avoid errors if I accidentally forget to stop the editor while editing C# scripts.
Editor Theme: (Subjective)
Editor Font: If you have a language requirement, you can change the font here.
Perform Bump Map Check: ✅ (If you want Unity to try to auto-detect normal maps).

Colors

A lot of people ask my why my editor turns obnoxious red when I am in play mode, this is just so I know I’m in play mode when editing things like physbones. You can edit this here.

General / Playmode Tint: <Some colour>

External Tools

This is where you can set your text editor. I recommend using Jetbrains Rider if you have it, otherwise Visual Studio Code.

External Script Editor: <Your Script Editor>

If you are using Rider, be sure to enable “Pass Console to Rider” in the Rider tab!

Search

Asset Store (store:): ❎

UI Scaling

If using a screen with a high resolution, you might want to change this setting.

Finished! Close and restart the editor now!

Setting up VCC

Wait for your project to open. VCC Connects to projects over a network socket so you may interact with it while it’s open.

After it is open, open the VCC and add the project by clicking the V next to Create New Project in the Projects tab.

Choose the project we just created’s root folder. Like this:

Click Manage Project.

I noticed my VCC complaining about this version of the editor not being installed. To fix this I had to manually add the editor using the “Add” button when clicking the orange “Open Project” button. Adding the editor path at C:\Program Files\Unity\Hub\Editor\2022.3.6f1\Editor\Unity.exe should fix this.

Next we need to add the VRChat SDK - Avatars package. Selecting this will automatically install the dependency packages like Base, and VPM

After this click back into the editor and wait for the packages to install. You’ll also begin to notice here how much nicer 2022 is! It’s actually using all of your CPU to import things! That’s great!!

2022 will run some background tasks, be sure these are finished before continuing by looking for the checkbox in the very bottom right.

Now you can install any package dependencies you may have. Try to do these one by one for now to make sure there are no issues in the editor. Check the editor with each package you have and wait for the recompile to finish. Everything should work smoothly!

IMPORTANT NOTE: The VCC will sometimes ignore packages defining above versions are compatible, and you’ll get a screen like this. BE SURE TO UPGRADE THE DOWNGRADED PACKAGES AGAIN! otherwise things will break. This issue is a bug with semantic versioning and has been reported.

Ignore this if you know the package works!

Notice the “Package requirement” of 3.5.x not detecting 3.5.0-beta.1

Update: This seems to have been fixed by the team publishing version numbers without a pre-release suffix. I.e. 3.5.0

Warnings like this can be ignored!

Audiolink will throw this error, choose “I made a backup go ahead!”

Finally, importing assets!

So long as you do not have any outdated editor scripts, you should be able to copy anything in your previous project’s assets folder, over to this 2022 project without issue.

I was able personally, to copy over all of my assets, along with avatar scripts, and not get hung up on anything. If something breaks, there’s a good chance you’ve imported something like a script to your project that shouldn’t have been imported.

You also may notice again how fast things import!!!

With this however, you should be good to go with a solid foundation for your 2022 experiments! Have fun!

Wrap-up

If this helped you, consider tossing me a Kofi