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.0 升级到 Godot 4.1

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

破坏性更改

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

警告

GDExtension API 在 4.1 中完全不兼容，因此未列入下表。更多信息请参见 将 GDExtension 更新到 4.1 部分。

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

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

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

核心

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
Basis
looking_at 方法添加了可选的 use_model_front 参数	✔️	✔️	✔️	GH-76082
Object
get_meta_list 方法的返回类型从 PackedStringArray 改成了 Array[StringName]	✔️	❌	❌	GH-76418
Transform3D
looking_at 方法添加了可选的 use_model_front 参数	✔️	✔️	✔️	GH-76082
UndoRedo
create_action 添加了可选的 backward_undo_ops 参数	✔️	✔️	✔️	GH-76688
WorkerThreadPool
wait_for_task_completion 方法的返回类型从 void 改成了 Error	✔️	❌	✔️	GH-77143

动画

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
AnimationNode
_process 方法添加了 test_only 参数	❌	❌	❌	GH-75759
blend_input 方法添加了可选的 test_only 参数	✔️	✔️	✔️	GH-75759
blend_node 方法添加了可选的 test_only 参数	✔️	✔️	✔️	GH-75759
AnimationNodeStateMachinePlayback
get_travel_path 方法的返回类型从 PackedStringArray 改成了 Array[StringName]	✔️	❌	❌	GH-76418

2D 节点

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
PathFollow2D
移除了 lookahead 属性	❌	❌	❌	GH-72842

3D 节点

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
Geometry3D
方法 segment_intersects_convex 将 planes 参数类型从无类型的 Array 改为 Array[Plane]	✔️	✔️	❌	GH-76418
MeshInstance3D
方法 create_multiple_convex_collisions 增加了一个新的 settings 可选参数	✔️	✔️	✔️	GH-72152
Node3D
方法 look_at 增加了一个新的 use_model_front 可选参数	✔️	✔️	✔️	GH-76082
方法 look_at_from_position 增加了一个新的 use_model_front 可选参数	✔️	✔️	✔️	GH-76082

GUI 节点

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
CodeEdit
方法 add_code_completion_option 添加了一个新的 location 可选参数	✔️	✔️	✔️	GH-75746
RichTextLabel
方法 push_list 增加了一个新的 bullet 可选参数	✔️	✔️	✔️	GH-75017
方法 push_paragraph 增加了一个新的 justification_flags 可选参数	✔️	✔️	✔️	GH-75250
方法 push_paragraph 增加了一个新的 tab_stops 可选参数	✔️	✔️	✔️	GH-76401
Tree
方法 edit_selected 增加了一个新的 force_edit 可选参数	✔️	✔️	✔️	GH-76794

物理

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
Area2D
属性 priority 类型从 float 改为 int	❌	❌	❌	GH-72749
Area3D
属性 priority 类型从 float 改为 int	❌	❌	❌	GH-72749
PhysicsDirectSpaceState2D
方法 collide_shape 将返回类型从 Array[PackedVector2Array] 改为 Array[Vector2]	❌	❌	❌	GH-75260
PhysicsDirectSpaceState3D
方法 collide_shape 将返回类型从 Array[PackedVector3Array] 改为 Array[Vector3]	❌	❌	❌	GH-75260

渲染

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
RDShaderFile
方法 get_version_list 将返回类型从 PackedStringArray 改为 Array[StringName]	✔️	❌	❌	GH-76418
RenderingDevice
方法 draw_list_begin 将 storage_textures 参数类型从无类型的 Array 改为 Array[RID]	✔️	✔️	❌	GH-76418
RenderingServer
方法 global_shader_parameter_get_list 将返回类型从 PackedStringArray 改为 Array[StringName]	✔️	❌	❌	GH-76418
SurfaceTool
方法 add_triangle_fan 将 tangents 参数类型从无类型的 Array 改为 Array[Plane]	✔️	✔️	❌	GH-76418

导航

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
NavigationAgent2D
方法 set_velocity 被属性 velocity 所取代	✔️	❌	❌	GH-69988
属性 time_horizon 被拆分为 time_horizon_agents 和 time_horizon_obstacles	❌	❌	❌	GH-69988
NavigationAgent3D
属性 agent_height_offset 更名为 path_height_offset	❌	❌	❌	GH-69988
删除了属性 ignore_y	❌	❌	❌	GH-69988
方法 set_velocity 被属性 velocity 所取代	✔️	❌	❌	GH-69988
属性 time_horizon 被拆分为 time_horizon_agents 和 time_horizon_obstacles	❌	❌	❌	GH-69988
NavigationObstacle2D
删除了属性 estimate_radius	❌	❌	❌	GH-69988
方法 get_rid 更名为 get_agent_rid	❌	❌	❌	GH-69988
NavigationObstacle3D
删除了属性 estimate_radius	❌	❌	❌	GH-69988
方法 get_rid 更名为 get_agent_rid	❌	❌	❌	GH-69988
NavigationServer2D
方法 agent_set_callback 更名为 agent_set_avoidance_callback	❌	❌	❌	GH-69988
删除了方法 agent_set_target_velocity	❌	❌	❌	GH-69988
方法 agent_set_time_horizon 拆分为 agent_set_time_horizon_agents 和 agent_set_time_horizon_obstacles	❌	❌	❌	GH-69988
NavigationServer3D
方法 agent_set_callback 更名为 agent_set_avoidance_callback	❌	❌	❌	GH-69988
删除了方法 agent_set_target_velocity	❌	❌	❌	GH-69988
方法 agent_set_time_horizon 拆分为 agent_set_time_horizon_agents 和 agent_set_time_horizon_obstacles	❌	❌	❌	GH-69988

网络

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
WebRTCPeerConnectionExtension
方法 _create_data_channel 将返回类型从 Object 改为 WebRTCDataChannel	✔️	❌	✔️	GH-78237

编辑器插件

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
AnimationTrackEditPlugin
AnimationTrackEditPlugin 类型已移除	❌	❌	❌	GH-76413
EditorInterface
EditorInterface 类现在继承自 Object 而不是 Node	✔️	❌	❌	GH-76176
方法 set_movie_maker_enabled 替换为 movie_maker_enabled 属性	✔️	❌	❌	GH-76176
方法 is_movie_maker_enabled 替换为 movie_maker_enabled 属性	✔️	❌	❌	GH-76176
EditorResourcePreviewGenerator
_generate 方法添加了 metadata 参数	❌	❌	❌	GH-64628
_generate_from_path 方法添加了 metadata 参数	❌	❌	❌	GH-64628
EditorUndoRedoManager
create_action 添加了可选的 backward_undo_ops 参数	✔️	✔️	✔️	GH-76688

行为更改

4.1 中引入了一些行为的更改，你可能需要调整项目。

更改	引入
SubViewportContainer
当输入事件应传播到 SubViewport 及其子节点时，SubViewportContainer.mouse_filter 现在需要改为 MOUSE_FILTER_STOP 或 MOUSE_FILTER_PASS。详见 GH-79271。	GH-57894
如果多层 SubViewportContainer 节点都应接收鼠标输入事件，现在需要用 Area2D 节点代替。详见 GH-79128。	GH-57894
Viewport
启用 Physics Picking 的 Viewport 节点现在会自动将 InputEvent 标记为已处理。变通方法见 GH-79897。	GH-77595

将 GDExtension 更新到 4.1

为了修复一个严重的错误，在 Godot 4.1 中，我们不得不在很大程度上打破二进制兼容性，在很小程度上打破源代码兼容性。

这意味着为 Godot 4.0 制作的 GDExtensions 将需要为 Godot 4.1 重新编译（使用 godot-cpp 的 4.1 分支），并对其源代码稍作修改。

在 Godot 4.0 中，你的“entry_symbol”函数应该是这样：

GDExtensionBool GDE_EXPORT example_library_init(const GDExtensionInterface *p_interface, const GDExtensionClassLibraryPtr p_library, GDExtensionInitialization *r_initialization) {
    godot::GDExtensionBinding::InitObject init_obj(p_interface, p_library, r_initialization);

    init_obj.register_initializer(initialize_example_module);
    init_obj.register_terminator(uninitialize_example_module);
    init_obj.set_minimum_library_initialization_level(MODULE_INITIALIZATION_LEVEL_SCENE);

    return init_obj.init();
}

不过，对于 Godot 4.1 来说，它应该是这样的：

GDExtensionBool GDE_EXPORT example_library_init(GDExtensionInterfaceGetProcAddress p_get_proc_address, const GDExtensionClassLibraryPtr p_library, GDExtensionInitialization *r_initialization) {
    godot::GDExtensionBinding::InitObject init_obj(p_get_proc_address, p_library, r_initialization);

    init_obj.register_initializer(initialize_example_module);
    init_obj.register_terminator(uninitialize_example_module);
    init_obj.set_minimum_library_initialization_level(MODULE_INITIALIZATION_LEVEL_SCENE);

    return init_obj.init();
}

有 2 个小改动：

1. 第一个参数从 const GDExtensionInterface *p_interface 改为 GDExtensionInterfaceGetProcAddress p_get_proc_address

2. init_obj 变量的构造函数现在会接收 p_get_proc_address 作为第一个参数

You also need to add an extra compatibility_minimum line to your .gdextension file, so that it looks something like:

[configuration]

entry_symbol = "example_library_init"
compatibility_minimum = 4.1

这会让 Godot 知道你的 GDExtension 已经更新，可以在 Godot 4.1 中安全加载。