Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

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