Upgrade to Unity 6.5

Upgrade a project from Unity 6.4 to Unity 6.5.

Read time 13 minutes

Last updated 20 days ago

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):

2D
Editor and workflow
Graphics
Optimization
Platforms
Programming
XR

2D

This section outlines recent updates to Unity's 2D APIs that can affect your upgrade experience.

The new 2D physics API has a new name and namespace

The

LowLevelPhysics2D

API has the following changes:

The API has been renamed to
```
PhysicsCore2D
```
API.
The API has been moved from the
```
UnityEngine.LowLevelPhysics2D
```
namespace to the
```
Unity.U2D.Physics
```
namespace.
The
```
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.

Editor and workflow

This section outlines recent updates to the Unity Editor and its general workflows that can affect your upgrade experience.

Project-local Editor.log by default

Previously, Unity used a single global Editor log file for all projects stored at the following OS-specific locations:

Windows:
```
%LOCALAPPDATA%\Unity\Editor\Editor.log
```
macOS:
```
/Library/Logs/Unity/Editor.log
```
Linux:
```
/.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 scripts 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.

Graphics

This section outlines recent updates to graphics that can affect your upgrade experience.

Built-In Render Pipeline deprecation

The Built-In Render Pipeline 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:

Updated RequestLightsDelegate API

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 lights. 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;  }

Deprecated Reflection Probe Node

The Reflection Probe 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
```
: Vector3
```
Normal
```
: Vector3
```
LOD
```
: Float

In the Custom Function node, use the following shader code:


Out = SHADERGRAPH_REFLECTION_PROBE(ViewDir, Normal, LOD);

For more information, refer to the documentation on Reflection Probe Node.

Render Pipeline Core no longer depends on uGUI

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.

Removed legacy compiler from Render Graph codebase

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.

Rendering Debugger Editor UITK conversion

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.

Optimization

This section outlines recent updates to optimization that can affect your upgrade experience.

ModelImporter API deprecation

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`

Platforms

This section outlines recent updates to platform-specific tools and settings that can affect your upgrade experience.

Android

This section outlines recent updates to Android-specific tools and settings.

Unity Android adaptability improvements

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-insets
```
- ```
unity.system-bars-behavior
```

Gradle theme: Unity replaced the Gradle theme

android:Theme.Holo.Light.NoActionBar.Fullscreen

with

android:Theme.Holo.Light.NoActionBar

. Google deprecated the

.Fullscreen

variant.

Deprecated RequestToUseMobileDataAsync API

AndroidAssetPacks.RequestToUseMobileDataAsync

API is deprecated. Use the

AndroidAssetPacks.ShowConfirmationDialogAsync

API instead.

Raised Android minimum specification to 8.0

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-ins or dependencies, as raising the minimum API level can cause compatibility issues.

Removed support for x86-64

x86-64 target architecture support is completely removed for Android.

Updated Android build tools

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:

Custom Gradle templates are enabled in
Player Settings
?
> Publishing Settings or your project includes
```
mainTemplate.gradle
```
or
```
launcherTemplate.gradle
```
.
Your project uses older third-party plug-ins that are not updated for Gradle/AGP updates.

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, Analytics 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"

iOS

This section outlines recent updates to iOS-specific APIs.

Removed ReplayKit in Unity 6

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-in or use a third-party plug-in that provides equivalent functionality.

Programming

This section outlines recent updates to the Programming system that can affect your upgrade experience.

Base Class Library extensions

Unity’s internal Base Class Library has been extended by adding the following targeting packs:

```
System.Text.Json
```
```
System.Collections.Immutable
```
```
System.Reflection.Metadata
```
```
System.Runtime.CompilerServices.Unsafe
```

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

Removed obsolete InstanceID type and methods

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.

Increased EntityId size to 8 bytes

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:

Using
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.
Using serialized string values: If you serialized an
```
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.
Using reinterpret functions based on unsafe code: This includes structs using
```
[StructLayout(LayoutKind.Explicit)]
```
where an
```
EntityId
```
field overlaps with an
```
int
```
, or C# pointers that reinterpret cast between an
```
Int
```
and an
```
EntityId
```
pointer.

Removed obsolete Entities.ForEach and Aspects APIs

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.

Removed obsolete GameObject and Component APIs

Obsolete APIs for GameObject 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>()`

XR

This section outlines recent updates to XR that can affect your upgrade experience.

Removed VR Module from Unity 6.5

The VR Module has been removed. To learn about packages and templates for XR development, refer to XR.

Upgrade to Unity 6.5

2D

The new 2D physics API has a new name and namespace

Editor and workflow

Project-local Editor.log by default

Graphics

Built-In Render Pipeline deprecation

Updated RequestLightsDelegate API

Deprecated Reflection Probe Node

Render Pipeline Core no longer depends on uGUI

Removed legacy compiler from Render Graph codebase

Rendering Debugger Editor UITK conversion

Optimization

ModelImporter API deprecation

Removed API

Replacement API

Platforms

Android

Unity Android adaptability improvements

Deprecated RequestToUseMobileDataAsync API

Raised Android minimum specification to 8.0

Removed support for x86-64

Updated Android build tools

Tool

Previous version

Updated version

iOS

Removed ReplayKit in Unity 6

Programming

Base Class Library extensions

Removed obsolete InstanceID type and methods

Increased EntityId size to 8 bytes

Removed obsolete Entities.ForEach and Aspects APIs

Removed API

Replacement API

Removed obsolete GameObject and Component APIs

Removed API

Replacement API

XR

Removed VR Module from Unity 6.5

Additional resources