Attention: Here be dragons

This is the latest (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...

从 Godot 4.5 升级到 Godot 4.6

对于大多数使用 4.5 制作的游戏和应用程序来说，迁移到 4.6 应该相对安全。本页旨在介绍迁移项目时需要注意的所有事项。

破坏性更改

如果你要从 4.5 迁移到 4.6，这里列出的破坏性更改可能会影响到你。变更按领域/系统进行了分组。

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

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

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

核心

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
FileAccess
方法 create_temp 将 mode_flags 参数的类型从 int 更改为 FileAccess.ModeFlags	✔️	✔️	✔️	GH-114053
方法 get_as_text 移除了 skip_cr 参数	✔️	✔️	✔️	GH-110867
性能
方法 add_custom_monitor 新增了一个可选参数 type	✔️	✔️	✔️	GH-110433

动画

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
AnimationPlayer
属性 assigned_animation 的类型从 String 改为 StringName	✔️	❌	❌	GH-110767
属性 autoplay 类型从 String 改为 StringName	✔️	❌	❌	GH-110767
属性 current_animation 的类型从 String 改为 StringName	✔️	❌	❌	GH-110767
get_queue 方法的返回类型从 PackedStringArray 变为 StringName[]	✔️	❌	❌	GH-110767
信号 current_animation_changed 将参数 name 的类型从 String 变为 StringName	✔️	❌	❌	GH-110767

3D

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
SpringBoneSimulator3D
方法 get_end_bone_direction 的返回类型从 SpringBoneSimulator3D.BoneDirection 变为 SkeletonModifier3D.BoneDirection	✔️	❌	✔️	GH-110120
方法 get_joint_rotation_axis 的返回类型从 SpringBoneSimulator3D.RotationAxis 变为 SkeletonModifier3D.RotationAxis	✔️	❌	✔️	GH-110120
方法 get_rotation_axis 的返回类型从 SpringBoneSimulator3D.RotationAxis 变为 SkeletonModifier3D.RotationAxis	✔️	❌	✔️	GH-110120
方法 set_end_bone_direction 将参数 bone_direction 的类型从 SpringBoneSimulator3D.BoneDirection 变为 SkeletonModifier3D.BoneDirection	✔️	❌	✔️	GH-110120
方法 set_joint_rotation_axis 将参数 axis 的类型从 SpringBoneSimulator3D.RotationAxis 更改为 SkeletonModifier3D.RotationAxis	✔️	❌	✔️	GH-110120
方法 set_rotation_axis 将参数 axis 的类型从 SpringBoneSimulator3D.RotationAxis 更改为 SkeletonModifier3D.RotationAxis	✔️	❌	✔️	GH-110120

渲染

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
DisplayServer
方法 accessibility_create_sub_text_edit_elements 添加了一个新的可选参数 is_last_line	✔️	✔️	✔️	GH-113459
方法 tts_speak 将参数 utterance_id 的类型从 int32 更改为 int64	✔️	✔️	✔️	GH-112379

GUI 节点

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
Control
方法 grab_focus 添加了一个新的可选参数 hide_focus	✔️	✔️	✔️	GH-110250
方法 has_focus 添加了一个新的可选参数 ignore_hidden_focus	✔️	✔️	✔️	GH-110250
FileDialog
方法 add_filter 添加了一个新的可选参数 mime_type	✔️	✔️	✔️	GH-111439
LineEdit
方法 edit 添加了一个新的可选参数 hide_focus	✔️	✔️	✔️	GH-111117
SplitContainer
方法 clamp_split_offset 添加了一个新的可选参数 priority_index	✔️	✔️	✔️	GH-90411

网络

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
StreamPeerTCP
方法 disconnect_from_host 移至基类 StreamPeerSocket	✔️	✔️	✔️	GH-107954
方法 get_status 移至基类 StreamPeerSocket	✔️	❌	✔️	GH-107954
方法 poll 移至基类 StreamPeerSocket	✔️	✔️	✔️	GH-107954
TCPServer
方法 is_connection_available 移至基类 SocketServer	✔️	✔️	✔️	GH-107954
方法 is_listening 移至基类 SocketServer	✔️	✔️	✔️	GH-107954
方法 stop 移至基类 SocketServer	✔️	✔️	✔️	GH-107954

OpenXR

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
OpenXRExtensionWrapper
方法 _get_requested_extensions 添加了一个新的可选参数 xr_version	❌	❌	❌	GH-109302
方法 _set_instance_create_info_and_get_next_pointer 添加了一个新的可选参数 xr_version	N/A	N/A	N/A	GH-109302

备注

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

编辑器

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
EditorExportPreset
方法 get_script_export_mode 的返回类型从 int 变为 EditorExportPreset.ScriptExportMode	✔️	❌	❌	GH-107167
EditorFileDialog
方法 add_filter 移至基类 FileDialog	✔️	✔️	✔️	GH-111212
方法 add_option 移至基类 FileDialog	✔️	✔️	✔️	GH-111212
移除了 add_side_menu 方法	❌	❌	❌	GH-111162
方法 clear_filename_filter 移至基类 FileDialog	✔️	✔️	✔️	GH-111212
方法 clear_filters 移至基类 FileDialog	✔️	✔️	✔️	GH-111212
方法 get_filename_filter 移至基类 FileDialog	✔️	✔️	✔️	GH-111212
方法 get_line_edit 移至基类 FileDialog	✔️	✔️	✔️	GH-111212
方法 get_option_default 移至基类 FileDialog	✔️	✔️	✔️	GH-111212
方法 get_option_name 移至基类 FileDialog	✔️	✔️	✔️	GH-111212
方法 get_option_values 移至基类 FileDialog	✔️	✔️	✔️	GH-111212
方法 get_selected_options 移至基类 FileDialog	✔️	✔️	✔️	GH-111212
方法 get_vbox 移至基类 FileDialog	✔️	✔️	✔️	GH-111212
方法 invalidate 移至基类 FileDialog	✔️	✔️	✔️	GH-111212
方法 popup_file_dialog 移至基类 FileDialog	✔️	✔️	✔️	GH-111212
方法 set_filename_filter 移至基类 FileDialog	✔️	✔️	✔️	GH-111212
方法 set_option_default 移至基类 FileDialog	✔️	✔️	✔️	GH-111212
方法 set_option_name 移至基类 FileDialog	✔️	✔️	✔️	GH-111212
方法 set_option_values 移至基类 FileDialog	✔️	✔️	✔️	GH-111212
属性 access 移至基类 FileDialog	✔️	❌	✔️	GH-111212
属性 current_dir 移至基类 FileDialog	✔️	✔️	✔️	GH-111212
属性 current_file 移至基类 FileDialog	✔️	✔️	✔️	GH-111212
属性 current_path 移至基类 FileDialog	✔️	✔️	✔️	GH-111212
属性 display_mode 移动到基类 FileDialog	✔️	❌	✔️	GH-111212
属性 file_mode 移动到基类 FileDialog	✔️	❌	✔️	GH-111212
属性 filters 移至基类 FileDialog	✔️	✔️	✔️	GH-111212
属性 option_count 移动到基类 FileDialog	✔️	✔️	✔️	GH-111212
属性 show_hidden_files 移至基类 FileDialog	✔️	✔️	✔️	GH-111212
信号 dir_selected 移动到基类 FileDialog	✔️	❌	✔️	GH-111212
信号 filename_filter_changed 移动到基类 FileDialog	✔️	❌	✔️	GH-111212
信号 file_selected 移动到基类 FileDialog	✔️	❌	✔️	GH-111212
信号 files_selected 移动到基类 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 。

核心

备注

在 Godot 4.6 中，TSCN 文件格式 发生了两处改动：

• 场景文件中将不再写入 load_steps 属性（GH-103352）。因为这个属性编辑器实际上并没有用到。

• 现在，场景文件中会保存唯一的节点 ID，以便在节点被移动或重命名时进行追踪（GH-106837）。这让场景重构变得稳健（可靠）得多。

这些改动是向后兼容且向前兼容的。这意味着，在 Godot 4.5 中保存的场景依然可以在 Godot 4.6 中正常加载，反之亦然（当然，前提是场景本身没有进行其他不兼容的修改）。

因此，当你在 Godot 4.6 中保存一个上次在 Godot 4.5 里编辑过的场景时，版本控制软件（比如 Git）里会出现大量的差异（diffs）。这些差异是预期之内的正常现象。

温馨提醒一下，你可以在编辑器的菜单栏里点击 Project > Tools > Upgrade Project Files... （项目 > 工具 > 升级项目文件...），将项目中的所有文件一键升级到最新的格式，然后再把这些改动提交到版本控制系统中。这样做能让你在后续编辑场景时，避免出现大量不必要的差异（diffs）。

渲染

备注

Glow（辉光）的默认混合模式现在改成了 Screen（滤色）。这种模式看起来更自然、更准确，但会比之前的 Soft Light（柔光）模式明显亮得多（GH-110671）。

为了确保辉光效果不会变得过于强烈，官方还调整了其他几项辉光的默认参数。但即便如此，在升级引擎后，你很可能还是需要手动微调一下 Environment（环境）中的辉光属性。

此外，辉光（glow）的“柔光（Soft Light）”混合模式现在的表现将始终与之前开启 use_hdr_2d 时的表现保持一致，而不再受 Viewport（视口）的 use_hdr_2d 设置影响 (GH-109971)。

当使用 Mobile（移动端）渲染器时，出于性能优化的考虑，重写的辉光效果在视觉上会与之前的版本有显著差异（GH-110077）。你可能需要进一步调整 Environment（环境）中的辉光设置，才能达到和以前类似的视觉效果。

备注

体积雾的混合方式经过了调整，现在更加符合物理规律（GH-112494）。这会导致在大多数场景中，体积雾看起来会比以前更亮。

为了抵消这种影响，你需要降低 Environment（环境）中的体积雾密度或亮度，或者调低特定灯光上的 Volumetric Fog Energy （体积雾能量）属性。

导航

备注

现在，当 from_id 是一个禁用/实心点时， AStar2D.get_point_path 、 AStar3D.get_point_path 、 AStarGrid2D.get_id_path 和 AStarGrid2D.get_point_path 将返回一个空路径 (GH-113988)。

默认值更改

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

备注

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

备注

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

3D

成员	旧值	新值	引入
MeshInstance3D
属性 skeleton	NodePath("..")	NodePath("")	GH-112267

备注

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

渲染

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

GUI 节点

属性/参数	旧值	新值	引入
PopupMenu
属性 submenu_popup_delay	0.3	0.2	GH-110256
ResourceImporterCSVTranslation
属性 compress	true	1	GH-112073