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.

Back to top

ShaderUtil update

ShaderUtil.ClearShaderErrors() is replaced by ShaderUtil.ClearShaderMessages() for naming consistency and is now marked as obsolete. Your existing Project scripts are automatically upgraded when you open them in Unity 2019.4.

Back to top

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.

Back to top

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.

Back to top

Addressables

AsyncLoad is now obsolete. Use Async.LoadAssetAsync instead.

Back to top

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

Back to top

Tilemap Editor is now a Package

The Tilemap 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.

Back to top

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

Back to top

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

Back to top

UI Elements is now a standard feature and not experimental

See the UI Elements 2019.1 upgrade guide for more information.

Back to top

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

Back to top

Lighting Improvements

Prior to 2019.1 Indirect Intensity slider only affected lightmaps when using the Progressive Lightmapper. For Enlighten, it was applied to both light probes 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.

Back to top

UnityAPICompatibilityVersionAttribute constructor change

The constructor that takes a single string is now obsolete. See the documentation for information on the supported overloads.

Back to top

Changed System Requirements

Projects made with Unity 2019 LTS require versions macOS 10.12 or Ubuntu 16.04 or later.

Back to top

Multiplayer (UNet) High level API has moved to a package

The multiplayer high level API 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 profiler 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.

Back to top

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.