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.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

行为更改

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

核心

备注

二进制序列化已被修改，以修复脚本化对象和类型化数组的序列化问题（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 信号来请求权限并等待用户响应。