从 Godot 4.0 升级到 Godot 4.1

从 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

GDExtension 仍处于测试阶段。在它被标记为稳定版之前，升级到新的 Godot 小版本时可能会出现兼容性问题。

为了修复一个严重的错误，在 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 个小改动：

第一个参数从 const GDExtensionInterface *p_interface 改为 GDExtensionInterfaceGetProcAddress p_get_proc_address
init_obj 变量的构造函数现在会接收 p_get_proc_address 作为第一个参数

你还需要在 .gdextension 文件中添加额外的 compatibility_minimum 行，使其看起来类似于

[configuration]
entry_symbol = "example_library_init"
compatibility_minimum = 4.1

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

从 Godot 4.0 升级到 Godot 4.1

从 Godot 4.0 升级到 Godot 4.1

破坏性更改

核心

动画

2D 节点

3D 节点

GUI 节点

物理

渲染

导航

网络

编辑器插件

行为更改

将 GDExtension 更新到 4.1