This page lists changes in Unity 6.5 (6000.5) in these areas that can affect existing projects when you upgrade from Unity 6.4 (6000.4) to Unity 6.5 (6000.5):
This section outlines recent updates to Unity’s 2D APIs that can affect your upgrade experience.
The LowLevelPhysics2D API has the following changes:
PhysicsCore2D API.UnityEngine.LowLevelPhysics2D namespace to the Unity.U2D.Physics namespace.PhysicsLowLevelSettings2D asset has been renamed the Physics Core Settings 2D asset. For more information, refer to Configure global Physics Core 2D API settings.Unity automatically migrates a 6.3 or 6.4 project to the new namespace when you open it in Unity 6.5.
The underlying types remain unchanged, guaranteeing full backward compatibility. To maintain compatibility with the older namespace in source files, use the UNITY_6000_5_OR_NEWER macro. For example:
#if UNITY_6000_5_OR_NEWER
using Unity.U2D.Physics;
#else
using UnityEngine.LowLevelPhysics2D;
#endif
The new Physics Core 2D built-in module, available via the Package Manager, includes new physics features. If you don’t need the older Physics 2D module, disable it to reduce memory and build size.
For more information, refer to 2D physics with the Physics Core 2D API.
This section outlines recent updates to the Unity Editor and its general workflows that can affect your upgrade experience.
Previously, Unity used a single global Editor log file for all projects stored at the following OS-specific locations:
%LOCALAPPDATA%\Unity\Editor\Editor.log
/Library/Logs/Unity/Editor.log
/.config/unity3d/Editor.log
By default, Unity now writes Editor log messages to a dedicated project-specific log file at ProjectName/Logs/Editor.log in the project’s folder.
You might have 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 or automation that need updating to account for this change. For example, those that retrieve the log file as a CI/CD artifact. For scripts within Unity, use Application.consoleLogPath to retrieve the log file path instead of hard-coding it. For scripts outside of Unity, pass the -logFile command-line argument to the Editor on launch.
To restore the previous default behavior instead and make all projects write to the same global Editor log file, enable the Use Global Editor Log setting in the Preferences window or pass the -useGlobalLog Editor command-line argument. Unity recommends to use the default project-local Editor log as it provides greater clarity and easier debugging, especially if you regularly switch between projects.
For more information, refer to Log files reference.
This section outlines recent updates to graphics that can affect your upgrade experience.
The Built-In Render PipelineA series of operations that take the contents of a Scene, and displays them on a screen. Unity lets you choose from pre-built render pipelines, or write your own. More info
See in Glossary is deprecated and will be made obsolete in a future release. It remains supported, including bug fixes and maintenance, through the full Unity 6.7 LTS lifecycle.
For more information, refer to:
The internal contract for LightBaker has been modified to correct a long-standing inconsistency in intensity between punctual and area light sources. For historical reasons, punctual light sources in the Unity Engine render too bright by a factor of 𝝅. This change is internal and only fixes the inconsistency within the scope of the LightBaker library. It preserves the Editor and Engine light intensities for both real-time and baked lightsLight components whose Mode property is set to Baked. Unity pre-calculates the illumination from Baked Lights before runtime, and does not include them in any runtime lighting calculations. More info
See in Glossary. If you haven’t modified the baking code, the change is transparent and no action is required. However, if you use a custom RequestLightsDelegate, you need to update your code.
To adapt your custom delegate and maintain correct lighting behavior with Unity 6.5, you must apply a 𝝅 correction factor to the intensity of punctual lights returned by the delegate.
You can do so by adding the following code snippet to the end of your custom delegate implementation:
for (int i = 0; i < requests.Length; i++)
{
if (lightsOutput[i].type != Experimental.GlobalIllumination.LightType.Directional
&& lightsOutput[i].type != Experimental.GlobalIllumination.LightType.Point
&& lightsOutput[i].type != Experimental.GlobalIllumination.LightType.Spot)
continue;
var tmp = lightsOutput[i];
tmp.color.intensity *= Mathf.PI;
tmp.indirectColor.intensity *= Mathf.PI;
lightsOutput[i] = tmp;
}
The 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 Node is deprecated as it isn’t supported correctly on all render pipelines, including HDRP and URP’s Forward+ and Deferred+ render paths.
If your project uses URP’s Forward or Deferred render paths, use a Custom Function Node with the following inputs:
ViewDir: Vector3Normal: Vector3LOD: FloatIn the Custom Function node, use the following shaderA program that runs on the GPU. More info
See in Glossary code:
Out = SHADERGRAPH_REFLECTION_PROBE(ViewDir, Normal, LOD);
For more information, refer to the documentation on Reflection Probe Node.
Unity removed the dependency on the com.unity.ugui package from the com.unity.render-pipelines.core package. If your project relies on uGUI indirectly through the Render Pipeline Core, Universal Render Pipeline, or High Definition Render Pipeline, add the com.unity.ugui package to your project through the Package Manager.
The legacy Render Graph API is now obsolete. Existing URP and HDRP projects that use the new Render Graph API with native render pass support are not affected. This change only affects projects with custom SRPs that still use the legacy Render Graph API. For such projects, use the Render Graph API with native render pass support.
The Rendering Debugger now uses UI Toolkit instead of uGUI and IMGUI. Unity also removed the classes that support uGUI-based custom controls for the debugger. Those APIs were public, but they were not practical to use without forking the Render Pipeline Core package.
If you use the DebugUI API to add custom controls to the Rendering Debugger, this change doesn’t affect your workflow. However, if your custom control needs to store state across domain reloads, Unity recommends you to update your code to use the new ISerializedDebugDisplaySettings based API, which is available in this release. The old DebugState state serialization system will be removed in 6.6.
This section outlines recent updates to optimization that can affect your upgrade experience.
Some obsolete ModelImporter APIs now cause compilation errors if used. These APIs have been obsolete with warnings for some time, and a replacement API exists for each one. Unity automatically upgrades most affected code, but in some cases manual action will be needed. Follow the instructions provided in the error messages to resolve the issues manually.
The following ModelImporter APIs are affected:
| Removed API | Replacement API |
|---|---|
isFileScaleUsed |
useFileScale |
normalImportMode |
importNormals |
optimizeMesh |
optimizeMeshPolygons and/or optimizeMeshVertices
|
resampleRotations |
resampleCurves |
splitTangentsAcrossSeams |
tangentImportMode |
tangentImportMode |
importTangents |
This section outlines recent updates to platform-specific tools and settings that can affect your upgrade experience.
This section outlines recent updates to Android-specific tools and settings.
The following changes affect how your project handles edge-to-edge support, safe area, and system bar visibility on Android:
API updates:
PlayerSettings.Android.renderOutsideSafeArea: Previously, this property controlled the status bar visibility and cutout rendering mode. It now only controls cutout rendering mode. To control the status bar visibility, use the PlayerSettings.Android.requestedVisibleInsets API.
Screen.fullScreen: Previously, this property controlled navigation bar visibility. It no longer has an effect on Android. To control status and navigation bar visibility, use the AndroidApplication.currentWindowInsets.Show or AndroidApplication.currentWindowInsets.Hide APIs.
PlayerSettings.Android.startInFullscreen:
This property is obsolete. Use the PlayerSettings.Android.requestedVisibleWindowInsets instead.
Configuration updates:
Android Manifest: Unity removed the unity.launch-fullscreen manifest entry. Use the following entries to control insets and their behavior:
unity.requested-visible-insetsunity.system-bars-behavior
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 theme: Unity replaced the Gradle theme android:Theme.Holo.Light.NoActionBar.Fullscreen with android:Theme.Holo.Light.NoActionBar. Google deprecated the .Fullscreen variant.
AndroidAssetPacks.RequestToUseMobileDataAsync API is deprecated. Use the AndroidAssetPacks.ShowConfirmationDialogAsync API instead.
The minimum supported Android API level is now 26 (Android 8.0 Oreo).
If your project uses Android API levels 23 to 25, you receive a warning in the Console, but the project build will not fail yet. Update your project to API level 26 as soon as possible and verify any third-party plug-insA set of code created outside of Unity that creates functionality in Unity. There are two kinds of plug-ins you can use in Unity: Managed plug-ins (managed .NET assemblies created with tools like Visual Studio) and Native plug-ins (platform-specific native code libraries). More info
See in Glossary or dependencies, as raising the minimum API level can cause compatibility issues.
x86–64 target architecture support is completely removed for Android.
Android build tooling versions for Gradle and Android Gradle Plugin (AGP) are updated to ensure compatibility with the latest Android development tools. The updated versions are as follows:
| Tool | Previous version | Updated version |
|---|---|---|
| Gradle | 8.13 | 9.1.0 |
| AGP | 8.10.0 | 9.0.0 |
For an overview of the changes these updates introduce, refer to the What’s new in Unity 6.5.
Unity automatically applies this update in most projects. You might need to make manual changes if any of the following apply:
mainTemplate.gradle or launcherTemplate.gradle.To ensure a smooth transition, take the following actions, where applicable:
If you have Custom Gradle Template enabled, review your .gradle files for deprecated attributes. Unity displays a dialog on build when any deprecated attributes are detected and automatically renames them to use their newer versions.
Check for updates from third-party SDK providers, such as for Ads, AnalyticsAbbreviation of Unity Analytics
See in Glossary to ensure they support AGP 9.0.
For projects with custom logic in .gradle templates, make sure to review the deprecated APIs listed in the official AGP release notes.
Configure unique namespaces for any custom Android plug-ins or libraries in your project. Set the namespace in either:
AndroidManifest.xml: package=“com.example.library.unique”Build.gradle: namespace “com.example.library.unique”This section outlines recent updates to iOS-specific APIs.
The ReplayKit API is now obsolete. This API was supported only on the iOS platform. Unity projects that still require ReplayKit functionality must implement it through an iOS native plug-inA platform-specific native code library that is created outside of Unity for use in Unity. Allows you can access features like OS calls and third-party code libraries that would otherwise not be available to Unity. More info
See in Glossary or use a third-party plug-in that provides equivalent functionality.
This section outlines recent updates to the Programming system that can affect your upgrade experience.
Unity’s internal Base Class Library has been extended by adding the following targeting packs:
System.Text.JsonSystem.Collections.ImmutableSystem.Reflection.MetadataSystem.Runtime.CompilerServices.UnsafeThese assemblies are now provided directly by Unity. If your project (or any of its dependencies) already reference any of these packages, Unity resolves to the internal version that ships with the Engine and any user-supplied copy is dropped from the build. This applies even if the version you reference differs from Unity’s. Two versions of the same package cannot co-exist in the same load context, and Unity must use its own version to guarantee Engine functionality.
InstanceID has been replaced with EntityId type. As a result, a large number of InstanceID APIs have been marked obsolete and will cause errors if used.
To upgrade your project to Unity 6.5, replace all usages of the obsolete InstanceID APIs with the corresponding EntityId version. In most cases, the obsolete error at each call site will point you to the replacement API.
One scenario that might require additional change is code that stores an InstanceID as an int, for example: int instanceID = go.GetInstanceID();. When upgrading to 6.5 change this to: EntityId entityId = go.GetEntityId();. If the surrounding code expects this id to fit into an int, further changes will be needed, as EntityId is now 8 bytes. For more information on this scenario, refer to the next section.
EntityId (formerly known as InstanceId) is now 8 bytes. If you do not update your code to 64 bits, you discard half of the data needed for valid EntityIds. For example, when you call EntityId myEntityId = myObject.GetEntityId(), and then later call Resources.EntityIdToObject(myEntityId), and a downcast occurred between the calls, Unity displays the following error:
Unexpected EntityId(23123:3735928559) version value: 3735928559. Did you accidentally downcast the EntityId and upcast it afterwards, losing the version number? (be careful of EntityId.FromULong/Entity.ToULong and especially parsing EntityId.ToString back to an EntityId.).
This error can occur in the following scenarios:
EntityId.FromULong((ulong)myIntInstanceId): The most common case is variables still named InstanceId that are stored as an int. In such cases, update them to use the EntityId type throughout including as dictionary keys. Do not use EntityId.GetHashCode() as a dictionary key.EntityId using EntityId.ToString() in Unity 6.2–6.4, the value was stored as 32-bit. In Unity 6.5, it is stored as 64-bit ulong. If you then use EntityId.FromULong(int.Parse(myEntityIdString)) to get it back as an EntityId, it will convert the int to ulong, and information will be lost in the same way as the previous example.[StructLayout(LayoutKind.Explicit)] where an EntityId field overlaps with an int, or C# pointers that reinterpret cast between an Int and an EntityId pointer.
Entities.ForEach, Job.WithCode, and IAspect have been deprecated for multiple Entities releases and are removed to simplify the Entities API surface and improve iteration time. These features relied heavily on source generation. Use the following replacement APIs:
| Removed API | Replacement API |
|---|---|
Entities.ForEach |
IJobEntity and SystemAPI.Query
|
Job.WithCode |
IJob |
IAspect |
Component and EntityQuery APIs instead of Aspects. |
For more information and upgrade instructions, refer to the Upgrade Guide in the Entities documentation.
Obsolete APIs for GameObjectThe 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 and Component (which MonoBehaviours inherit from) are removed. These APIs have been marked obsolete (with an error) for a long time. If your code contains any of these APIs, the following table lists the removed APIs and their replacement.
| Removed API | Replacement API |
|---|---|
GameObject.SampleAnimation(AnimationClip, float) |
AnimationClip.SampleAnimation(GameObject, float) |
GameObject.AddComponent(string) |
GameObject.AddComponent<T>() |
GameObject.rigidbody2D |
GameObject.GetComponent<Rigidbody2D>() |
GameObject.rigidbody |
GameObject.GetComponent<Rigidbody>() |
GameObject.camera |
GameObject.GetComponent<Camera>() |
GameObject.light |
GameObject.GetComponent<Light>() |
GameObject.animation |
GameObject.GetComponent<Animation>() |
GameObject.constantForce |
GameObject.GetComponent<ConstantForce>() |
GameObject.renderer |
GameObject.GetComponent<Renderer>() |
GameObject.audio |
GameObject.GetComponent<AudioSource>() |
GameObject.networkView |
GameObject.GetComponent<NetworkView>() |
GameObject.collider |
GameObject.GetComponent<Collider>() |
GameObject.collider2d |
GameObject.GetComponent<Collider2D>() |
GameObject.hingeJoint |
GameObject.GetComponent<HingeJoint>() |
GameObject.particleSystem |
GameObject.GetComponent<ParticleSystem>() |
GameObject.PlayAnimation(UnityEngine.Object) |
animation.Play() |
GameObject.StopAnimation() |
animation.Stop() |
Component.rigidbody2D |
GetComponent<Rigidbody2D>() |
Component.rigidbody |
GetComponent<Rigidbody>() |
Component.camera |
GetComponent<Camera>() |
Component.light |
GetComponent<Light>() |
Component.animation |
GetComponent<Animation>() |
Component.constantForce |
GetComponent<ConstantForce>() |
Component.renderer |
GetComponent<Renderer>() |
Component.audio |
GetComponent<AudioSource>() |
Component.networkView |
GetComponent<NetworkView>() |
Component.collider |
GetComponent<Collider>() |
Component.collider2d |
GetComponent<Collider2D>() |
Component.hingeJoint |
GetComponent<HingeJoint>() |
Component.particleSystem |
GetComponent<ParticleSystem>() |
This section outlines recent updates to XR that can affect your upgrade experience.
The VRVirtual Reality More info
See in Glossary Module has been removed. To learn about packages and templates for XR development, refer to XR.