从 Godot 4.4 升级到 Godot 4.5

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

破坏性更改

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

警告

为支持 新的 Google Play 要求，现在在将 C# 项目导出到 Android 平台时，必须以 .NET 9 为目标框架；其他平台仍以 .NET 8 作为最低要求版本，但鼓励使用并支持更新的版本。

如果你在项目中使用了 C# 并希望导出到 Android 平台，则需要将项目升级至 .NET 9（升级方法请参阅 Upgrading to a new .NET version）。

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

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

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

核心

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
JSONRPC
Method set_scope replaced by set_method	❌	|❌ 待兼容|	|❌ 待兼容|	GH-104890
节点
方法 get_rpc_config 更名为 get_node_rpc_config	❌	✔️	✔️	GH-106848
方法 set_name 将 name 的参数类型从 String 更改为 StringName	✔️	✔️	✔️	GH-76560

渲染

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
DisplayServer
方法 file_dialog_show 添加了一个新的可选参数 parent_window_id	✔️	✔️	✔️	GH-98194
方法 file_dialog_with_options_show 添加了一个新的可选参数 parent_window_id	✔️	✔️	✔️	GH-98194
RenderingDevice
方法 texture_create_from_extension 添加了一个新的可选参数 mipmaps	✔️	✔️	✔️	GH-105570
RenderingServer
方法 instance_reset_physics_interpolation 已被移除	❌	✔️	✔️	GH-104269
方法 instance_set_interpolated 已被移除	❌	✔️	✔️	GH-104269

备注

In C#, the enum RenderingDevice.Features breaks compatibility because of the way the bindings generator detects the enum prefix. New members were added to the enum in GH-103941 that caused the enum member Address to be renamed to BufferDeviceAddress.

GLTF

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
GLTFAccessor
属性 byte_offset 的类型元数据从 int32 改为 int64	✔️	❌	❌	GH-106220
属性 component_type 的类型从 int 改为 GLTFAccessor::GLTFComponentType	✔️	❌	❌	GH-106220
属性 count 的类型元数据从 int32 改为 int64	✔️	❌	❌	GH-106220
属性 sparse_count 的类型从 int32 改为 int64	✔️	❌	❌	GH-106220
属性 sparse_indices_byte_offset 的类型元数据从 int32 改为 int64	✔️	❌	❌	GH-106220
属性 sparse_indices_component_type 的类型从 int 改为 GLTFAccessor::GLTFComponentType	✔️	❌	❌	GH-106220
属性 sparse_values_byte_offset 的类型元数据从 int32 改为 int64	✔️	❌	❌	GH-106220
GLTFBufferView
属性 byte_length 的类型元数据从 int32 改为 int64	✔️	❌	❌	GH-106220
属性 byte_offset 的类型元数据从 int32 改为 int64	✔️	❌	❌	GH-106220
属性 byte_stride 的类型元数据从 int32 改为 int64	✔️	❌	❌	GH-106220

备注

由于类型元数据的变更，C# 绑定将该类型从 int（32 位）已更改为 long（64 位）。

文本

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
CanvasItem
方法 draw_char 添加了一个新的可选参数 oversampling	✔️	✔️	✔️	GH-104872
方法 draw_char_outline 添加了一个新的可选参数 oversampling	✔️	✔️	✔️	GH-104872
方法 draw_multiline_string 添加了一个新的可选参数 oversampling	✔️	✔️	✔️	GH-104872
方法 draw_multiline_string_outline 添加了一个新的可选参数 oversampling	✔️	✔️	✔️	GH-104872
方法 draw_string 添加了一个新的可选参数 oversampling	✔️	✔️	✔️	GH-104872
方法 draw_string_outline 添加了一个新的可选参数 oversampling	✔️	✔️	✔️	GH-104872
字体
方法 draw_char 添加了一个新的可选参数 oversampling	✔️	✔️	✔️	GH-104872
方法 draw_char_outline 添加了一个新的可选参数 oversampling	✔️	✔️	✔️	GH-104872
方法 draw_multiline_string 添加了一个新的可选参数 oversampling	✔️	✔️	✔️	GH-104872
方法 draw_multiline_string_outline 添加了一个新的可选参数 oversampling	✔️	✔️	✔️	GH-104872
方法 draw_string 添加了一个新的可选参数 oversampling	✔️	✔️	✔️	GH-104872
方法 draw_string_outline 添加了一个新的可选参数 oversampling	✔️	✔️	✔️	GH-104872
RichTextLabel
方法 add_image 添加了一个新的可选参数 alt_text	✔️	✔️	✔️	GH-76829
方法 add_image 将参数 size_in_percent 替换为 width_in_percent 和 height_in_percent	✔️	✔️	✔️	GH-107347
方法 push_strikethrough 添加了一个新的可选参数 color	✔️	✔️	✔️	GH-106300
方法 push_table 添加了一个新的可选参数 name	✔️	✔️	✔️	GH-76829
方法 push_underline 添加了一个新的可选参数 color	✔️	✔️	✔️	GH-106300
方法 update_image 将参数 size_in_percent 替换为 width_in_percent 和 height_in_percent	✔️	✔️	✔️	GH-107347
TextLine
方法 draw 新增了一个可选参数 过采样	✔️	✔️	✔️	GH-104872
方法 draw_outline 新增了一个参数``过采样``	✔️	✔️	✔️	GH-104872
TextParagraph
方法 draw 新增了一个可选参数 过采样	✔️	✔️	✔️	GH-104872
方法 draw_dropcap 新增了一个可选参数 过采样	✔️	✔️	✔️	GH-104872
方法 draw_dropcap_outline 新增了一个可选参数 过采样	✔️	✔️	✔️	GH-104872
方法 draw_line 新增了一个可选参数 过采样	✔️	✔️	✔️	GH-104872
方法 draw_line_outline 新增了一个可选参数 过采样	✔️	✔️	✔️	GH-104872
方法 draw_outline 新增了一个参数``过采样``	✔️	✔️	✔️	GH-104872
TextServer
方法 font_draw_glyph 新增了一个可选参数 过采样	✔️	✔️	✔️	GH-104872
方法 font_draw_glyph_outline 新增了一个可选参数 过采样	✔️	✔️	✔️	GH-104872
方法 shaped_text_draw 新增了一个可选参数 过采样	✔️	✔️	✔️	GH-104872
方法 shaped_text_draw_outline 新增了一个可选参数 过采样	✔️	✔️	✔️	GH-104872
TreeItem
方法 add_button 新增了一个可选参数 alt_text	✔️	✔️	✔️	GH-76829
TextServerExtension
方法 _font_draw_glyph 新增了一个可选参数 过采样	❌	❌	❌	GH-104872
方法 _font_draw_glyph_outline 新增了一个可选参数 过采样	❌	❌	❌	GH-104872
方法 _shaped_text_draw 新增了一个可选参数 过采样	❌	❌	❌	GH-104872
方法 _shaped_text_draw_outline 新增了一个可选参数 过采样	❌	❌	❌	GH-104872

XR

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
OpenXRAPIExtension
方法 register_composition_layer_provider 将参数 extension 的类型从 OpenXRExtensionWrapperExtension 更改为 OpenXRExtensionWrapper	✔️	✔️	✔️	GH-104087
方法 register_projection_views_extension 将参数 extension 的类型从 OpenXRExtensionWrapperExtension 更改为 OpenXRExtensionWrapper	✔️	✔️	✔️	GH-104087
方法 unregister_composition_layer_provider 将参数 extension 的类型从 OpenXRExtensionWrapperExtension 更改为 OpenXRExtensionWrapper	✔️	✔️	✔️	GH-104087
方法 unregister_projection_views_extension 的 extension 的参数类型从 OpenXRExtensionWrapperExtension 更改为 OpenXRExtensionWrapper	✔️	✔️	✔️	GH-104087
OpenXRBindingModifierEditor
类型 OpenXRBindingModifierEditor 的 API 类型从 Core 已更改为 Editor	❌	❌	❌	GH-103869
OpenXRInteractionProfileEditor
类型 OpenXRInteractionProfileEditor 的 API 类型从 Core 已更改为 Editor	❌	❌	❌	GH-103869
OpenXRInteractionProfileEditorBase
类型 OpenXRInteractionProfileEditorBase 的 API 类型从 Core 已更改为 Editor	❌	❌	❌	GH-103869

备注

类 OpenXRBindingModifierEditor、OpenXRInteractionProfileEditor 和 OpenXRInteractionProfileEditorBase 仅在编辑器中可用。在编辑器外部使用这些类将导致编译错误。

在 C# 中，这意味着这些类型已从 GodotSharp 程序集移至 GodotSharpEditor 程序集。请确保将使用这些类型的代码包裹在 #if TOOLS 块中，以确保它们不会被包含在导出的游戏内。

此更改也已向后移植到 4.4.1 版本。

编辑器插件

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
EditorExportPlatform
方法 get_forced_export_files 添加了一个新的可选参数 preset	✔️	✔️	✔️	GH-71542
EditorUndoRedoManager
方法 create_action 添加了一个新的可选参数 mark_unsaved	✔️	✔️	✔️	GH-106121
EditorExportPlatformExtension
方法 _get_option_icon 的返回类型从 ImageTexture 更改为 Texture2D	✔️	❌	❌	GH-108825

行为更改

在 4.5 版本中，一些功能的行为被更改，您可能需要重新适配您的项目。

图块地图画布层

相较于 4.4 版本，由于 4.5 版本中 TileMapLayer 的物理分区是默认开启的， TileMapLayer.get_coords_for_body_rid() 的返回值将变得不同。 TileMapLayer.physics_quadrant_size 的值越高，函数的精确度越低。若想要像 4.4 及之前版本一样获取准确的单元坐标，需要将 TileMapLayer.physics_quadrant_size 的值设置为 1 ，这同时也将关闭物理分区。

3D 模型导入

3D 模型导入器已进行修复，以正确处理骨骼层级结构中的非关节节点（GH-104184）。为保持兼容性，默认行为是沿用旧版方式导入现有文件（GH-107352）。对于新的 .gltf、.glb、.blend 和 .fbx 文件（无对应的 .import 文件），将使用新行为进行导入。但如果您希望对现有文件启用新行为，则必须在导入面板底部修改“命名版本”（Naming Version）选项：

核心

备注

Resource.duplicate(true) （执行深度复制）现在仅复制它被调用资源文件内部的资源。在 4.4 版本中，它相反复制了所有内容，包括外部资源。如果你正在深度复制一个包含对其他外部资源引用的资源，这些外部资源现在不再被复制。你必须调用 Resource.duplicate_deep(DEEP_DUPLICATE_ALL) 来保持旧的行为。

备注

现在 ProjectSettings.add_property_info() ，当字典参数缺少键或键无效时，它会发出警告。最重要的是，它现在会在传递 usage 键时发出警告，因为这个键没有被使用。在 4.5 之前也是这种情况，但它被默默忽略了。作为提醒，要正确设置属性使用信息，必须使用 ProjectSettings.set_as_basic() ， ProjectSettings.set_restart_if_changed() ，或者 ProjectSettings.set_as_internal() 。

备注

在 C# 中，StringExtensions.PathJoin 现在会在原始字符串为空，或追加的路径以路径分隔符开头时，避免添加多余的路径分隔符（GH-105281）。

备注

在 C# 中，当原始字符串不包含扩展名时，StringExtensions.GetExtension 现在将返回空字符串，而不是返回原始字符串（GH-108041）。

备注

在 C# 中，Quaternion(Vector3, Vector3) 构造函数现在能正确创建表示两个输入向量之间最短弧的四元数。此前，对于某些输入值，该构造函数会返回错误的结果（GH-107618）。

导航

备注

默认情况下，NavigationServer 导航服务器地图中的区域现在通过线程异步更新以提升性能。这可能导致线程同步导致更新延迟。异步区域更新可以通过 navigation/world/region_use_async_iterations 项目设置切换。

备注

NavigationServer 导航服务器中导航网格的合并改变了处理顺序。区域现在将先合并并缓存内部导航网格，然后导航地图将剩余的空闲边合并。如果项目之前存在导航地图同步错误，现在可能已经移动了受影响的边缘，使布局中已有的错误在路径定位中更加明显。 navigation/2d_or_3d/merge_rasterizer_cell_scale 项目设置可以调低以增加栅格网格的细节（ 0.01 为最小单元格大小）。如果边缘合并错误在最小光栅化缩放值下依然存在，错误可能是由于重叠引起：两个导航网格叠加在一起，导致几何体冲突。

物理

备注

当 3D 物理引擎设置为 Jolt Physics 时，现在默认情况下将始终报告 Area3D 与静态物体之间的重叠，因为项目设置项 physics/jolt_physics_3d/simulation/areas_detect_static_bodies 已被移除（GH-105746）。如果您仍希望忽略此类重叠，则需要改为调整 Area3D 或静态物体的碰撞掩码（collision mask）或碰撞层（collision layer）。

文本

备注

在 GDScript 中，对函数 RichTextLabel::add_image 和 RichTextLabel::update_image 的调用将继续有效，但 size_in_percent 参数现在将被用作 width_in_percent 的值，而 height_in_percent 将默认为 false``（`GH-107347`_）。若要恢复之前的行为，您可以显式地将 ``height_in_percent 设置为您之前传递给 size_in_percent 的相同值。