Attention: Here be dragons
This is thelatest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
Upgrading from Godot 4.4 to Godot 4.5
For most games and apps made with 4.4 it should be relatively safe to migrate to 4.5.This page intends to cover everything you need to pay attention to when migratingyour project.
Breaking changes
If you are migrating from 4.4 to 4.5, the breaking changes listed here mightaffect you. Changes are grouped by areas/systems.
Warning
In order to supportnew Google Play requirements Android now requirestargeting .NET 9 when exporting C# projects to Android, other platformscontinue to use .NET 8 as the minimum required version but newer versionsare supported and encouraged.
If you are using C# in your project and want to export to Android, you willneed to upgrade your project to .NET 9 (seeUpgrading to a new .NET versionfor instructions).
This article indicates whether each breaking change affects GDScript and whetherthe C# breaking change isbinary compatible orsource compatible:
Binary compatible - Existing binaries will load and execute successfully withoutrecompilation, and the run-time behavior won't change.
Source compatible - Source code will compile successfully without changes whenupgrading Godot.
Core
Change | GDScript Compatible | C# Binary Compatible | C# Source Compatible | Introduced |
|---|---|---|---|---|
JSONRPC | ||||
Method | ||||
Node | ||||
Method | ||||
Method |
Rendering
Change | GDScript Compatible | C# Binary Compatible | C# Source Compatible | Introduced |
|---|---|---|---|---|
DisplayServer | ||||
Method | ||||
Method | ||||
RenderingDevice | ||||
Method | ||||
RenderingServer | ||||
Method | ||||
Method |
Note
In C#, the enumRenderingDevice.Features breaks compatibility because of the way the bindings generatordetects the enum prefix. New members were added to the enum inGH-103941 that caused the enum memberAddress to be renamed toBufferDeviceAddress.
GLTF
Change | GDScript Compatible | C# Binary Compatible | C# Source Compatible | Introduced |
|---|---|---|---|---|
GLTFAccessor | ||||
Property | ||||
Property | ||||
Property | ||||
Property | ||||
Property | ||||
Property | ||||
Property | ||||
GLTFBufferView | ||||
Property | ||||
Property | ||||
Property |
Note
As a result of changing the type metadata, the C# bindings changed the type fromint (32-bytes) tolong (64-bytes).
Text
Change | GDScript Compatible | C# Binary Compatible | C# Source Compatible | Introduced |
|---|---|---|---|---|
CanvasItem | ||||
Method | ||||
Method | ||||
Method | ||||
Method | ||||
Method | ||||
Method | ||||
Font | ||||
Method | ||||
Method | ||||
Method | ||||
Method | ||||
Method | ||||
Method | ||||
RichTextLabel | ||||
Method | ||||
Method | ||||
Method | ||||
Method | ||||
Method | ||||
Method | ||||
TextLine | ||||
Method | ||||
Method | ||||
TextParagraph | ||||
Method | ||||
Method | ||||
Method | ||||
Method | ||||
Method | ||||
Method | ||||
TextServer | ||||
Method | ||||
Method | ||||
Method | ||||
Method | ||||
TreeItem | ||||
Method | ||||
TextServerExtension | ||||
Method | ||||
Method | ||||
Method | ||||
Method |
XR
Change | GDScript Compatible | C# Binary Compatible | C# Source Compatible | Introduced |
|---|---|---|---|---|
OpenXRAPIExtension | ||||
Method | ||||
Method | ||||
Method | ||||
Method | ||||
OpenXRBindingModifierEditor | ||||
Type | ||||
OpenXRInteractionProfileEditor | ||||
Type | ||||
OpenXRInteractionProfileEditorBase | ||||
Type |
Note
ClassesOpenXRBindingModifierEditor,OpenXRInteractionProfileEditor, andOpenXRInteractionProfileEditorBaseare only available in the editor. Using them outside of the editor will result in a compilation error.
In C#, this means the types are moved from theGodotSharp assembly to theGodotSharpEditor assembly.Make sure to wrap code that uses these types in a#ifTOOLS block to ensure they are not included in an exported game.
This change was also backported to 4.4.1.
Editor plugins
Change | GDScript Compatible | C# Binary Compatible | C# Source Compatible | Introduced |
|---|---|---|---|---|
EditorExportPlatform | ||||
Method | ||||
EditorUndoRedoManager | ||||
Method | ||||
EditorExportPlatformExtension | ||||
Method |
Behavior changes
In 4.5, some behavior changes have been introduced, which might require you to adjust your project.
TileMapLayer
TileMapLayer.get_coords_for_body_rid()will return different values in 4.5 compared to 4.4,as TileMapLayer physics chunking is enabled by default. Higher values ofTileMapLayer.physics_quadrant_sizewill make this function less precise. To get the exact cell coordinates like in 4.4 and priorversions, you need to setTileMapLayer.physics_quadrant_sizeto1, which disables physics chunking.
3D Model Import
A fix has been made to the 3D model importers to correctly handle non-joint nodes within a skeleton hierarchy (GH-104184).To preserve compatibility, the default behavior is to import existing files with the same behavior as before (GH-107352).New.gltf,.glb,.blend, and.fbx files (without a corresponding.import file)will be imported with the new behavior. However, for existing files, if you want to use thenew behavior, you must change the "Naming Version" option at the bottom of the Import dock:
Core
Note
Resource.duplicate(true) (which performsdeep duplication) now only duplicates resources internal to the resource fileit's called on. In 4.4, this duplicated everything instead, including external resources.If you were deep-duplicating a resource that contained references to otherexternal resources, those external resources aren't duplicated anymore. You must callResource.duplicate_deep(RESOURCE_DEEP_DUPLICATE_ALL)instead to keep the old behavior.
Note
ProjectSettings.add_property_info()now prints a warning when the dictionary parameter has missing keys or invalid keys.Most importantly, it will now warn when ausage key is passed, as this key is not used.This was also the case before 4.5, but it was silently ignored instead.As a reminder, to set property usage information correctly, you must useProjectSettings.set_as_basic(),ProjectSettings.set_restart_if_changed(),orProjectSettings.set_as_internal() instead.
Note
In C#,StringExtensions.PathJoin now avoids adding an extra path separator when the original string is empty,or when the appended path starts with a path separator (GH-105281).
Note
In C#,StringExtensions.GetExtension now returns an empty string instead of the original stringwhen the original string does not contain an extension (GH-108041).
Note
In C#, theQuaternion(Vector3,Vector3) constructor now correctly creates a quaternion representingthe shortest arc between the two input vectors. Previously, it would return incorrect values for certain inputs(GH-107618).
Navigation
Note
By default, the regions in a NavigationServer map now update asynchronously using threads to improve performance.This can cause additional delay in the update due to thread synchronisation.The asynchronous region update can be toggled with thenavigation/world/region_use_async_iterations project setting.
Note
The merging of navmeshes in the NavigationServer has changed processing order. Regions now merge and cacheinternal navmeshes first, then the remaining free edges are merged by the navigation map.If a project had navigation map synchronisation errors before, it might now have shiftedaffected edges, making already existing errors in a layout more noticeable in the pathfinding.Thenavigation/2d_or_3d/merge_rasterizer_cell_scale project setting can be set to a lower valueto increase the detail of the rasterization grid (with0.01 being the smallest cell size possible).If edge merge errors still persist with the lowest possible rasterization scale value,the error may be caused by overlap: two navmeshes are stacked on top of each other, causing geometry conflict.
Physics
Note
When the 3D physics engine is set to Jolt Physics, you will now always have overlaps betweenArea3D and staticbodies reported by default, as thephysics/jolt_physics_3d/simulation/areas_detect_static_bodies project settinghas been removed (GH-105746). If you still want such overlaps to be ignored, you will need to change the collision maskor layer of either theArea3D or the static body instead.
Text
Note
In GDScript, calls to functionsRichTextLabel::add_image andRichTextLabel::update_image will continue to work,but thesize_in_percent argument will now be used as the value forwidth_in_percent andheight_in_percentwill default tofalse (GH-107347). To restore the previous behavior, you can explicitly setheight_in_percentto the same value you were passing assize_in_percent.