从 Godot 4.1 升级到 Godot 4.2
- 破坏性更改

从 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。