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.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:// 路径（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）。需使用传感器事件的项目可在项目设置的 输入设备 > 传感器 中按需启用。