从 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_convexplanes 参数类型从无类型的 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_beginstorage_textures 参数类型从无类型的 Array 改为 Array[RID]

✔️

✔️

GH-76418

RenderingServer

方法 global_shader_parameter_get_list 将返回类型从 PackedStringArray 改为 Array[StringName]

✔️

GH-76418

SurfaceTool

方法 add_triangle_fantangents 参数类型从无类型的 Array 改为 Array[Plane]

✔️

✔️

GH-76418

导航

更改

GDScript 兼容

C# 二进制兼容

C# 源代码兼容

引入

NavigationAgent2D

方法 set_velocity 被属性 velocity 所取代

✔️

GH-69988

属性 time_horizon 被拆分为 time_horizon_agentstime_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_agentstime_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_agentsagent_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_agentsagent_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_STOPMOUSE_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”函数应该是这样:

  1. GDExtensionBool GDE_EXPORT example_library_init(const GDExtensionInterface *p_interface, const GDExtensionClassLibraryPtr p_library, GDExtensionInitialization *r_initialization) {
  2. godot::GDExtensionBinding::InitObject init_obj(p_interface, p_library, r_initialization);
  3. init_obj.register_initializer(initialize_example_module);
  4. init_obj.register_terminator(uninitialize_example_module);
  5. init_obj.set_minimum_library_initialization_level(MODULE_INITIALIZATION_LEVEL_SCENE);
  6. return init_obj.init();
  7. }

不过,对于 Godot 4.1 来说,它应该是这样的:

  1. GDExtensionBool GDE_EXPORT example_library_init(GDExtensionInterfaceGetProcAddress p_get_proc_address, const GDExtensionClassLibraryPtr p_library, GDExtensionInitialization *r_initialization) {
  2. godot::GDExtensionBinding::InitObject init_obj(p_get_proc_address, p_library, r_initialization);
  3. init_obj.register_initializer(initialize_example_module);
  4. init_obj.register_terminator(uninitialize_example_module);
  5. init_obj.set_minimum_library_initialization_level(MODULE_INITIALIZATION_LEVEL_SCENE);
  6. return init_obj.init();
  7. }

有 2 个小改动:

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

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

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

  1. [configuration]
  2. entry_symbol = "example_library_init"
  3. compatibility_minimum = 4.1

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

Previous Next


© 版权所有 2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0). Revision b1c660f7.

Built with Sphinx using a theme provided by Read the Docs.