This page lists changes in Unity 6 which might affect existing projects when you upgrade them from 2022 LTS version to Unity 6.
This upgrade guide describes how to upgrade to the Unity 6 version of Unity’s Built-In Render Pipeline. To upgrade other render pipelines, refer to:
To upgrade other packages, refer to the documentation for the packages you’re using.
The Progressive Lightmapper includes a Gaussian option among its Advanced filtering options (Lighting Window > Lightmapping Settings > Filtering > Direct Filter > Gaussian). The Radius control for Gaussian filtering now supports decimal increments, such as 0.5. Previously, this control only supported integer steps (1 to 5).
As a result of this change, these properties are now deprecated in the C# API:
int LightingSettings.filteringGaussRadiusAOint LightingSettings.filteringGaussRadiusDirectint LightingSettings.filteringGaussRadiusIndirectThe floating point replacements for the deprecated properties are:
float LightingSettings.filteringGaussianRadiusAOfloat LightingSettings.filteringGaussianRadiusDirectfloat LightingSettings.filteringGaussianRadiusIndirectYou can call one of the deprecated member functions to round the Gaussian filter radius to the nearest integer.
Light Probes are now as bright as 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. Previously, Unity’s 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 were only 94% as bright as they should be. For this reason, objects lit with light probes appeared a bit darker than objects lit with lightmaps. Because of the subtlety of this change, it is possible that many users won’t see a noticeable difference.
Should you prefer the old appearance, you can achieve it in the following way:
The EnlightenA lighting system by Geomerics used in Unity for Enlighten Realtime Global Illumination. More info
See in Glossary Baked Global IlluminationA group of techniques that model both direct and indirect lighting to provide realistic lighting results.
See in Glossary lightmapping backend is no longer available.
When you upgrade a project to this version, Unity removes the Enlighten baking backend from the lightmapperA tool in Unity that bakes lightmaps according to the arrangement of lights and geometry in your scene. More info
See in Glossary selection dropdown and substitutes a Progressive Lightmapper in every SceneA Scene contains the environments and menus of your game. Think of each unique Scene file as a unique level. In each Scene, you place your environments, obstacles, and decorations, essentially designing and building your game in pieces. More info
See in Glossary where you’ve selected the Enlighten baking backend.
On Apple silicon devices, Unity substitutes the Progressive GPU Lightmapper for the Enlighten baking backend. On all other devices, Unity selects the CPU Progressive Lightmapper.
Enlighten precomputed Realtime Global Illumination is still available and is supported up until Unity 2024 LTS.
The UnityPlayer Java class has been replaced by two new bridge classes, UnityPlayerForActivityOrService and UnityPlayerForGameActivity. These new classes both derive from UnityPlayer, but public methods such as displayChanged and windowFocusChanged have moved from UnityPlayer specifically to UnityPlayerForActivityOrService.
If you extend the default Unity activity and use the UnityPlayer class, you might encounter compile errors. In this case, rename UnityPlayer to UnityPlayerForActivityOrService.
The UnityPlayer Java class no longer extends FrameLayout. If you need to access FrameLayout, call the getFrameLayout function on the UnityPlayer instance.
RenderPipelineEditorUtility.FetchFirstCompatibleTypeUsingScriptableRenderPipelineExtension is now deprecated. Use GetDerivedTypesSupportedOnCurrentPipeline instead. This method’s signature is also different; now it returns all derived types, not just the first one it encounters. This prevents inconsistencies, because Unity does not guarantee type order.
CustomEditorForRenderPipelineAttribute and VolumeComponentMenuForRenderPipelineAttribute are now deprecated. Use CustomEditor and VolumeComponentMenu instead. To restrict the choice of pipeline when these attributes are active, combine them with SupportedOnRenderPipelineAttribute and specify a RenderPipelineAsset type. If you want to activate an SRP attribute that does work with the Built-In Render Pipeline, use SupportedOnRenderPipelineAttribute without parameters. This provides a unified workflow for both attributes when there’s a need to activate them on a specific pipeline.
A new API to modify the Android GradleAn Android build system that automates several build processes. This automation means that many common build errors are less likely to occur. More info
See in Glossary project was introduced. The API can be used to replace the old Android Gradle templates workflow. Templates will still work as before if the new API is not used.
To use the new API a Templates Upgrader can be used:
Unity’s Progressive Lightmapper no longer bakes the ambient probe and the skyboxA special type of Material used to represent skies. Usually six-sided. More info
See in Glossary Reflection ProbeA 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 by default, and the Recalculate Environment Lighting setting in the Lighting window has been removed.
To avoid a newly created scene having no environment lighting, Unity assigns a default Lighting Data Asset containing environment lighting that matches the default skybox material.
You must select Generate Lighting in the Lighting window in the following cases:
If you rely on the previous automatic baking behavior but you use the default environment lighting settings, Unity upgrades the scene to use the default Lighting Data Asset.
The Auto Generate setting in the Lighting window has been removed, and related APIs are now obsolete.
To generate baked lighting for a scene, you can do any of the following:
Lightmapping.Bake API.Lightmapping.BakeAsync API.To check lightmaps while you’re editing, you can now select a Scene View Draw Mode and set Lighting Data to Preview. This displays a preview of the baked lighting. The preview lightmaps are non-destructive, and you can use them after you’ve baked the scene.
If a scene relies on auto-generated lighting, it no longer has its baked lighting. Select Generate Lighting in the Lighting window to re-bake the lighting manually.
If you use a script to open a scene, you must now use Lightmapping.Bake or Lightmapping.BakeAsync instead of waiting for auto-generated lighting to complete.
The following graphics formats, which were previously deprecated in 2022.1, are now obsolete and produce compile errors if you use them:
GraphicsFormat.DepthAutoGraphicsFormat.ShadowAutoGraphicsFormat.VideoAutoThe GraphicsFormatUtility.GetGraphicsFormat API no longer returns the obsolete formats. Instead it does the following:
RenderTextureFormat.Depth to GraphicsFormat.None instead of GraphicsFormat.DepthAuto. GraphicsFormat.None indicates depth-only rendering.RenderTextureFormat.Shadowmap to GraphicsFormat.None instead of GraphicsFormat.ShadowAuto. If you create a render textureA 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 infoGraphicsFormat.None format, you must set RenderTextureDescriptor.shadowSamplingMode to ShadowSamplingMode.CompareDepths to enable depth-compare sampling.Because GraphicsFormat.DepthAuto and GraphicsFormat.ShadowAuto were both considered depth stencil formats but used as colors formats, you may need to adjust your code.
For example, in the following snippet, GraphicsFormatUtility.IsDepthFormat returns false instead of true:
RenderTextureDescriptor desc = new RenderTextureDescriptor(256, 256, RenderTextureFormat.Depth, 32);
bool isDepthOnly = GraphicsFormatUtility.IsDepthFormat(desc.graphicsFormat);
To check if a RenderTexture or RenderTextureDescriptor is depth-only, use one of the following:
if (renderTexture.graphicsFormat == GraphicsFormat.None && renderTexture.depthStencilFormat != GraphicsFormat.None)if (renderTexture.format == RenderTextureFormat.Depth || renderTexture.format == RenderTextureFormat.Shadowmap)Runtime-created 2D textures will no longer have their mipmap upload limited by default. Before, mipmap limits had to be disabled explicitly via the Texture2D constructor (by providing an ignoreMipmapLimit boolean parameter when the constructor is called with a TextureFormat, or the IgnoreMipmapLimit TextureCreationFlag when it’s called with a GraphicsFormat), or by toggling tex.ignoreMipmapLimit of a constructed texture. This behavior has changed: mipmap limits are now opt-in for runtime-created 2D textures.
Without making project changes, in the following cases users miss out on GPU bandwidth and memory optimizations, and potentially see a better quality than intended because textures are now getting uploaded at full resolution:
In following cases, users are not affected by this change:
false for ignoreMipmapLimit,tex.ignoreMipmapLimit to false after construction.These users may want to upgrade their 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 if they use deprecated constructors.
To upgrade your scripts, use a Texture2D constructor with a MipmapLimitDescriptor to indicate that a runtime Texture should be affected by the quality settings.
This change was made for consistency with the new mipmap limit support for Texture2DArrays. Rather than having each texture shape define its own default mipmap limit behavior, we opt for consistency and have decided that runtime textures should explicitly enable mipmap limits. This opt-in behavior is preferred over opt-out because runtime textures are often used in more versatile ways where unexpectedly uploading fewer mips than expected could be more harmful than unexpectedly uploading more mips.
Simplified the creation of custom controls with UXML in UI(User Interface) Allows a user to interact with your application. Unity currently supports three UI systems. More info
See in Glossary Toolkit to speed up the workflow and make it more intuitive.
A key improvement is the introduction of UxmlElement and UxmlAttribute attributes. These attributes simplify attribute authoring and automatically derive the attribute names from property names, eliminating the need for UxmlTraits and UxmlFactory classes.
You can now create custom attribute converters for specific data types, ensuring seamless conversion of values to and from UXML attribute strings. We’ve also enhanced UxmlObjects, allowing custom, non-visual elements to be defined within visual elementsA node of a visual tree that instantiates or derives from the C# VisualElement class. You can style the look, define the behaviour, and display it on screen as part of the UI. More info
See in Glossary. The new system leverages the Unity serialization and uses a source generator to create UxmlSerializedData classes for elements from all UxmlAttribute definitions for each custom element class, enabling support for custom property drawersA Unity feature that allows you to customize the look of certain controls in the Inspector window by using attributes on your scripts, or by controlling how a specific Serializable class should look More info
See in Glossary, decorators, and various attributes.
The introduction of “attribute overrides” allows you to customize the behavior of UXML attributes, and provides flexibility when you work with inherited attributes. These improvements provide a more efficient and user-friendly experience for creating complex UI elements in Unity 2023.2 and beyond.
For example, the following code sample is a custom control created with UxmlFactory and UxmlTraits:
public class HealthBar : VisualElement
{
private const float k_LowValue = 0;
private const float k_HighValue = 100;
// Declare as usable with Uxml
public new class UxmlFactory : UxmlFactory<HealthBar, UxmlTraits> { }
// Define attributes (and connect with class properties) for Uxml
public new class UxmlTraits : BindableElement.UxmlTraits
{
UxmlColorAttributeDescription m_Color = new UxmlColorAttributeDescription { name = "color", defaultValue = Color.white };
UxmlFloatAttributeDescription m_Value = new UxmlFloatAttributeDescription { name = "value", defaultValue = k_HighValue };
public override void Init(VisualElement ve, IUxmlAttributes bag, CreationContext cc)
{
base.Init(ve, bag, cc);
var bar = ve as HealthBar;
bar.color = m_Color.GetValueFromBag(bag, cc);
bar.value = m_Value.GetValueFromBag(bag, cc);
}
}
public Color color { get; set; }
[Range(k_LowValue, k_HighValue)]
public float value { get; set; }
}
The following code sample does the same thing as the previous code sample, but uses the new UxmlElement and UxmlAttributes system:
[UxmlElement]
public class HealthBar2 : VisualElement
{
private const float k_LowValue = 0;
private const float k_HighValue = 100;
[UxmlAttribute]
public Color color { get; set; } = Color.white;
[UxmlAttribute]
[Range(k_LowValue, k_HighValue)]
public float value { get; set; } = k_HighValue;
}
For more examples and information, refer to Unity UI Toolkit documentation, and stay tuned for an in-depth blog post this fall.
The Assets/Create menu has been reorganized and categorized. As part of this overhaul, the Unity Built-In ScriptTemplate files have been renamed.
Users who have added elements to the Assets/Create menu with either CreateAssetMenuAttribute``, MenuItemAttribute or a Custom ScriptTemplate might want to change their menu item’s priority as it’s placement relative to other elements is now different.
Users who were creating assets by executing these menu items with the EditorApplication.ExecuteMenuItem API, must verify the new path to the menu item.
Users who have previously overridden the Unity Built-In ScriptTemplates must update the names of their override files to ensure they match the new names of the Built-In Templates.
The ExecuteDefaultAction and ExecuteDefaultActionAtTarget methods have been deprecated. The following methods are added to replace them:
HandleEventTrickleDownHandleEventBubbleUpUnity executes these new methods on each element in the event dispatching path immediately after TrickleDown and before BubbleUp callbacks of that element. During those methods, the dispatching phase is set to TrickleDown or BubbleUp accordingly and the event’s `currentTarget`` coincides with the element executing the method.
The AtTarget dispatching phase and the PreventDefault method have been deprecated. Calling StopPropagation or StopPropagationImmediately now stops further executing HandleEventTrickleDown and HandleEventBubbleUp at the same time as it stops further invocation of the TrickleDown and `BubbleUp`` callbacks.
In most cases, if you don’t upgrade to the new methods, your code should not alter its behavior significantly. UI Tookkit still calls the obsolete methods in the same order as before, or with minimal adjustments. However, all the standard controls within UI Toolkit have migrated to using the new methods, aligning their logic execution order accordingly. Mixing calls to obsolete methods with the use of upgraded controls might lead to some logic being out of sync compared to previous Unity versions.
To upgrade existing code to the new methods, proceed as follows:
ExecuteDefaultAction and ExecuteDefaultActionAtTarget by HandleEventBubbleUp and PreventDefault by StopPropagation (or remove calls to PreventDefault if StopPropagation has already been called in the same code block. This covers the majority of cases).PreventDefault during a BubbleUp callback, which is no longer possible and can’t be replaced by StopPropagation because the event has already reached its target, consider adding a callback during the TrickleDown phase to call StopPropagation. This step is generally sufficient to address such scenarios.The cross compilation of Unity shadersA program that runs on the GPU. More info
See in Glossary to Metal shaders has changed with respect to buffer layouts. Any buffer that contains min16float, half or real types now have a different memory layout compared to previous versions of Unity.
You need to act only if you’re targeting Metal and using APIs that write raw data directly to buffers, for example:
You don’t need to act if you use only CommandBuffer.SetComputeFloatParam or Material.SetFloat.
More specifically, HLSL min16float, half and real inside buffers are always converted to 32-bit MSL float, whereas in previous Unity versions they could be converted to 16-bit MSL half, depending on the target platform.
If you have tested your shaders only on Metal platforms, check the buffers in the generated MSL code to ensure the layout matches the buffer data that’s accessed in C#. You can test whether this change impacts your shaders by adding #pragma metal_fxc_allow_float16_in_cpu_visible_buffers to your shader code and seeing if any visual artifact is fixed. If you notice a difference, remove this pragma and adjust your shader and C# code so that it works correctly without the pragma, to improve the cross-platform compatibility of your project.
To use native 16-bit floats in buffers, consider using the DXC HLSL compiler and adding #pragma require Native16Bit to your shader. But note that using DXC in Unity is still in an experimental stage.
The global package cache contains several subfolders. One of those subfolders, packages, is no longer used by the Package Manager.
You need to act only if you have automation scripts or pipelines that interact directly with the global package cache’s packages subfolder, for example, if you use the UPM_CACHE_PATH environment variable. If so, you can remove the references. Unity doesn’t offer a direct replacement subfolder for packages. Packages are now extracted directly to the project cache.
If you no longer maintain projects created with Unity 2023.2, you can safely delete the packages subdirectory from the global package cache root. This operation is optional.
Previous versions of the Unity Editor supported use of the UPM_CACHE_PATH environment variable to specify the absolute path to the location where you want the Package Manager to store the uncompressed contents of package tarballs.
You need to act only if you have automation scripts or pipelines that set path values in the UPM_CACHE_PATH. There’s no replacement for UPM_CACHE_PATH because packages are now extracted directly to the project cache. However, if you used to use UPM_CACHE_PATH, you can now use the UPM_CACHE_ROOT environment variable, which sets the root of the global cache. Note that the global cache root is the parent directory to the subfolder formerly associated with UPM_CACHE_PATH.
For more information, refer to Customize the global cache.
Unity has updated the default versions of the following tools used by Android. The default versions of NDK, SDK Command Line Tools, and SDK Tools remain unchanged. The updated versions are as follows:
| Tool | Version |
|---|---|
| Gradle | 8.4 |
| Android Gradle Plugin | 8.3.0 |
| SDK Build Tools | 34.0.0 |
| SDK Platform Tools | 34.0.5 |
| Java Development Kit (JDK) | 17 |
If your project uses custom gradle templates, consider recreating those templates to avoid any build issues with the updated Android Gradle Plugin version. For more information, refer to Modify Gradle project files with Gradle template files.
Previous Unity Editor versions included a 7-Zip fork that supported zstandard compressionA method of storing data that reduces the amount of storage space it requires. See Texture Compression, Animation Compression, Audio Compression, Build Compression.
See in Glossary:
Windows versions included 7-Zip-zstd, a fork of mcmilk/7-Zip-zstd which is a fork of upstream 7-Zip version 22.01. This code is vulnerable to several known security issues, such as CVE–2023–31102 and CVE–2023–40481.
macOS and Linux versions included p7zip-zstd, a fork of tehmul/p7zip-zstd (abandoned in 2017), which is a fork of p7zip (abandoned in 2016), which is a fork of upstream 7-Zip. This code is vulnerable to several known security issues, such as CVE–2016–7804, CVE–2017–17969, CVE–2018–10115, CVE–2018–10172, CVE–2018–5996, CVE–2023–31102 and CVE–2023–40481.
Unity 6 includes the regular upstream version 23.01 of 7-Zip for Windows, macOS, and Linux Editors. However, this upstream version of 7-Zip doesn’t support zstandard compression or decompression for .zip or .7z archives. It also lacks support for additional compression formats and hash algorithms added in the mcmilk/7-Zip-zstd fork.
If you have packages that use 7za or 7z.exe binaries that operate on archives using zstandard compression, use one of the following options: