从 Godot 4.2 升级到 Godot 4.3

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

破坏性更改

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

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

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

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

GDExtension

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
GDExtension
移除了 close_library 方法	❌	❌	❌	GH-88418
移除了 initialize_library 方法	❌	❌	❌	GH-88418
移除了 open_library 方法	❌	❌	❌	GH-88418

由于这些方法基本上无法以任何有用的方式使用，这些方法已被移除。请改用 GDExtensionManager::load_extension 和 GDExtensionManager::unload_extension 来正确加载和卸载 GDExtension。

动画

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
动画
方法 position_track_interpolate 添加了新的 backward 可选参数	✔️	✔️	✔️	GH-86629
方法 rotation_track_interpolate 添加了新的 backward 可选参数	✔️	✔️	✔️	GH-86629
方法 scale_track_interpolate 添加了新的 backward 可选参数	✔️	✔️	✔️	GH-86629
create_action 添加了可选的 backward_undo_ops 参数	✔️	✔️	✔️	GH-86629
方法 value_track_interpolate 添加了新的 backward 可选参数	✔️	✔️	✔️	GH-86629
方法 track_find_key 增加了新的 limit 可选参数	✔️	✔️	✔️	GH-86661
方法 track_find_key 添加了新的 backward 可选参数	✔️	✔️	✔️	GH-92861
动画混合器
方法 _post_process_key_value 的 object 参数类型从 Object 更改为 uint64	✔️	❌	❌	GH-86687
3D骨骼
方法 add_bone 的返回类型从 void 更改为 int32	✔️	❌	✔️	GH-88791
信号 bone_pose_changed 已替换为 skeleton_updated	❌	❌	❌	GH-90575
3D骨骼附属
方法 on_bone_pose_update 已替换为 on_skeleton_update	✔️	✔️	✔️	GH-90575

GUI 节点

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
AcceptDialog
方法 register_text_enter 的参数 line_edit 的类型从 Control 更改为 LineEdit	✔️	✔️	✔️	GH-89419
方法 remove_button 的参数 button 的类型从 Control 更改为 Button	✔️	✔️	✔️	GH-89419

物理

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
PhysicsShapeQueryParameters2D
属性 motion 的类型从 Vector2 改为 Vector3	❌	❌	❌	GH-85393

备注

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

渲染

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
RenderingDevice
枚举字段 FinalAction.FINAL_ACTION_CONTINUE 将值从 2 更改为 0	✔️	❌	❌	GH-84976
枚举字段 InitialAction.INITIAL_ACTION_CLEAR 将值从 0 更改为 1	✔️	❌	❌	GH-84976
枚举字段 InitialAction.INITIAL_ACTION_CLEAR_REGION_CONTINUE 将值从 2 更改为 1	✔️	❌	❌	GH-84976
枚举字段 InitialAction.INITIAL_ACTION_CONTINUE 将值从 5 更改为 0	✔️	❌	❌	GH-84976
枚举字段 InitialAction.INITIAL_ACTION_DROP 将值从 4 更改为 2	✔️	❌	❌	GH-84976
枚举字段 InitialAction.INITIAL_ACTION_KEEP 将值从 3 更改为 0	✔️	❌	❌	GH-84976
buffer_clear 方法移除了 post_barrier 参数	✔️	✔️	✔️	GH-84976
buffer_update 方法移除了 post_barrier 参数	✔️	✔️	✔️	GH-84976
compute_list_begin 方法移除了 allow_draw_overlap 参数	✔️	✔️	✔️	GH-84976
compute_list_end 方法移除了 post_barrier 参数	✔️	✔️	✔️	GH-84976
draw_list_begin 方法移除了 storage_textures 参数	✔️	✔️	✔️	GH-84976
draw_list_end 方法移除了 post_barrier 参数	✔️	✔️	✔️	GH-84976
texture_clear 方法移除了 post_barrier 参数	✔️	✔️	✔️	GH-84976
texture_copy 方法移除了 post_barrier 参数	✔️	✔️	✔️	GH-84976
texture_resolve_multisample 方法移除了 post_barrier 参数	✔️	✔️	✔️	GH-84976
texture_update 方法移除了 post_barrier 参数	✔️	✔️	✔️	GH-84976
RenderingServer
environment_set_fog 方法增加了一个新的 fog_mode 可选参数	✔️	✔️	✔️	GH-84792
RenderSceneBuffersRD
get_color_layer 方法添加了一个新的 msaa 可选参数	✔️	✔️	✔️	GH-80214
get_depth_layer 方法增加了一个新的 msaa 可选参数	✔️	✔️	✔️	GH-80214
get_velocity_layer 方法增加了一个新的 msaa 可选参数	✔️	✔️	✔️	GH-80214
get_color_texture 方法添加了一个新的 msaa 可选参数	✔️	✔️	✔️	GH-80214
get_depth_texture 方法增加了一个新的 msaa 可选参数	✔️	✔️	✔️	GH-80214
get_velocity_texture 方法增加了一个新的 msaa 可选参数	✔️	✔️	✔️	GH-80214

备注

当 RenderingDevice.InitialAction 和 RenderingDevice.FinalAction 中枚举字段的值发生变化时，唯一使用它们的方法（ draw_list_begin ）添加了一个兼容性方法，该方法支持旧值。因此，实际上不会破坏兼容性。

备注

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

文本

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
字体
find_variation 方法添加了可选的 baseline_offset 参数	✔️	✔️	✔️	GH-87668
RichTextLabel
push_meta 方法增加了一个新的 underline_mode 可选参数	✔️	✔️	✔️	GH-89024
TextServer
shaped_text_get_word_breaks 方法增加了一个新的 skip_grapheme_flags 可选参数	✔️	✔️	✔️	GH-90732
TextServerExtension
_shaped_text_get_word_breaks 方法添加了 skip_grapheme_flags 参数	❌	❌	❌	GH-90732

音频

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
AudioStreamPlaybackPolyphonic
方法 play_stream 增加了新的 playback_type 和 bus 可选参数	✔️	✔️	✔️	GH-91382

导航

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
AStar2D
get_id_path 方法增加了一个新的 allow_partial_path 可选参数	✔️	✔️	✔️	GH-88047
get_point_path 方法增加了一个新的 allow_partial_path 可选参数	✔️	✔️	✔️	GH-88047
AStar3D
get_id_path 方法增加了一个新的 allow_partial_path 可选参数	✔️	✔️	✔️	GH-88047
get_point_path 方法增加了一个新的 allow_partial_path 可选参数	✔️	✔️	✔️	GH-88047
AStarGrid2D
get_id_path 方法增加了一个新的 allow_partial_path 可选参数	✔️	✔️	✔️	GH-88047
get_point_path 方法增加了一个新的 allow_partial_path 可选参数	✔️	✔️	✔️	GH-88047
NavigationRegion2D
移除了 avoidance_layers 属性	❌	❌	❌	GH-90747
移除了 constrain_avoidance 属性	❌	❌	❌	GH-90747
移除了 get_avoidance_layer_value 方法	❌	❌	❌	GH-90747
移除了 set_avoidance_layer_value 方法	❌	❌	❌	GH-90747

备注

NavigationRegion2D 中的约束避障功能是实验性的，现已停止使用且没有替代方案。

TileMap

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
TileData
get_navigation_polygon 方法添加了新的 flip_h ， flip_v ，和 transpose 可选参数	✔️	✔️	✔️	GH-84660
get_occluder 方法添加了新的 flip_h ， flip_v 和 transpose 可选参数	✔️	✔️	✔️	GH-84660

XR

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
WebXRInterface
get_input_source_tracker 方法将返回类型从 XRPositionalTracker 更改为 XRControllerTracker	✔️	❌	✔️	GH-90645
XRServer
get_tracker 方法将返回类型从 XRPositionalTracker 更改为 XRTracker	✔️	❌	❌	GH-90645

编辑器插件

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
EditorInspectorPlugin
方法 add_property_editor 新添加了可选参数 label	✔️	✔️	✔️	GH-92322
EditorPlugin
方法 add_control_to_bottom_panel 新添加了可选参数 shortcut	✔️	✔️	✔️	GH-88081
方法 add_control_to_dock 新添加了可选参数 shortcut	✔️	✔️	✔️	GH-88081
EditorSceneFormatImporterFBX
类型重命名为 EditorSceneFormatImporterFBX2GLTF	❌	❌	❌	GH-81746

行为更改

In 4.3, some behavior changes have been introduced, which might require you to adjust your project.

核心

备注

二进制序列化已被修改，以修复脚本化对象和类型化数组的序列化问题（GH-78219 ）。这一改动破坏了脚本编码/解码的兼容性。

备注

PackedByteArray 现在能够使用更紧凑的 base64 编码进行存储。但代价是它破坏了兼容性，这意味着旧版本的 Godot 可能无法打开由 4.3 版本保存的资源（GH-89186）。

为了最大限度地提高兼容性，目前这个新的存储格式将仅针对包含大型 PackedByteArray 的资源和场景启用。对于旧版本的 Godot，我们也会在补丁更新中添加对这个新格式的支持。一旦所有受支持的 Godot 版本都能够读取新格式，我们将逐步淘汰兼容性措施，并让所有资源和场景都使用新的存储格式。

备注

在 C# 中， Transform3D.InterpolateWith 的实现已修复为使用正确的操作顺序，在缩放之前应用旋转（GH-89843）。

备注

在 C# 中，修复了 Aabb.GetSupport 的实现，以正确返回支持向量（GH-88919）。

备注

在 C# 中，Variant 类型的 ToString 实现现在默认使用 InvariantCulture （GH-89547），这意味着 Vector2(1.2, 3.4) 将使用 . 作为小数点分隔符进行格式化，而与程序运行的操作系统语言无关。

动画

备注

AnimationMixer 已将它的捕获（Capture） 模式替换为新的捕获 （Capture） 功能，该功能比旧版本效果更好，这取代了现有的缓存（GH-86715）。

备注

AnimationNode 重新设计了获取语义时间（semantic time）信息的过程。这确保了时间相关的行为能够按预期工作，但也改变了混合行为。实现 _process 虚方法的开发者还应注意，该方法现已弃用，未来将被新方法取代（GH-87171）。

有关动画更改的更多信息，请参阅`将动画从 Godot 4.0 迁移到 4.3 <https://godotengine.org/article/migrating-animations-from-godot-4-0-to-4-3>`__ 文章。

GUI 节点

备注

默认字体轮廓颜色从白色更改为黑色（GH-54641）。

备注

auto_translate 属性已被弃用，取而代之的是现在位于 Node 中的 auto_translate_mode 属性（GH-87530）。 auto_translate_mode 的默认值为 AUTO_TRANSLATE_INHERIT ，这意味着节点会从其父节点继承 auto_translate_mode 值。因此，如果现有节点的 auto_translate 属性设置为 true ，但其父节点的 auto_translate 属性设置为 false ，那么这些节点可能不再被翻译。

多人游戏

备注

SceneMultiplayer 的缓存协议已更改，在发送节点移除确认数据包时，现在会发送接收到的 ID 而不是节点路径（GH-90027）。

这是对高级多人游戏协议（high-level multiplayer protocol）的破坏性改动，该改动会使其与之前的 Godot 版本不兼容。请将你的服务器和客户端版本都升级到 Godot 4.3 以妥善处理此更改。

请注意，高级多人游戏（high-level multiplayer）功能仅与使用相同 Godot 版本的服务器和客户端兼容。建议实现某种版本检查机制。

渲染

备注

现在，贴花会将调制颜色从 sRGB 颜色转换为线性颜色，与所有其他输入一致，以确保正确的混合效果（GH-89849）。使用贴花调制属性的现有项目会注意到其视觉效果发生了变化。

备注

现已实现反向 Z 深度缓冲技术。这可能会破坏某些着色器的兼容性。请阅读 反向 Z 简介 (又名：很抱歉破坏了你的着色器) 文章，了解更多信息并获取修复常见场景的指导。

TileMap

备注

TileMap 图层已移至单独的节点（GH-87379 和 GH-89179）。

Android

备注

Android 权限不再自动请求，因为这违反了推荐的最佳实践（GH-87080)。请使用 OS 中的 request_permission 方法和 MainLoop 上的 on_request_permissions_result 信号来请求权限并等待用户响应。