Upgrading from Godot 4.5 to Godot 4.6

For most games and apps made with 4.5 it should be relatively safe to migrate to 4.6. This page intends to cover everything you need to pay attention to when migrating your project.

破坏性更改

If you are migrating from 4.5 to 4.6, the breaking changes listed here might affect you. Changes are grouped by areas/systems.

这篇文章指出了每项破坏性改动是否会影响 GDScript，以及 C# 的破坏性改动是 二进制兼容 还是 源代码兼容：

• 二进制兼容 — 现有可执行文件无需重新编译即可成功加载和执行，且运行时行为不会发生变化。

• 源代码兼容—— 在升级 Godot 时，源代码可成功编译，无需更改。

核心

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
FileAccess
Method create_temp changes mode_flags parameter type from int to FileAccess.ModeFlags	✔️	✔️	✔️	GH-114053
Method get_as_text removes skip_cr parameter	✔️	✔️	✔️	GH-110867
性能
Method add_custom_monitor adds a new type optional parameter	✔️	✔️	✔️	GH-110433

动画

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
AnimationPlayer
Property assigned_animation changes type from String to StringName	✔️	❌	❌	GH-110767
Property autoplay changes type from String to StringName	✔️	❌	❌	GH-110767
Property current_animation changes type from String to StringName	✔️	❌	❌	GH-110767
Method get_queue changes return type from PackedStringArray to StringName[]	✔️	❌	❌	GH-110767
Signal current_animation_changed changes name parameter type from String to StringName	✔️	❌	❌	GH-110767

3D

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
SpringBoneSimulator3D
Method get_end_bone_direction changes return type from SpringBoneSimulator3D.BoneDirection to SkeletonModifier3D.BoneDirection	✔️	❌	✔️	GH-110120
Method get_joint_rotation_axis changes return type from SpringBoneSimulator3D.RotationAxis to SkeletonModifier3D.RotationAxis	✔️	❌	✔️	GH-110120
Method get_rotation_axis changes return type from SpringBoneSimulator3D.RotationAxis to SkeletonModifier3D.RotationAxis	✔️	❌	✔️	GH-110120
Method set_end_bone_direction changes bone_direction parameter type from SpringBoneSimulator3D.BoneDirection to SkeletonModifier3D.BoneDirection	✔️	❌	✔️	GH-110120
Method set_joint_rotation_axis changes axis parameter type from SpringBoneSimulator3D.RotationAxis to SkeletonModifier3D.RotationAxis	✔️	❌	✔️	GH-110120
Method set_rotation_axis changes axis parameter type from SpringBoneSimulator3D.RotationAxis to SkeletonModifier3D.RotationAxis	✔️	❌	✔️	GH-110120

渲染

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
DisplayServer
Method accessibility_create_sub_text_edit_elements adds a new is_last_line optional parameter	✔️	✔️	✔️	GH-113459
Method tts_speak changes utterance_id parameter type metadata from int32 to int64	✔️	✔️	✔️	GH-112379

GUI 节点

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
Control
Method grab_focus adds a new hide_focus optional parameter	✔️	✔️	✔️	GH-110250
Method has_focus adds a new ignore_hidden_focus optional parameter	✔️	✔️	✔️	GH-110250
FileDialog
Method add_filter adds a new mime_type optional parameter	✔️	✔️	✔️	GH-111439
LineEdit
Method edit adds a new hide_focus optional parameter	✔️	✔️	✔️	GH-111117
SplitContainer
Method clamp_split_offset adds a new priority_index optional parameter	✔️	✔️	✔️	GH-90411

网络

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
StreamPeerTCP
Method disconnect_from_host moved to base class StreamPeerSocket	✔️	✔️	✔️	GH-107954
Method get_status moved to base class StreamPeerSocket	✔️	❌	✔️	GH-107954
Method poll moved to base class StreamPeerSocket	✔️	✔️	✔️	GH-107954
TCPServer
Method is_connection_available moved to base class SocketServer	✔️	✔️	✔️	GH-107954
Method is_listening moved to base class SocketServer	✔️	✔️	✔️	GH-107954
Method stop moved to base class SocketServer	✔️	✔️	✔️	GH-107954

OpenXR

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
OpenXRExtensionWrapper
Method _get_requested_extensions adds a new xr_version parameter	❌	❌	❌	GH-109302
Method _set_instance_create_info_and_get_next_pointer adds a new xr_version parameter	N/A	N/A	N/A	GH-109302

备注

OpenXRExtensionWrapper 类型旨在从 GDExtensions 中细分为子类。方法 _set_instance_create_info_and_get_next_pointer 有一个 void* 参数，所以不会暴露在脚本中。

编辑器

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
EditorExportPreset
Method get_script_export_mode changes return type from int to EditorExportPreset.ScriptExportMode	✔️	❌	❌	GH-107167
EditorFileDialog
Method add_filter moved to base class FileDialog	✔️	✔️	✔️	GH-111212
Method add_option moved to base class FileDialog	✔️	✔️	✔️	GH-111212
Method add_side_menu removed	|❌ 待兼容|	|❌ 待兼容|	|❌ 待兼容|	GH-111162
Method clear_filename_filter moved to base class FileDialog	✔️	✔️	✔️	GH-111212
Method clear_filters moved to base class FileDialog	✔️	✔️	✔️	GH-111212
Method get_filename_filter moved to base class FileDialog	✔️	✔️	✔️	GH-111212
Method get_line_edit moved to base class FileDialog	✔️	✔️	✔️	GH-111212
Method get_option_default moved to base class FileDialog	✔️	✔️	✔️	GH-111212
Method get_option_name moved to base class FileDialog	✔️	✔️	✔️	GH-111212
Method get_option_values moved to base class FileDialog	✔️	✔️	✔️	GH-111212
Method get_selected_options moved to base class FileDialog	✔️	✔️	✔️	GH-111212
Method get_vbox moved to base class FileDialog	✔️	✔️	✔️	GH-111212
Method invalidate moved to base class FileDialog	✔️	✔️	✔️	GH-111212
Method popup_file_dialog moved to base class FileDialog	✔️	✔️	✔️	GH-111212
Method set_filename_filter moved to base class FileDialog	✔️	✔️	✔️	GH-111212
Method set_option_default moved to base class FileDialog	✔️	✔️	✔️	GH-111212
Method set_option_name moved to base class FileDialog	✔️	✔️	✔️	GH-111212
Method set_option_values moved to base class FileDialog	✔️	✔️	✔️	GH-111212
Property access moved to base class FileDialog	✔️	❌	✔️	GH-111212
Property current_dir moved to base class FileDialog	✔️	✔️	✔️	GH-111212
Property current_file moved to base class FileDialog	✔️	✔️	✔️	GH-111212
Property current_path moved to base class FileDialog	✔️	✔️	✔️	GH-111212
Property display_mode moved to base class FileDialog	✔️	❌	✔️	GH-111212
Property file_mode moved to base class FileDialog	✔️	❌	✔️	GH-111212
Property filters moved to base class FileDialog	✔️	✔️	✔️	GH-111212
Property option_count moved to base class FileDialog	✔️	✔️	✔️	GH-111212
Property show_hidden_files moved to base class FileDialog	✔️	✔️	✔️	GH-111212
Signal dir_selected moved to base class FileDialog	✔️	❌	✔️	GH-111212
Signal filename_filter_changed moved to base class FileDialog	✔️	❌	✔️	GH-111212
Signal file_selected moved to base class FileDialog	✔️	❌	✔️	GH-111212
Signal files_selected moved to base class FileDialog	✔️	❌	✔️	GH-111212

行为更改

Android

备注

Android 导出模板的源集配置已更新，以匹配默认的 Android Studio 项目结构（ GH-110829 ）。这会影响 Android 项目的目录布局：

• 之前位于 [项目根目录]/android/build/src/ 中的文件现在位于 [项目根目录]/android/build/src/main/java/ 中。

• Android 清单文件和资产目录已移至 src/main/ 子目录。

例如， GodotApp.java 从 src/com/godot/game/GodotApp.java 移动到了 src/main/java/com/godot/game/GodotApp.java 。

渲染

备注

现在，无论视口的 use_hdr_2d 设置如何，柔光混合模式的行为始终与以前使用 use_hdr_2d 时的行为相同（ GH-109971 ）。

导航

备注

AStar2D.get_point_path, AStar3D.get_point_path, AStarGrid2D.get_id_path and AStarGrid2D.get_point_path will now return an empty path when from_id is a disabled/solid point (GH-113988).

Changed defaults

以下默认值已更改 。如果你的项目依赖于之前的默认值，则可能需要将其显式设置为旧的值。

备注

Windows 系统上 新建 项目的默认渲染驱动程序现在是 D3D12 (GH-113213)。可以在项目设置的 rendering/rendering_device/driver.windows 下更改此设置。

备注

新建项目 的默认 3D 物理引擎现在是 Jolt Physics ( GH-105737 )。可以在项目设置的 physics/3d/physics_engine 下更改此设置。

3D

Member	Old Value	New Value	引入
MeshInstance3D
Property skeleton	NodePath("..")	NodePath("")	GH-112267

备注

骨骼 的默认值已更改 。如果为实现兼容性需要旧的行为 ，请在项目设置中启用 animation/ compatibility /default_parent_skeleton_in_mesh_instance_3d 。

渲染

Member	Old Value	New Value	引入
ProjectSettings
属性 rendering/reflections/sky_reflections/roughness_layers	8	7	GH-107902
属性 rendering/rendering_device/d3d12/agility_sdk_version	613	618	GH-114043
Environment
Property glow_blend_mode	2	1	GH-110671
Property glow_intensity	0.8	0.3	GH-110671
Property glow_levels/2	0.0	0.8	GH-110671
Property glow_levels/3	1.0	0.4	GH-110671
Property glow_levels/4	0.0	0.1	GH-110671
Property glow_levels/5	1.0	0.0	GH-110671
属性 ssr_depth_tolerance	0.2	0.5	GH-111210

GUI 节点

Property/Parameter	Old Value	New Value	引入
PopupMenu
Property submenu_popup_delay	0.3	0.2	GH-110256
ResourceImporterCSVTranslation
属性 compress	true	1	GH-112073