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.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
方法 set_scope 被 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

备注

在 C# 中，枚举 RenderingDevice.Features 破坏了兼容性，原因是绑定生成器检测枚举前缀的方式。GH-103941 为该枚举新增了成员，导致枚举项 Address 被重命名为 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 新增了一个可选参数 oversampling	✔️	✔️	✔️	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 新增了一个可选参数 oversampling	✔️	✔️	✔️	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 的相同值。