从 Godot 4.3 升级到 Godot 4.4

对于大多数使用 4.3 版本开发的游戏和应用程序来说，迁移到 4.4 版本应该是相对安全的。本页面旨在涵盖你在迁移项目时需要注意的所有事项。

破坏性更改

如果你正从 4.3 迁移到 4.4，此处列出的破坏性变更可能会影响你。这些变更按领域/系统进行了分组。

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

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

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

核心

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
FileAccess
方法 open_encrypted 增加了一个新的 iv 可选参数	✔️	✔️	✔️	GH-98918
方法 store_8 的返回类型从 void 更改为 bool	✔️	❌	✔️	GH-78289
方法 store_16 的返回类型从 void 更改为 bool	✔️	❌	✔️	GH-78289
方法 store_32 的返回类型从 void 更改为 bool	✔️	❌	✔️	GH-78289
方法 store_64 的返回类型从 void 更改为 bool	✔️	❌	✔️	GH-78289
方法 store_buffer 的返回类型从 void 更改为 bool	✔️	❌	✔️	GH-78289
store_csv_line 方法的返回类型从 void 改成了 bool	✔️	❌	✔️	GH-78289
方法 store_double 的返回类型从 void 更改为 bool	✔️	❌	✔️	GH-78289
方法 store_float 的返回类型从 void 更改为 bool	✔️	❌	✔️	GH-78289
方法 store_half 的返回类型从 void 更改为 bool	✔️	❌	✔️	GH-78289
方法 store_line 的返回类型从 void 更改为 bool	✔️	❌	✔️	GH-78289
store_pascal_string 方法的返回类型从 void 改成了 bool	✔️	❌	✔️	GH-78289
方法 store_real 的返回类型从 void 更改为 bool	✔️	❌	✔️	GH-78289
store_string 方法的返回类型从 void 改成了 bool	✔️	❌	✔️	GH-78289
方法 store_var 的返回类型从 void 更改为 bool	✔️	❌	✔️	GH-78289
OS
方法 execute_with_pipe 添加了一个新的可选参数 blocking	✔️	✔️	✔️	GH-94434
read_string_from_stdin 方法添加了 buffer_size 参数 [1]	❌	✔️	✔️	GH-91201
RegEx
方法 compile 添加了一个新的可选参数 show_error	✔️	✔️	✔️	GH-95212
方法 create_from_string 添加了一个新的可选参数 show_error	✔️	✔️	✔️	GH-95212
Semaphore
方法 post 添加了一个新的可选参数 count	✔️	✔️	✔️	GH-93605
TranslationServer
standardize_locale 方法添加了一个新的可选参数 add_defaults	✔️	✔️	✔️	GH-98972

导出注解

警告

Godot 4.4中， @export_file 的行为有所改变。当从检查器分配新值时，其路径被存储并且以 uid:// 的形式返回该引用，以这种方式代替之前的 res:// path(GH-97912)方式。这是一个破坏性改动，如果你的脚本或者序列化文件中依赖 ``res://``路径，很可能会导致问题。

例如，导出的文件数组中的可能包含混合的 uid:// 和 res:// 的路径，尤其是他们一部分在检查器编辑过。

在 4.4 版本中，保留``res://格式的唯一方法是手动编辑`.tscn` 或 `.tres` 文件，使用文本编辑器进行修改。从 Godot 4.5 开始，可以使用一个新的注解 ``@export_file_path 来显式保留旧的行为，并导出原始的 res:// 路径。

[1]

4.3 版本默认缓冲区大小为 1024。

GUI 节点

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
RichTextLabel
方法 push_meta 添加了一个新的可选参数 tooltip	✔️	✔️	✔️	GH-99481
set_table_column_expand 方法添加了一个新的可选参数 shrink	✔️	✔️	✔️	GH-101482
GraphEdit
connect_node 方法添加了新的一个可选参数 keep_alive	✔️	✔️	✔️	GH-97449
信号 frame_rect_changed 的 new_rect 参数类型从 Vector2 更改为 Rect2	❌	❌	❌	GH-102796

物理

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
SoftBody3D
set_point_pinned 方法增加了一个新的 insert_at 可选参数	✔️	✔️	✔️	GH-94684

渲染

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
CPUParticles2D
方法 restart 添加了一个新的 keep_seed 可选参数	✔️	✔️	✔️	GH-92089
CPUParticles3D
方法 restart 添加了一个新的 keep_seed 可选参数	✔️	✔️	✔️	GH-92089
GPUParticles2D
方法 restart 添加了一个新的 keep_seed 可选参数	✔️	✔️	✔️	GH-92089
GPUParticles3D
方法 restart 添加了一个新的 keep_seed 可选参数	✔️	✔️	✔️	GH-92089
RenderingDevice
方法 draw_list_begin 添加了新的 breadcrumb 可选参数	✔️	✔️	✔️	GH-90993
draw_list_begin 方法移除了许多参数	❌	✔️	✔️	GH-98670
index_buffer_create 方法增加了新的 enable_device_address 可选参数	✔️	✔️	✔️	GH-100062
方法 uniform_buffer_create 添加了一个新的可选参数 enable_device_address	✔️	✔️	✔️	GH-100062
方法 vertex_buffer_create 添加了一个新的可选参数 enable_device_address	✔️	✔️	✔️	GH-100062
RenderingServer
方法 multimesh_allocate_data 添加了一个新的可选参数 use_indirect	✔️	✔️	✔️	GH-99455
Shader
方法 get_default_texture_parameter 的返回类型从 Texture2D 更改为 Texture	✔️	❌	❌	GH-95126
方法 set_default_texture_parameter 的 texture 参数类型从 Texture2D 更改为 Texture	✔️	❌	✔️	GH-95126
VisualShaderNodeCubemap
属性 cube_map 的类型从 CubeMap 改为 TextureLayered	✔️	❌	❌	GH-95126
VisualShaderNodeTexture2DArray
属性 texture_array 的类型从 Texture2DArray 改为 TextureLayered	✔️	❌	❌	GH-95126

备注

在 C# 中，枚举 RenderingDevice.StorageBufferUsage 由于绑定生成器检测枚举前缀的方式而破坏了兼容性。在 GH-100062 中向该枚举添加了新成员，导致枚举成员被重命名。

导航

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
NavigationServer2D
方法 query_path 添加了一个新的可选参数 callback	✔️	✔️	✔️	GH-100129
NavigationServer3D
方法 query_path 添加了一个新的可选参数 callback	✔️	✔️	✔️	GH-100129

编辑器插件

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
EditorInterface
方法 open_scene_from_path 添加了一个新的可选参数 set_inherited	✔️	✔️	✔️	GH-90057
方法 popup_node_selector 添加了一个新的可选参数 current_value	✔️	✔️	✔️	GH-94323
方法 popup_property_selector 添加了一个新的可选参数 current_value	✔️	✔️	✔️	GH-94323
EditorSceneFormatImporter
方法 _get_import_flags 已被移除	❌	❌	❌	GH-101531
EditorTranslationParserPlugin
方法 _parse_file 的返回类型改为 Array ，并移除参数 msgids 和 msgids_context_plural	❌	❌	❌	GH-99297

备注

方法 _get_import_flags 从未被引擎调用。尽管会造成兼容性被破坏，但用户实际无法依赖此方法影响引擎行为，因此被移除。

行为更改

核心

备注

Curve 资源现在强制执行数值范围，若有点位超出默认 [0, 1] 范围，则需调整 min_value 和 max_value 。

渲染

备注

VisualShaderNodeVec4Constant 着色器节点的输入类型已改为 Vector4 ，用户需在常量中重新创建数值。

CSG

备注

CSG 实现现采用 Emmett Lalish 的 Manifold 库（GH-94321）。新实现更符合流形定义并修复了诸多错误与稳定性问题，因此不再支持非流形网格。如需渲染四边形或平面等非流形几何体，请改用 MeshInstance3D 。

Android

备注

Android 传感器事件现默认禁用（GH-94799）。需使用传感器事件的项目可在项目设置的 输入设备 > 传感器 中按需启用。