Who this guide is for?
Anyone who, like me, found themselves on the 2021.x tech stream path while working on a project using ECS and now needs to migrate to the 2020 LTS path to maintain compatibility with/support for ECS ( Notice on DOTS compatibility with Unity 2021.1 ).
Upfront warnings
-
DOWNGRADES ARE NOT SUPPORTED BY UNITY. They make this very clear. This doesn’t mean that you can’t migrate from a higher version to a lower version, it just means that their automatic tools don’t support it and by moving from a higher version to a lower version you may encounter problems and introduce bugs into your project. So be aware of the risks before proceeding.
-
THIS MAY BE PREMATURE. The communication from Unity has been less than transparent as to exactly what is going on. Consider whether your project can wait until further clarity is provided on the future path for ECS support. This guide is intended to help developers who find themselves stuck on a version of Unity that doesn’t support ECS and who feel that they must migrate to maintain support (e.g., your project timeline dictates that you can’t wait to find out what Unity has planned and need to adjust now). This is NOT a recommendation that every project on 2021.x should immediately downgrade to 2020 LTS.
-
MAKE A BACKUP. Something could go wrong, and you do not want to lose your project. Make a backup (version control, flash drive, whatever) so that you have the original, unaltered version of your project in the higher version of Unity in case something goes wrong. This way you can always fall back on that.
Migration Steps
- Create a new Project in the target Unity version (2020.3 LTS)
-
Create a new project in the target version (e.g., 2020.3.3f1).
-
Use the Package Manager to add the packages required by your project (reference the packages listed in the Package Manager or manifest.json file of your original project).
-
NOTE: If you’re using the URP, Shader Graph, and the Hybrid Renderer, there may be some problems with your Shader Graph shaders moving to the current version of URP for 2020 LTS (URP 10.4.0). It appears that URP version 10.3.2 may have better support for this package set. You can edit your manifest.json file manually to use 10.3.2 instead of 10.4.0.
-
Review and transfer the Project Settings and Preferences from your original project to the new one that is being created.
- Export your project files as a Package
-
Open your original project.
-
Open the menu option Assets > Export Package…
-
Select your assets to export and export them.
-
NOTE: When doing this, I received a large number of warning messages that were generated because of dependencies on assets in Unity Packages (e.g., VFX, URP, etc.). In my case these did not result in issues with the export.
-
Close your original project.
- Import the Package into your new project
-
In the new project that you have created, open the menu option Assets > Import Package > Custom Package…
-
Select the assets to import in the dialog.
-
Monitor your console for warnings and errors.
-
NOTE: I would recommend restarting after you’ve reviewed all warnings (and errors, if any) that were generated during the package import.
-
If you have Unit Tests, execute them now and verify the results.
-
Start your project and begin to verify that it works in Unity 2020 LTS.
Potential Problems
My shaders no longer work after migrating
-
Situation: All shaders result in the fallback error shader being rendered.
-
Setup: A project using URP and Hybrid Renderer V2
-
Description: The root cause appears to be that when the URP assets get imported (The Pipeline Asset and the Pipeline Asset Renderer), the Pipeline Asset Renderer asset becomes corrupted.
-
Solution:
-
Manually create a new Pipeline Asset (Create > Rendering > Universal Render Pipeline > [SELECT_YOUR_PIPELINE_ASSET])
-
Replace the old Pipeline Asset Renderer asset in the “Renderer List” property of the existing Pipeline Asset with the newly generated Pipeline Asset Renderer asset.
-
Delete the old/corrupt Pipeline Asset Renderer asset and the newly generated Pipeline Asset asset.
-
In Project Settings > Graphics, set the “Scriptable Render Pipeline Settings” to your Pipeline Asset asset.
-
Your shaders should now render properly.
UI Toggles no longer fire OnValueChanged when toggled
-
Situation: After switching to 2020 LTS, Toggle UI elements no longer fire OnValueChanged.
-
Description: If you’re following the recommendation to disable Domain and Scene reloads ( #Protip: Super fast enter playmode times when working in DOTS ) to speed up entering playmode, then your UI Toggle elements will no longer fire the OnValueChanged event after migrating to 2020 LTS. This issue appears to be fixed on the 2021.x path but doesn’t appear to be addressed on 2020 LTS as of 2020.3.3f1.
-
Solutions:
-
Either reenable Domain and/or Scene reloads in the Project Settings
-
Or, follow some of the hacks outlined in the thread Toggle OnValueChanged Parameter Doesn’t Change .
If anyone has recommendations, comments, or feedback on how best to handle a downgrade would be great if you shared them. I’d also like to hear of any issues people encounter during a downgrade and how they’ve handled them so that those can be incorporated into this guide.