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.1 升级到 Godot 4.2

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

破坏性更改

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

警告

Mesh 资源格式在 4.2 中已更改，以允许 顶点和属性压缩 。这个更改可以提高渲染性能，尤其是在受内存带宽限制的平台（例如移动设备）上。

仍然可以加载 Godot 4.0-4.1 Mesh 格式，但在之前的 Godot 版本中 不可能 加载 Godot 4.2 Mesh 格式。打开使用 4.2 之前版本创建的 Godot 项目时，可能会出现一个升级对话框，其中会提供两个选项：

• 重启并升级： 升级项目中所有网格的网格格式，并将结果保存到磁盘。一旦选择，此选项可以防止将项目降级到 4.2 之前的 Godot 版本。请设置版本控制系统，并在 选择此选项之前 推送你的更改！

• 仅升级： 升级内存中的网格格式，但不将升级结果写入磁盘。如果将来有需要，这个设置可允许你将项目降级回到 4.2 之前的 Godot 版本。这个设置的缺点是每次加载项目都会变慢，因为每次加载项目时都需要升级网格格式。这些增加的加载时间也会影响导出的项目。 Mesh 资源的数量和复杂度决定了加载时间受影响的程度。

如果该对话框没有出现，请使用编辑器顶端的 项目 > 工具 > 升级网格表面...。

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

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

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

核心

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
节点
常量 NOTIFICATION_NODE_RECACHE_REQUESTED 已被删除	❌	✔️	❌	GH-84419

动画

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
AnimationPlayer
方法 _post_process_key_value 移动到基类 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 add_animation_library 移动到基类 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 advance 移至基类 AnimationMixer	✔️	✔️	✔️	GH-80813
信号 animation_finished 移动到基类 AnimationMixer	✔️	❌	❌	GH-80813
信号 animation_started 移动到基类 AnimationMixer	✔️	❌	❌	GH-80813
信号 animation_libraries_updated 移动到基类 AnimationMixer	✔️	✔️	✔️	GH-80813
信号 animation_list_changed 移动到基类 AnimationMixer	✔️	✔️	✔️	GH-80813
属性 audio_max_polyphony 移动到基类 AnimationMixer	✔️	✔️	✔️	GH-80813
信号 caches_cleared 移动到基类 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 clear_caches 移至基类 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 find_animation 移至基类 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 find_animation_library 移动到基类 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 get_animation 移至基类 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 get_animation_library 移动到基类 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 get_animation_library_list 移至基类 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 get_animation_list 移至基类 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 has_animation 移至基类 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 has_animation_library 移动到基类 AnimationMixer	✔️	✔️	✔️	GH-80813
属性 method_call_mode 重命名为 callback_mode_method ，并移至基类 AnimationMixer	✔️	✔️	✔️	GH-80813
属性 playback_active 重命名为 active ，并移至基类 AnimationMixer	✔️	✔️	✔️	GH-80813
属性 playback_process_mode 重命名为 callback_mode_process ，并移动到基类 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 remove_animation_library 移动到基类 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 rename_animation_library 移动到基类 AnimationMixer	✔️	✔️	✔️	GH-80813
属性 reset_on_save 移至基类 AnimationMixer	✔️	✔️	✔️	GH-80813
属性 root_node 移动到基类 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 set_reset_on_save_enabled 移至基类 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 seek 添加了一个新的 update_only 可选参数	✔️	✔️	✔️	GH-80813
AnimationTree
方法 _post_process_key_value 移动到基类 AnimationMixer	✔️	✔️	✔️	GH-80813
属性 active 移至基类 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 advance 移至基类 AnimationMixer	✔️	✔️	✔️	GH-80813
信号 animation_finished 移动到基类 AnimationMixer	✔️	❌	❌	GH-80813
信号 animation_started 移动到基类 AnimationMixer	✔️	❌	❌	GH-80813
属性 audio_max_polyphony 移动到基类 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 get_root_motion_position 移至基类 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 get_root_motion_position_accumulator 移动到基类 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 get_root_motion_rotation 移至基类 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 get_root_motion_rotation_accumulator 移动到基类 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 get_root_motion_scale 移至基类 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 get_root_motion_scale_accumulator 移至基类 AnimationMixer	✔️	✔️	✔️	GH-80813
属性 process_callback 重命名为 callback_mode_process ，并移至基类 AnimationMixer	✔️	✔️	✔️	GH-80813
属性 root_motion_track 移动到基类 AnimationMixer	✔️	✔️	✔️	GH-80813
属性 tree_root 的类型从 AnimationNode 改为 AnimationRootNode	✔️	❌	❌	GH-80813

GUI 节点

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
PopupMenu
add_icon_shortcut 方法增加了一个新的 allow_echo 可选参数	✔️	✔️	✔️	GH-36493
add_shortcut 方法增加了一个新的 allow_echo 可选参数	✔️	✔️	✔️	GH-36493
方法 clear 添加了一个新的 free_submenus 可选参数	✔️	✔️	✔️	GH-79965
RichTextLabel
方法 add_image 添加新的 key 、 pad 、 tooltip 和 size_in_percent 可选参数	✔️	✔️	✔️	GH-80410

渲染

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
ImporterMesh
方法 add_surface 将 flags 参数类型从 uint32 更改为 uint64	✔️	✔️	✔️	GH-81138
方法 get_surface_format 将返回类型从 uint32 更改为 uint64	✔️	❌	❌	GH-81138
MeshDataTool
方法 commit_to_surface 添加了一个新的 compression_flags 可选参数	✔️	✔️	✔️	GH-81138
方法 get_format 将返回类型从 uint32 更改为 uint64	✔️	❌	❌	GH-81138
RenderingDevice
枚举字段 BarrierMask.BARRIER_MASK_RASTER 将值从 1 更改为 9	✔️	✔️	✔️	GH-79911
枚举字段 BarrierMask.BARRIER_MASK_ALL_BARRIERS 将值从 7 更改为 32767	✔️	✔️	✔️	GH-79911
枚举字段 BarrierMask.BARRIER_MASK_NO_BARRIER 将值从 8 更改为 32768	✔️	✔️	✔️	GH-79911
方法 shader_create_from_bytecode 添加了一个新的 placeholder_rid 可选参数	✔️	✔️	✔️	GH-79606
方法 shader_get_vertex_input_attribute_ask 将返回类型从 uint32 更改为 uint64	✔️	❌	❌	GH-81138
SurfaceTool
方法 commit 将 flags 参数类型从 uint32 更改为 uint64	✔️	✔️	✔️	GH-81138

文本

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
字体
方法 set_fallbacks 替换为 fallbacks 属性	✔️	❌	❌	GH-78266
方法 get_fallbacks 替换为 fallbacks 属性	✔️	❌	❌	GH-78266
方法 find_variation 添加了新的可选参数： spacing_top 、 spacing_bottom 、 spacing_space 、 spacing_glyph	✔️	✔️	✔️	GH-80954

GraphEdit

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
GraphEdit
属性 arrange_nodes_button_hidden 更名为 show_arrange_button	❌	✔️	✔️	GH-81582
方法 get_zoom_hbox 更名为 get_menu_hbox	❌	✔️	✔️	GH-79308
属性 snap_distance 更名为 snapping_distance	❌	✔️	✔️	GH-79308
属性 use_snap 更名为 snapping_enabled	❌	✔️	✔️	GH-79308
GraphNode
删除了属性 comment	❌	❌	❌	GH-79307
信号 close_request 重命名为 delete_request ，并移至基类 GraphElement	❌	✔️	✔️	GH-79311
属性 draggable 移至基类 GraphElement	✔️	✔️	✔️	GH-79311
属性 draggable 移至基类 GraphElement	✔️	✔️	✔️	GH-79311
信号 dragged 移动到基类 GraphElement	✔️	❌	❌	GH-79311
删除了方法 get_connection_input_color	❌	❌	❌	GH-79311
删除了方法 get_connection_input_count	❌	❌	❌	GH-79311
删除了方法 get_connection_input_height	❌	❌	❌	GH-79311
删除了方法 get_connection_input_position	❌	❌	❌	GH-79311
删除了方法 get_connection_input_slot	❌	❌	❌	GH-79311
删除了方法 get_connection_input_type	❌	❌	❌	GH-79311
删除了方法 get_connection_output_color	❌	❌	❌	GH-79311
删除了方法 get_connection_output_count	❌	❌	❌	GH-79311
删除了方法 get_connection_output_height	❌	❌	❌	GH-79311
删除了方法 get_connection_output_position	❌	❌	❌	GH-79311
删除了方法 get_connection_output_slot	❌	❌	❌	GH-79311
删除了方法 get_connection_output_type	❌	❌	❌	GH-79311
删除了属性 language	❌	❌	❌	GH-79311
信号 node_deselected 移动到基类 GraphElement	✔️	✔️	✔️	GH-79311
信号 node_selected 移动到基类 GraphElement	✔️	✔️	✔️	GH-79311
删除了属性 overlay	❌	❌	❌	GH-79311
属性 position_offset 移动到基类 GraphElement	✔️	✔️	✔️	GH-79311
信号 position_offset_changed 移动到基类 GraphElement	✔️	✔️	✔️	GH-79311
信号 raise_request 移动到基类 GraphElement	✔️	✔️	✔️	GH-79311
属性 ressized 移至基类 GraphElement	✔️	✔️	✔️	GH-79311
信号 resize_request 移动到基类 GraphElement	✔️	❌	❌	GH-79311
属性 selectable 移至基类 GraphElement	✔️	✔️	✔️	GH-79311
属性 selected 移至基类 GraphElement	✔️	✔️	✔️	GH-79311
删除了属性 show_close	❌	❌	❌	GH-79311
删除了属性 text_direction	❌	❌	❌	GH-79311

TileMap

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
TileMap
属性 cell_quadrant_size 更名为 rendering_quadrant_size	❌	✔️	✔️	GH-81070

XR

更改	GDScript 兼容	C# 二进制兼容	C# 源代码兼容	引入
XRInterface
新增了属性 environment_blend_mode	✔️	❌	❌	GH-81561

备注

这一更改破坏了 C# 中的兼容性，因为新属性和现有枚举的名称相冲突，而 C# 绑定生成器优先考虑属性，因此枚举类型由 EnvironmentBlendMode 重命名为 EnvironmentBlendModeEnum。