从 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

行为更改

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 of TileMapLayer.physics_quadrant_size will make this function less precise. To get the exact cell coordinates like in 4.4 and prior versions, you need to set TileMapLayer.physics_quadrant_size to 1, which disables physics chunking.

3D 模型导入

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

核心

备注

Resource.duplicate(true) (which performs deep duplication) now only duplicates resources internal to the resource file it's called on. In 4.4, this duplicated everything instead, including external resources. If you were deep-duplicating a resource that contained references to other external resources, those external resources aren't duplicated anymore. You must call Resource.duplicate_deep(RESOURCE_DEEP_DUPLICATE_ALL) instead to keep the old behavior.

备注

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 a usage 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 use ProjectSettings.set_as_basic(), ProjectSettings.set_restart_if_changed(), or ProjectSettings.set_as_internal() instead.

备注

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

备注

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

备注

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

导航

备注

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 the navigation/world/region_use_async_iterations project setting.

备注

The merging of navmeshes in the NavigationServer has changed processing order. Regions now merge and cache internal 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 shifted affected edges, making already existing errors in a layout more noticeable in the pathfinding. The navigation/2d_or_3d/merge_rasterizer_cell_scale project setting can be set to a lower value to increase the detail of the rasterization grid (with 0.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.

物理

备注

当 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 的相同值。