Upgrading to Unity 2019 LTS
Note: Follow the advice in this section in release order. For example, if you need to upgrade your project from 2018 to 2020, read the 2019 upgrade guides to see if there are any changes that you need to make before you read the 2020 upgrade guides.
This page lists changes in the Unity 2019 versions which might affect existing projects when you upgrade from any Unity 2018 version to 2019 LTS. If you’re upgrading from a Unity 2017 version, first see the Upgrading to Unity 2018 LTS guide.
Note that 2019 LTS is also known as 2019.4.
Page outline
- Lightweight Render Pipeline (LWRP) becomes Universal Render Pipeline (URP)
- ShaderUtil update
- Animation C# Jobs
- Scripting Render Pipeline (SRP) API changes
- Addressables
- New Asset Import Pipeline
- Tilemap Editor is now a Package
- SpriteTooling is now a Package
- Unity UI is now a Package
- UI Elements is now a standard feature and not experimental
- .NET 3.5 Equivalent Scripting Runtime Removal
- Lighting Improvements
- UnityAPICompatibilityVersionAttribute constructor change
- Changed System Requirements
- Multiplayer (UNet) High level API has moved to a package
- UNITY_ADS compiler directive removed
Lightweight Render Pipeline (LWRP) becomes Universal Render Pipeline (URP)
The Lightweight Render Pipeline (LWRP) is now the Universal Render Pipeline (URP) in Unity 2019.3 and later.
If your Project uses LWRP, you will need to upgrade your Project to use URP. For a step by step guide to the upgrade process, see the LWRP to URP upgrade guide.
ShaderUtil update
ShaderUtil.ClearShaderErrors() is replaced by ShaderUtil.ClearShaderMessages() for naming consistency and is now marked as obsolete. Your existing Project scriptsA piece of code that allows you to create your own Components, trigger game events, modify Component properties over time and respond to user input in any way you like. More info
See in Glossary are automatically upgraded when you open them in Unity 2019.4.
Animation C# Jobs
Animation C# jobs are moving out of experimental namespace from UnityEngine.Experimental.Animations to UnityEngine.Animations.
Unity 2019.4 automatically updates most of your scripts except for scripts with the following Animator jobs extension methods:
- BindStreamTransform
- BindStreamProperty
- BindCustomStreamProperty
- BindSceneTransform
- BindSceneProperty
- OpenAnimationStream
- CloseAnimationStream
- ResolveAllStreamHandles
- ResolveAllSceneHandles
You have to manually add using UnityEngine.Animations; statements to those scripts.
Scripting Render Pipeline (SRP) API changes
The undocumented RenderPipeline.beginCameraRendering and RenderPipeline.beginFrameRendering events have been removed. You should replace these with events from the RenderPipelineManager class.
The RenderPipeline static protected functions BeginFrameRendering and BeginCameraRendering have been removed. You must replace these with the signature that takes a ScriptableRenderContext in a parameter. Additionally there are now EndCameraRendering and EndFrameRendering methods that you must call as well.
Addressables
AsyncLoad is now obsolete. Use Async.LoadAssetAsync instead.
New Asset Import Pipeline
The new Asset Import Pipeline is available with Unity 2019.3 and later. If you have an existing project, you can upgrade to the new Asset Import Pipeline using the Project Settings Window in the Editor:
Selecting Version 2 will tell the editor you now want to use the new Asset Import Pipeline together with this project, and restarting your project will re-import it using the new Asset Import Pipeline code. This essentially has the same effect as deleting your Library folder, but without deleting it. When switching to use Asset Import Pipeline V2, the Import Results from the original Asset Import Pipeline are not deleted as V2 creates its own folder structure to store its Import Results. Projects that you’ve created in Unity 2019.2 or older will still use their original Asset Import Pipeline by default. When opening such a project in Unity 2019.3 for the first time, you’ll get an option to upgrade to the new Asset Import Pipeline. If you decline, your project will continue using the original Asset Import Pipeline. Furthermore, the selected version is stored in the EditorSettings.asset file of your project, so it can be version controlled.
New Projects created with the new Asset Import Pipeline
When creating a new Project with Unity 2019.3 or newer, the new Asset Import Pipeline has become the new default way to work. All new projects you create will be using it.
Behaviour changes to the New Asset Import Pipeline
Multiple versions of the same asset are cached in the Library folder
Up until Unity 2019.2 (with the original Asset Import Pipeline), the Library folder was comprised of the GUIDs of Assets being their filename. Thus, switching from a platform to another platform would invalidate the Import Result in the Library folder, causing it to be re-imported every time you switch platforms.
Asset Import Pipeline V1
If you had to switch back and forth between platforms multiple times per day, this could easily take up hours, depending on your project size.
Some of you have figured out workarounds for this, such as having a copy of your project per platform on your machine, but that doesn’t scale very well.
With the new Asset Import Pipeline, we’ve removed the GUID to File Name mapping. Since dependencies
See in Glossary for a particular Asset are tracked, we are able to Hash them all together to create a revision for the Import Result of an Asset. This allows us to have multiple revisions per Asset, which then means that we are no longer bound by a GUID to File Name mapping. Not having this requirement allows us to have Import Results which work across different configurations. For Fast Platform Switching, we could have an Import Result per platform, so that when you switch platforms back and forth the Import Result is already there, thus making the platform switch many orders of magnitude faster than with the Asset Import Pipeline V1.
Asset Import Pipeline V2
Caching and the Unity Accelerator
Most of the importers have had significant work done to them in order to improve their determinsm and have a positive effect on caching. This means that if the Unity Accelerator is used, the import result will be uploaded to a centralized storage where other machines can connect to and benefit from the work done for the same Asset on a different machine. Assets with dynamic dependencies can be cached now (e.g. nested prefabs, shaders, etc.). For a more comprehensive list of Importers and their associated files, check out the new AssetDatabase Manual page
Caching of Scripted Importers:
ScriptedImporters and importers with registered dependencies were not cached with the old Asset Import Pipeline.
Old Behaviour
With the old Asset Import Pipeline, the switching of platforms invalidated all imports as the Import Result was GUID based, thus switching a platform would overwrite the import result every time.
New Behaviour
In the new Asset Import Pipeline, switching platforms does not invalidate imports as the File on disk representing the import result is a hash of its own contents, thus ensuring that when switching platform the contents are different and result in a new file, thus keeping both versions of the Import Result around and simply switching between one or another, without having to import anything.
Number of Calls to OnPostProcessAllAssets
In the old Asset Import Pipeline, the number of calls to the OnPostProcessAllAssets function was non-deterministic. Meaning that this function could be called once, or multiple times, for the same changes. With the new Asset Import Pipeline, there will be a single call to OnPostProcessAllAssets for detected Script changes (.cs files), and one for non-script changes (think .png, .fbx, .wav files).
Synchronous Script Compilation
In the old Asset Import Pipeline, one could trigger a compilation and chain going into play mode while a compilation was happening. This was a big time saver in certain situations, having non-synchronous compilation could lead to non-deterministic results. With the new Asset Import Pipeline, this has been changed so that the Asset Import Pipeline drives the majority of Script Compilation, and as such it requires a deterministic approach, thus locking up the editor until Script Compilation completes.
Tilemap Editor is now a Package
The TilemapA GameObject that allows you to quickly create 2D levels using tiles and a grid overlay. More info
See in Glossary Editor is now a package. This package is automatically installed in new Unity Projects created with the 2D Project template. For more information on installing a package see Adding and removing packages.
All public classes have been moved to the UnityEditor.Tilemaps namespace. Unity compiles your scripts that reference these classes into the “Unity.2D.Tilemap.Editor” Assembly Definition Asset. These are:
- GridBrush
- GridBrushEditorBase
- GridBrushEditor
- GridSelection
Unity will attempt to update the relevant Tilemap using statements in your scripts but please check and change if needed.
If you are referencing the Tilemap Tooling classes with scripts which are part of an Assembly Definition, you should add the “Unity.2D.Tilemap.Editor” Assembly Definition as an Assembly Definition Reference under your Assembly Definition. Unity may have set this automatically for you but please change it if it hasn’t.
If you have precompiled assemblies referencing the Tilemap Tooling classes from a previous version of Unity, you will encounter issues when using them due to these changes. If possible, please update and recompile these assemblies against the new Tilemap Tooling assemblies.
If you have precompiled assemblies referencing the Tilemap Tooling classes from a previous version of Unity, you need to update and recompile these assemblies to reference the new Tilemap Tooling assemblies.
Examples of these issues when importing the precompiled assembly are (as errors in the Console window):
Failed to extract {Class in Precompiled Assembly} class of base type UnityEditor.GridBrush when inspecting {Precompiled Assembly} Unloading broken assembly {Precompiled Assembly}, this assembly can cause crashes in the runtime
These errors can be caused by inheriting from one of the Tilemap Tooling classes such as the GridBrush.
Examples of these issues when using the precompiled assembly are (as errors in the Console window):
TypeLoadException: Could not resolve type with token 01000011 (from typeref, class/assembly UnityEditor.GridBrush, UnityEditor, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null)
Error: Could not load signature of {Method in Precompiled Assembly) due to: Could not resolve type with token 01000011 (from typeref, class/assembly UnityEditor.GridBrush, UnityEditor, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null) assembly:UnityEditor, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null type:UnityEditor.GridBrush member:(null) signature:<none>
These errors can be caused by creating or calling one of the methods of the Tilemap Tooling classes such as the GridBrush.
SpriteTooling is now a Package
Sprite Tooling (Sprite Editor Window) is now a package. For more information on installing a package see Adding and removing packages.
- This package is not added to a new Unity Project by default, unless the new Project is created with the 2D Project template.
- This package will be added to pre-existing Unity Projects (2019.1 and prior) when upgraded to Unity 2019.1. You can remove this package If your project doesn’t use 2D Sprites and doesn’t require the use of SpriteA 2D graphic objects. If you are used to working in 3D, Sprites are essentially just standard textures but there are special techniques for combining and managing sprite textures for efficiency and convenience during development. More info
See in Glossary Tooling. - As part of converting the Sprite Tooling to a Package, the Experimental namespaces has been removed. If your project has scripts which reference classes related to Sprite Tooling, please ensure that they are using the correct namespace after the upgrade, eg. adding “using UnityEditor.U2D.Sprites” if required.
- If you are referencing the Sprite classes with scripts which are part of an Assembly Definition, you need to add the “Unity.2D.Sprite.Editor” Assembly Definition as an Assembly Definition Reference under your Assembly Definition.
Unity UI is now a Package
Unity UI (UGUI) is now a package, com.unity.ugui. You can access it from the Package Manager (menu: Window > Package Manager).
Unity UI(User Interface) Allows a user to interact with your application. More info
See in Glossary is a core package that ships with Unity. You do not need to install it in new Projects.
When you upgrade existing Unity Projects, created with version 2019.2b1 and earlier, to Unity 2019.2, this package is added automatically.
Assembly definitions automatically get a reference to the uGUI assembly.
If you install Unity 2019.2 overtop of an older version of Unity, make sure that the GUISystem folder, located in \Editor\Data\UnityExtensions\Unity is removed. Otherwise you might get class redefinition errors.
The Unity UI source code is no longer published to BitBucket because Unity provides it with the package.
The Unity UI API documentation is no longer in the main Scripting API reference. You can access it from the Scripting API section of the Unity UI package documentation.
UI Elements is now a standard feature and not experimental
See the UI Elements 2019.1 upgrade guide for more information.
.NET 3.5 Equivalent Scripting Runtime Removal
The .NET 3.5 Equivalent option for Scripting Runtime Version has been removed. Projects are automatically migrated to use the .NET 4.x Equivalent option when opened in 2019.2.
Lighting Improvements
Prior to 2019.1 Indirect Intensity slider only affected lightmapsA pre-rendered texture that contains the effects of light sources on static objects in the scene. Lightmaps are overlaid on top of scene geometry to create the effect of lighting. More info
See in Glossary when using the Progressive LightmapperA tool in Unity that bakes lightmaps according to the arrangement of lights and geometry in your scene. More info
See in Glossary. For EnlightenA lighting system by Geomerics used in Unity for lightmapping and for Realtime Global Illumination. More info
See in Glossary, it was applied to both light probesLight probes store information about how light passes through space in your scene. A collection of light probes arranged within a given space can improve lighting on moving objects and static LOD scenery within that space. More info
See in Glossary and light maps. Now all backends apply Indirect Intensity value to both lightmaps and light probes.
Upon baking the lighting again, you might notice that the probes will appear brighter if the Indirect Intensity value was modified.
It is best to Clear Baked Data prior to baking lightmaps again after the upgrade.
UnityAPICompatibilityVersionAttribute constructor change
The constructor that takes a single string is now obsolete. See the documentation for information on the supported overloads.
Changed System Requirements
Projects made with Unity 2019 LTS require versions macOS 10.12 or Ubuntu 16.04 or later.
Multiplayer (UNet) High level API has moved to a package
The multiplayer high level APIA system for building multiplayer capabilities for Unity games. It is built on top of the lower level transport real-time communication layer, and handles many of the common tasks that are required for multiplayer games. More info
See in Glossary has been moved from an extension to a package. This doesn’t affect the NetworkTransport class (the low level API). All dependencies which were in the Unity engine have been moved to the package. This means the high level API is now independent except for some hooks into the profilerA window that helps you to optimize your game. It shows how much time is spent in the various areas of your game. For example, it can report the percentage of time spent rendering, animating, or in your game logic. More info
See in Glossary which couldn’t be migrated at this time.
Older Projects containing the high level API will have the package automatically added to prevent compiler errors. This does not happen for new Projects and you can add it if required from the Package Manager window. See the multiplayer high level API documentation.
The UNITY_ADS directive was removed
As of 2019.4, Unity no automatically defines UNITY_ADS. You need to either stop using UNITY_ADS in your scripts, or create a new custom global #define for it. See the Platform Dependent Compilation page for guidance on how to create a new custom global #define.