How to update unity
How to update unity
Switching to another package version
You can update a package while in the In Project, Unity Registry, or My Registries context:
Open the Package Manager window and select In Project from the Packages Packages are collections of assets to be shared and re-used in Unity. The Unity Package Manager (UPM) can display, add, and remove packages from your project. These packages are native to the Unity Package Manager and provide a fundamental method of delivering Unity functionality. However, the Unity Package Manager can also display Asset Store packages that you downloaded from the Asset Store. More info
See in Glossary drop-down menu.
Switch the context to In Project
An arrow indicator appears next to any packages that have updates available.
Select the installed package you want to update from the list of packages. The package information appears in the details view.
The lock icon ( ) indicates that this package and version is locked to an installed feature set. To unlock the package and select another version, click the Unlock button.
Note: The package is only temporarily unlocked. If you change to a different list context, or close either the Package Manager or the Editor, the package reverts to being locked again. However, if you switch versions when the package is unlocked (for example, with the Add package by name method), the package stays unlocked.
In the list of packages, click the expander icon to the left of the package name.
Currently installed and Recommended are the only versions available
Note: If you see the See other versions link after expanding the package, you can click it to see the list of all available versions for that package.
Select any version of the current package to see the details specific to that version in the details view.
Update to button in the bottom right corner of the details view
Click the Update to button.
When the progress bar finishes, any new functionality is immediately available.
Note: If you switch to an older version of a package, you might have to run the API Updater on the package contents.
Check For Updates
Unity checks whether updates are available. This check happens either when Unity is started, or when you choose the Help->Check for Updates menu item. The update check sends the current Unity revision number (the five digit number that appears in brackets after the version name in the About Unity dialog) to the update server where is it compared with the most-up-to-date released version. If a newer version of Unity is available the following dialog is shown:
Window displayed when there is a newer version of Unity available for download.
If the version in use is the most up-to-date then the following dialog is shown:
Window displayed when Unity is updated to the latest version.
Click the Download new version button to be taken to the website where you can download the new version.
Update Check Frequency
The response from the server also contains a time interval which suggests when the next update check should be made. This allows the update check to be made less frequently when Unity is not expecting updates to be made available.
Skipping Update Versions
If you are in the middle of a project you may not want to update to a new version of Unity. Ticking the Skip this version button on the Unity Editor Update Check dialog will prevent Unity from telling you about this update.
Disabling the Update Check
It is not possible to disable the check for updates. The Check For Updates tick box on the dialog controls whether you are notified of updates (if they are available) when Unity starts. Even if you have unticked the Check for Updates option you can still check for updates by using the Help->Check for Updates menu item.
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)
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 scripts A 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:
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.
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.
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
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 Tilemap A 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:
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.
Assembly definition for the Tilemap Editor
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
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):
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.
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
.NET 3.5 Equivalent Scripting Runtime Removal
Lighting Improvements
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 API A 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 profiler A 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
Upgrading to Unity 2021 LTS
Follow the advice in this section in release order. For example, if you need to upgrade your project from 2019 to 2021, read the 2020 upgrade guide to see if there are any changes that you need to make before you read the 2021 upgrade guides.
This page lists changes in the Unity 2021 LTS version which might affect existing projects when you upgrade from a 2020 version to 2021 LTS.
Note: 2021LTS is also known as 2021.3.
Page Outline
Device Simulator
The Device Simulator is now part of the Editor and is accessible from the Game window. To set up the Device Simulator, add the UnityEngine.Device namespace to the Screen, Application, and SystemInfo classes: UnityEngine.Device.Screen; UnityEngine.Device.Application; UnityEngine.Device.SystemInfo;
Environment Lighting
Environment lighting: Ambient probe and skybox reflection probe are now automatically baked
Unity’s Progressive Lightmapper A tool in Unity that bakes lightmaps according to the arrangement of lights and geometry in your scene. More info
See in Glossary now automatically generates the ambient probe and the skybox reflection probe A rendering component that captures a spherical view of its surroundings in all directions, rather like a camera. The captured image is then stored as a Cubemap that can be used by objects with reflective materials. More info
See in Glossary for every scene by default. This means that a scene automatically receives environment lighting in accordance with the settings in the Environment tab in the Lighting settings panel. The Editor updates the ambient probe and skybox reflection probe every time the environment lighting changes, until you generate lighting. When you bake with the Generate Lighting control, the Editor stops updating the probes, and only updates them again at the next bake. When you enable the Auto Generate option, the Editor continues to update the probes every time the environment lighting changes. If you generate lighting and then delete this lighting data by removing the Lighting Data Asset from the project, the Editor automatically generates the ambient probe and skybox reflection probe again.
There is one situation which requires action when you upgrade a project. This is when you don’t wish to have any Environment lighting contribution in a project which also:
In this situation, navigate to Window > Rendering > Lighting Settings > Environment and disable the environment contribution of the automatically generated ambient probe and skybox reflection probe by making one of the following changes:
Enable Code Coverage preference
The user interface for managing Code Coverage has moved from General Preferences to within the Code Coverage package.
In Unity 2021 the Enable Code Coverage checkbox was moved in the Code Coverage window.
The Code Coverage package is available as a released package via the Package Manager for Unity 2019.3 and above. The latest version is 1.0.0.
You can use one of the following methods to enable code coverage:
Particle System Force Fields
Previously, some Force Field properties behaved differently at different frame rates (or if using the Time Scale in the Time Manager settings)
The Particle System A component that simulates fluid entities such as liquids, clouds and flames by generating and animating large numbers of small 2D images in the scene. More info
See in Glossary now uses a reference frame rate of 30fps to serve as the basis for the simulation. If your app runs at a different frame rate, the following settings might behave differently compared to earlier versions of Unity:
If these settings are affected, adjust the strengths of the affected areas to get the desired appearance.
Particle System Start Delay + Rate over Distance emission
Previously, Rate over Distance emission ignored the Start Delay setting. Now, if the Start Delay setting is defined, it delays the start for the distance-based emission.
If this field was previously set, you might need to adjust it.
PackedAssets.file has been marked obsolete without a direct replacement. Previously this held an integer signifying a file id or index into BuildReport.files To look up BuildReport files now, use PackedAssets.shortPath.
Terrain APIs out of experimental (WIP)
The experimental Terrain The landscape in your scene. A Terrain GameObject adds a large flat plane to your scene and you can use the Terrain’s Inspector window to create a detailed landscape. More info
See in Glossary APIs have been moved to non-experimental namespaces. There have also been some other minor changes to the Terrain API. If you used the experimental Terrain APIs, use the following APIs instead:
Here is the full list of API changes:
Texture2D.Resize renamed to Reinitialize
Android changes
A large part of the Android build pipeline is now incremental and Unity removed the following features that were in the previous build pipeline:
Default Image.scaleMode was changed from ScaleAndCrop to ScaleToFit.
The expected behavior for an image is to scale to the size of the element, so we changed the default value of Image.scaleMode to ScaleToFit. If you didn’t override the Image scale mode, some cropped images might shrink to fit the size of the element. If ScaleAndCrop was the expected mode for your images, you can override their style by adding the following value in your UXML file inline style:
You can also create a style class with the override and apply it to images that require ScaleAndCrop.
Mono upgrade behavior changes
The underlying C# runtime, Mono, has been upgraded in the latest version. This includes many fixes from the upstream version of Mono, and some notable changes in behavior.
Adaptive Performance
Version 3.0 of the Adaptive Performance package is now available. For information on how to upgrade to version 3.0, see the Adaptive Performance upgrade guides.
RenderTexture DepthStencilFormat
The new RenderTexture.depthStencilFormat property returns the format that the graphics API uses to create the resource in video memory. You can also use this property to request a specific format. However, not all platforms support all depth stencil formats. When you set the DepthStencilFormat property to an unsupported format, Unity automatically selects a compatible format that has the equal or greater amount of bits for the depth and stencil components.
Upgrading
The RenderTexture asset now serializes the depth stencil format that you selected. If you use an API that takes a number of bits instead of a format, these bits get mapped to a format and that format is serialized. RenderTexture assets from previous versions that had the depth set to more than 16-bits are automatically upgraded to use D24_S8.
On some platforms (for example Windows) that use the DirectX graphics API, this results in a format with fewer depth bits because the graphics backend selects the D32_S8 format internally if you set bits>16. To ensure consistent upgrades across all platforms, D24_S8 is used on all platforms for the automatic upgrader. However, this might introduce visual artifacts in the render output of your project if you have RenderTexture assets in your project. Review these assets and change the depth stencil format to D32_S8 when needed. The following issues might occur:
Graphics formats DepthAuto, ShadowAuto and VideoAuto are deprecated
The following graphics formats have now been deprecated:
These Auto formats are unclear about the exact format that’s used and might vary by platform.
The steps to remove the use of these deprecated formats depends on the format and use case.
For VideoAuto
For DepthAuto/ShadowAuto used to indicate a depth-only render texture.
The GraphicsFormat API often uses DepthAuto or ShadowAuto to create render textures A special type of Texture that is created and updated at runtime. To use them, first create a new Render Texture and designate one of your Cameras to render into it. Then you can use the Render Texture in a Material just like a regular Texture. More info
See in Glossary with depth-only rendering, and no color buffer. Examples of this use case are:
To indicate depth-only (non-color) rendering, use GraphicsFormat.None as the new color format. renderTextureDescriptor.graphicsFormat = GraphicsFormat.None;
If you used ShadowAuto, set the shadowSamplingMode of your RenderTextureDescriptor to ShadowSamplingMode.CompareDepths to enable depth-compare sampling on the depth texture, and change the code to use an overload that takes a RenderTextureDescriptor. renderTextureDescriptor.shadowSamplingMode = ShadowSamplingMode.CompareDepths;
For DepthAuto/ShadowAuto in other situations
In some situations the DepthAuto/ShadowAuto formats represented an automatically selected depth format appropriate for the current platform. To replace the deprecated values in this case, use SystemInfo.GetGraphicsFormat(DefaultFormat.Depth/Shadow)
WebGL: Updated Emscripten to 2.0.19
The asm.js Linker target that was available for advanced users is no longer available.
Progressive GPU Lightmapper dropped support for CPU OpenCL devices
OnPostprocessAllAssets behavior changes
When Unity calls InitializeOnLoad methods during the asset import process, asset loading can fail. During asset import, the asset database is in an update state and Unity can’t determine which assets have already been imported. InitializeOnLoad methods can’t load assets that haven’t been imported.
To improve the asset import process, the OnPostprocessAllAssets callback has been enhanced. In particular, the OnPostprocessAllAssets callback:
Move any domain-related initialization logic that requires asset operations to the OnPostprocessAllAsset callback; do not perform asset operations inside InitializeOnLoad methods.
The following behavior change code examples show how asset operations were previously postponed.
The following example has the new OnPostprocessAllAssets variant with the didDomainReload parameter:
All domain reloads are now processed inside the asset database.
OnPostprocessAllAssets now works better with asset operations, but any processing in this callback increases asset database refresh and domain reload time. InitializeOnLoad methods also add to domain reload time. It is best practice to minimize processing in these callbacks to improve Editor responsiveness between iterations.
Mixed point and spot lights with no shadows bake direct light in subtractive lighting mode
Mixed mode point and spot lights now consistently contribute baked direct light in Scenes using Subtractive lighting mode, regardless of their Shadow Type setting. As a result, specular lighting for Static GameObjects The fundamental object in Unity scenes, which can represent characters, props, scenery, cameras, waypoints, and more. A GameObject’s functionality is defined by the Components attached to it. More info
See in Glossary may appear to be missing in affected Scenes. To resolve this issue, replace affected Mixed mode lights with Realtime mode Lights. Alternatively, use Baked Indirect or Shadowmask A Texture that shares the same UV layout and resolution with its corresponding lightmap. More info
See in Glossary lighting mode(s) with Mixed lights.
Shader keyword system improvements
The shader A program that runs on the GPU. More info
See in Glossary keyword system now allows up to 65534 local keywords per shader or compute shader and 2 32 –2 global keywords per project. All keywords you declare in a shader or compute shader are now local to this shader. Keywords you declare in a directive with the _local suffix aren’t affected by the state of global keywords.
A pass in a shader declares the following keywords:
When using this pass, keywords FOO and BAR are enabled if they’re enabled either globally or on the material. Keywords BOO and BAZ are only enabled if they’re enabled on the material.
Sources of conflict include the following:
Resolve ambiguous references
For example, if you add a type named MyCompany.MyCode.Range to your project’s code, this might conflict with the existing System.Range type. Code that contains both using System; and using MyCompany; statements fails to compile.
To prevent errors, fully specify the namespace in the C# code for any types that have conflicting names.
Resolve conflicting extension methods
Resolve conflicting assemblies
If your project uses precompiled assemblies (that is, managed plugins) that implement types and methods that are now part of the base class library, then remove these assemblies from your project and use the built-in implementations.
Windows XR plugin removed
Microsoft has deprecated the Windows XR An umbrella term encompassing Virtual Reality (VR), Augmented Reality (AR) and Mixed Reality (MR) applications. Devices supporting these forms of interactive applications can be referred to as XR devices. More info
See in Glossary plugin and now supports Windows Mixed Reality (WMR) features and devices through the OpenXR plugin.
To upgrade to the Unity OpenXR plugin:
Once the OpenXR plugin is enabled, you can use the Mixed Reality Feature Tool provided by Microsoft to install the required supporting packages.
To install or update WMR features, tools, and samples:
For more information about setting up new and updated Unity projects to use Windows Mixed Reality, see Setting up your XR configuration on Microsoft’s documentation site.
Switching to another package version
You can update a package while in the In Project, Unity Registry, or My Registries context:
Open the Package Manager window and select In Project from the Packages Packages are collections of assets to be shared and re-used in Unity. The Unity Package Manager (UPM) can display, add, and remove packages from your project. These packages are native to the Unity Package Manager and provide a fundamental method of delivering Unity functionality. However, the Unity Package Manager can also display Asset Store packages that you downloaded from the Asset Store. More info
See in Glossary drop-down menu.
Switch the context to In Project
An arrow indicator appears next to any packages that have updates available.
Select the installed package you want to update from the list of packages. The package information appears in the details view.
The lock icon ( ) indicates that this package and version is locked to an installed feature set. To unlock the package and select another version, click the Unlock button.
Note: The package is only temporarily unlocked. If you change to a different list context, or close either the Package Manager or the Editor, the package reverts to being locked again. However, if you switch versions when the package is unlocked (for example, with the Add package by name method), the package stays unlocked.
In the list of packages, click the expander icon to the left of the package name.
Currently installed and Recommended are the only versions available
Note: If you see the See other versions link after expanding the package, you can click it to see the list of all available versions for that package.
Select any version of the current package to see the details specific to that version in the details view.
Update to button in the bottom right corner of the details view
Click the Update to button.
When the progress bar finishes, any new functionality is immediately available.
Note: If you switch to an older version of a package, you might have to run the API Updater on the package contents.