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 添加新的 keypadtooltipsize_in_percent 可选参数

✔️

✔️

✔️

GH-80410

渲染

更改

GDScript 兼容

C# 二进制兼容

C# 源代码兼容

引入

ImporterMesh

方法 add_surfaceflags 参数类型从 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

方法 commitflags 参数类型从 uint32 更改为 uint64

✔️

✔️

✔️

GH-81138

文本

更改

GDScript 兼容

C# 二进制兼容

C# 源代码兼容

引入

字体

方法 set_fallbacks 替换为 fallbacks 属性

✔️

GH-78266

方法 get_fallbacks 替换为