从 Godot 3 升级到 Godot 4

我应该升级到 Godot4 吗？

在升级之前，有必要考虑一下升级会给你的项目带来的优缺点。

升级的优点

除了 4.0 中提供的新功能之外，升级还有如下优点：

• 许多问题已经在4.0进行了修复，但是由于各种各样的原因（例如不同的图形API以及向后兼容性等），这些问题无法在3.x版本中修复。

• 4.x 版本将享受更长的支持周期。Godot 3.x 也将在 4.0 发布之后支持一段时间，但最终将会放弃支持。

记录 Godot 4.0 中新功能的文档页面列表见 文档变更日志，Godot 中所有功能列表见 特性列表。

升级的缺点

如果你并不 需要 Godot 4.x 中的任何新特性，出于以下原因，你可能希望继续使用 Godot 3.x：

• Godot 4 的基准硬件需求要稍高一些（例如内存占用），无论是编辑器还是导出后的项目。这些都是实现核心优化所必须的。

• 由于 Godot 4 比 Godot 3 包含更多的功能，Godot 4 导出的项目二进制文件相比更大。这个问题可以通过针对大小优化构建来缓解，但是启用模块相同的前提下，4.0 构建的大小仍然会比 3.x 构建要大。为 Web 导出时可能会造成一些问题，因为二进制文件的大小对引擎初始化的速度有直接影响（不考虑下载速度）。

• Godot 4 不支持且不会提供对 GLES2 渲染器的支持。（使用新的兼容渲染器，Godot依然支持 GLES3 渲染，这意味着不支持 Vulkan 的设备依旧可以运行Godot 4。）

  • 如果你的目标是像 Intel Sandy Bridge（第二代）集成图形一样极其老旧的硬件，升级后将阻止项目在此类硬件上运行。软件 OpenGL 实现可以用来绕过这个限制，但对于游戏来说太慢了。

升级的注意事项

由于 Godot 4 在许多方面都是完全重写的，一些功能在这个过程中不幸地丢失了。其中一些功能可能会在未来的 Godot 版本中恢复：

• Bullet 物理引擎被移除以支持 GodotPhysics。这只会影响使用默认物理引擎（即 Bullet）且没有手动更改为 GodotPhysics 的3D项目。没有在核心中重新添加 Bullet 物理引擎的计划，但由于 GDExtension，可以为其创建第三方附加组件。

• 默认情况下，2D 渲染不再以 HDR 模式执行，这意味着"过亮"的调制值不会产生可见效果。从 Godot 4.2 开始，你可以启用项目设置 HDR 2D 来以 HDR 模式执行 2D 渲染。另请参阅 在 2D 中使用辉光。

• 虽然使用 Forward+ 或 Mobile 后端时，3D 模式下渲染仍然会以 HDR 格式进行，但视口无法再返回 HDR 数据。 我们计划在未来某个时候恢复这一功能。

• Mono 被替换为 .Net 6。这意味着现在不支持导出 C# 项目到 Android，iOS 和 HTML5。导出 C# 项目到桌面平台依然是支持的，并且从 4.2 开始，实验性支持导出到移动平台。随着上游支持的改进，将 C# 项目导出到更多平台的支持将在未来的 4.x 版本中恢复。

你可以通过在 GitHub 上搜索issues 标记为“regression”而不是“bug”来找到更完整的功能回归列表。

升级前的准备（可选）

如果你想在未来升级到 Godot 4，可以考虑在你的项目中使用 Tweener 和 Time 单例。这些类在 Godot 3.5 及更高版本中都已可用。

如此，你便不用再依赖已弃用的 Tween node 和 OS time 函数，这两个函数在 Godot 4.0 中都被删除了。

使用 .gdshader 后缀来替换 .shader 后缀是一个很好的点子。Godot 3.x 支持这两种后缀，但 Godot 4.0 仅支持 .gdshader 这一种。

运行项目升级工具

危险

升级前，请对你的项目进行完整备份！项目升级工具不会对升级的项目进行备份。

你可以使用版本控制备份项目，也可以将项目文件夹复制到其他位置。

使用项目管理器

使用项目升级工具：

1. 打开 Godot 4 项目管理器。

2. 使用导入按钮导入 Godot 3.x 项目，或者使用扫描按钮在文件夹中查找项目。

3. 双击导入的项目（或者选中项目后选择编辑）。

4. 你将看到一个带有两个选项的对话框：仅转换 project.godot和转换整个项目。在确保你的项目已经备份之后（见上面的警告），请选择转换整个项目。仅转换 project.godot 选项只应该用于高级用例，处理转换工具失败的情况。

5. 等待项目转换完成。由许多场景组成的大项目将花费更多的时间。

6. 当项目管理器界面再次可用时，双击项目 (或选中项目，然后选择 编辑) 在编辑器中打开。

如果某些项目文件过大或过长会遇到转换问题，你可以使用命令行来升级项目（参见下面的内容）。你还可以重设转换器的大小限制。

使用命令行

要从 命令行 使用升级工具，建议通过使用如下参数运行 Godot 编辑器二进制文件来验证项目转换：

# [<max_file_kb>] [<max_line_size>] are optional arguments.
# Remove them if you aren't changing their values.
path/to/godot.binary --path /path/to/project/folder --validate-conversion-3to4 [<max_file_kb>] [<max_line_size>]

如果计划升级列表无误，在 Godot 编辑器二进制文件上运行以下命令来升级项目文件：

# [<max_file_kb>] [<max_line_size>] are optional arguments.
# Remove them if you aren't changing their values.
path/to/godot.binary --path /path/to/project/folder --convert-3to4 [<max_file_kb>] [<max_line_size>]

[<max_file_kb>] 和 [<max_line_size>] 是可选参数，用于指定要转换的文件的最大大小（单位分别为 KB 和行）。默认限制分别为 4MB 和十万行。如果文件达到上述任何一个限制，则项目转换器将不会对其进行升级。这对于防止大量资源占用会降低升级速度来说非常有用。

如果你仍然希望通过项目升级工具转换大文件，请在运行项目升级工具时增加大小限制。例如，运行带有这些参数的 Godot 编辑器二进制文件会使这两个限制都增加10倍：

path/to/godot.binary --path /path/to/project/folder --convert-3to4 40000 1000000

备注

只有Godot 3.x的项目可以使用 Godot 4 编辑器中的项目转换工具升级。

建议在使用项目升级工具之前检查你的项目是否为最新的 3.x 稳定版。

运行项目升级工具后修复项目

项目升级完成之后，你可能会注意到某些东西看起来不太正常。脚本还可能包含各种错误（在大项目中可能有几百个）。这是因为项目升级工具无法满足所有情况。故升级后的很大一部分问题仍然需要手动解决。

自动重命名节点和资源

以下列表是 Godot 4.0 为了一致性或清晰性而简单重命名的节点。项目升级工具会在你的脚本中自动重命名它们。

在 3D 节点中有一些重命名值得注意，它们中与 2D 功能相似的节点全部以 3D 为后缀。例如 Area 现在为 Area3D。

为了方便搜索，此表列出了所有已更名并自动转换的节点和资源，不包括仅在旧名称后添 3D 后缀的节点和资源：

旧名称（Godot 3.x）	新名称（Godot 4）
AnimatedSprite	AnimatedSprite2D
ARVRCamera	XRCamera3D
ARVRController	XRController3D
ARVRAnchor	XRAnchor3D
ARVRInterface	XRInterface
ARVROrigin	XROrigin3D
ARVRPositionalTracker	XRPositionalTracker
ARVRServer	XRServer
BoxShape	BoxShape3D
CapsuleShape	CapsuleShape3D
CubeMesh	BoxMesh
EditorSpatialGizmo	EditorNode3DGizmo
EditorSpatialGizmoPlugin	EditorNode3DGizmoPlugin
GIProbe	VoxelGI
GIProbeData	VoxelGIData
GradientTexture	GradientTexture1D
KinematicBody	CharacterBody3D
KinematicBody2D	CharacterBody2D
Light2D	PointLight2D
LineShape2D	WorldBoundaryShape2D
Listener	AudioListener3D
NavigationMeshInstance	NavigationRegion3D
NavigationPolygonInstance	NavigationRegion2D
Navigation2DServer	NavigationServer2D
PanoramaSky	Sky
Particles	GPUParticles3D
Particles2D	GPUParticles2D
ParticlesMaterial	ParticleProcessMaterial
Physics2DDirectBodyState	PhysicsDirectBodyState2D
Physics2DDirectSpaceState	PhysicsDirectSpaceState2D
Physics2DServer	PhysicsServer2D
Physics2DShapeQueryParameters	PhysicsShapeQueryParameters2D
Physics2DTestMotionResult	PhysicsTestMotionResult2D
PlaneShape	WorldBoundaryShape3D
Position2D	Marker2D
Position3D	Marker3D
ProceduralSky	Sky
RayShape	SeparationRayShape3D
RayShape2D	SeparationRayShape2D
ShortCut	Shortcut
Spatial	Node3D
SpatialGizmo	Node3DGizmo
SpatialMaterial	StandardMaterial3D
Sprite	Sprite2D
StreamTexture	CompressedTexture2D
TextureProgress	TextureProgressBar
VideoPlayer	VideoStreamPlayer
ViewportContainer	SubViewportContainer
Viewport	SubViewport
VisibilityEnabler	VisibleOnScreenEnabler3D
VisibilityNotifier	VisibleOnScreenNotifier3D
VisibilityNotifier2D	VisibleOnScreenNotifier2D
VisibilityNotifier3D	VisibleOnScreenNotifier3D
VisualServer	RenderingServer
VisualShaderNodeScalarConstant	VisualShaderNodeFloatConstant
VisualShaderNodeScalarFunc	VisualShaderNodeFloatFunc
VisualShaderNodeScalarOp	VisualShaderNodeFloatOp
VisualShaderNodeScalarClamp	VisualShaderNodeClamp
VisualShaderNodeVectorClamp	VisualShaderNodeClamp
VisualShaderNodeScalarInterp	VisualShaderNodeMix
VisualShaderNodeVectorInterp	VisualShaderNodeMix
VisualShaderNodeVectorScalarMix	VisualShaderNodeMix
VisualShaderNodeScalarSmoothStep	VisualShaderNodeSmoothStep
VisualShaderNodeVectorSmoothStep	VisualShaderNodeSmoothStep
VisualShaderNodeVectorScalarSmoothStep	VisualShaderNodeSmoothStep
VisualShaderNodeVectorScalarStep	VisualShaderNodeStep
VisualShaderNodeScalarSwitch	VisualShaderNodeSwitch
VisualShaderNodeScalarTransformMult	VisualShaderNodeTransformOp
VisualShaderNodeScalarDerivativeFunc	VisualShaderNodeDerivativeFunc
VisualShaderNodeVectorDerivativeFunc	VisualShaderNodeDerivativeFunc
VisualShaderNodeBooleanUniform	VisualShaderNodeBooleanParameter
VisualShaderNodeColorUniform	VisualShaderNodeColorParameter
VisualShaderNodeScalarUniform	VisualShaderNodeFloatParameter
VisualShaderNodeCubeMapUniform	VisualShaderNodeCubeMapParameter
VisualShaderNodeTextureUniform	VisualShaderNodeTexture2DParameter
VisualShaderNodeTextureUniformTriplanar	VisualShaderNodeTextureParameterTriplanar
VisualShaderNodeTransformUniform	VisualShaderNodeTransformParameter
VisualShaderNodeVec3Uniform	VisualShaderNodeVec3Parameter
VisualShaderNodeUniform	VisualShaderNodeParameter
VisualShaderNodeUniformRef	VisualShaderNodeParameterRef

手动重命名的方法、属性、信号、枚举和常量

由于项目升级工具的工作方式，并非所有 API 的重命名都可以自动执行。 以下列表包含了必须使用脚本编辑器手动执行的所有重命名项目。

如果你在下面的列表中找不到节点或资源，请参考上表查找其新名称。

小技巧

你可以在脚本编辑器打开时按 Ctrl + Shift + R 使用 在文件中替换 对话框来加快替换速度。 但是需要小心，“在文件中替换”对话框不提供任何撤消替换的方法。 使用版本控制定期提交升级工作。 如果你要比编辑器的“在文件中替换”对话框更灵活的工具，也可以使用 sd等命令行工具。

如果使用 C#，请记住在项目中使用 PascalCase 表示法（即帕斯卡命名法）搜索过时的 API 使用情况（并使用 PascalCase 表示法执行替换）。

方法

• 文件和目录类已被 FileAccess 与 DirAccess 取代，它们拥有完全不同的 API。现在有几种方法是静态的，这意味着你可以不创建对象而直接使用 FileAccess 或 DirAccess 的方法。

• OS 单例中与屏幕和窗口相关的方法（例如 OS.get_screen_size()）已被移至 DisplayServer 单例。方法命名也改为使用 DisplayServer.<object>_<get/set>_property() 的形式。例如，OS.get_screen_size() 变成了 DisplayServer.screen_get_size()。

• 时间和日期方法已从 OS 单例移动至 Time 单例。（ 在Godot 3.5 以及其后的版本中依旧如此。）

• 你可能需要将一些 instance() 调用替换为 instantiate()。转换器 应该 会自动处理这个，但这依赖于可能无法在全部情况下正常工作的自定义代码。

• AcceptDialog的 set_autowrap() 现在是 set_autowrap_mode()。

• AnimationNode的 process() 现在是 _process()（注意前面的下划线，表示虚方法）。

• AnimationPlayer 的 add_animation() 方法现在改为 add_animation_library() ，并且现在使用 AnimationLibrary。

• AnimationTree的 set_process_mode() 现在是 set_process_callback()。

• Array的``empty()``方法现在是``is_empty()``.

• Array的 invert() 方法现在为 reverse()。

• Array的 remove() 现在是 remove_at()。

• AStar2D和AStar3D的 get_points() 现在改为 get_points_id()。

• BaseButton的 set_event() 现在改为 set_shortcut()。

• Camera2D的 get_h_offset() 现在是 get_drag_horizontal_offset()。

• Camera2D的 get_v_offset() 现在改为 get_drag_vertical_offset()。

• Camera2D的 set_h_offset() 现在改为 set_drag_horizontal_offset()。

• Camera2D的 set_v_offset() 现在改为 set_drag_vertical_offset()。

• CanvasItem的 raise() 现在改为 move_to_front()。

• CanvasItem的 update() 现在改为 queue_redraw()。

• Control的 get_stylebox() 现在是 get_theme_stylebox()。

• Control的 set_tooltip() 现在是 set_tooltip_text()。

• EditorNode3DGizmoPlugin的 create_gizmo() 现在改为 _create_gizmo()（注意前面的下划线，表示虚方法）。

• ENetMultiplayerPeer的 get_peer_port() 现在是 get_peer()。

• FileDialog的 get_mode() 现在是 get_file_mode()。

• FileDialog的 set_mode() 现在改为 set_file_mode()。

• GraphNode的 get_offset() 现在改为 get_position_offset()。

• GridMap 的 map_to_world() 方法现在叫 map_to_local()。

• GridMap的 world_to_map() 现在改为 local_to_map()。

• Image的 get_rect() 方法现在为 get_region()。

• ImmediateGeometry'的 set_normal() 更名为 surface_set_normal()。

• ImmediateMesh的``set_color()`` 更名为``surface_set_color()``。

• ImmediateMesh的 set_uv()``更名为 ``surface_set_uv()。

• ItemList 的 get_v_scroll() 方法现在为 get_v_scroll_bar()。

• MultiPlayerAPI 的 get_network_connected_peers() 现在改为 get_peers()。

• MultiPlayerAPI 的 get_network_peer() 现在改为 get_peer()。

• MultiPlayerAPI 的 get_network_unique_id() 现在改为 get_unique_id()。

• MultiPlayerAPI 的 has_network_peer() 现在是 has_multiplayer_peer()。

• MultiPlayerAPI 的 is_refusing_new_network_connections() 现改为 is_refusing_new_connections()。

• PacketPeerUDP 的 is_listening() 现在是 is_bound()。

• PacketPeerUDP 的 listen() 现在是 bind()。

• ParticleProcessMaterial 的 set_flag() 现在是 set_particle_flag()。

• PhysicsTestMotionResult2D的 get_motion() 现在是 get_travel()。

• RenderingServer的 get_render_info() 更名为 get_rendering_info()。

• ResourceFormatLoader 的 get_dependencies() 现在是 _get_dependencies()（注意前面的下划线表示虚方法）。

• ResourceFormatLoader 的 load() 更名为 _load()。

• SceneTree 中的 change_scene() 现改为 change_scene_to_file()。

• Shortcut 中的 is_valid() 现改为 has_valid_event()。

• TileMap 中的 map_to_world() 现改为 map_to_local()。

• TileMap 中的 world_to_map() 现改为 local_to_map()。

• Transform2D 中的 xform() 改成了 mat * vec，xform_inv() 改成了 vec * mat。

• XRPositionalTracker的 get_name() 更名为 get_tracker_name()。

• XRPositionalTracker 的 get_type() 更名为 get_tracker_type()。

• XRPositionalTracker的 _set_name() 更名为 get_tracker_name()。

属性

备注

如果此处列出了属性，则要在项目中使用，必须手动重命名其关联的 getter 和 setter 方法。例如， PathFollow2D 和 PathFollow3D 的 set_offset() 和 get_offset() 必须分别重命名为 set_progress() 和 get_progress()。

• AudioServer 的 device 现在改为 output_device。

• BaseButton 的 group 现在改为 button_group。

• Camera3D 的 zfar 现在改为 far。

• Camera3D 的 znear 现在改为 near

• Control 的 margin 现在改为 offset。

• InputEventMouseButton 的 doubleclick 现在改为 double_click。

• InputEventWithModifiers 的 alt 现在改为 alt_pressed。

• InputEventWithModifiers 的 command 现在改为 command_pressed。

• InputEventWithModifiers 的 control 现在改为 ctrl_pressed。

• InputEventWithModifiers 的 meta 现在改为 meta_pressed。

• InputEventWithModifiers 的 shift 现在改为 shift_pressed。

• Label 的 percent_visible 现在改为 visible_ratio。

• MultiPlayerAPI 的 refuse_new_network_connections 现在改为 refuse_new_connections。

• Node 的 filename 现在改为 scene_file_path。

• PathFollow2D 的 rotate 现在改为 rotates。

• PathFollow2D 和 PathFollow3D 的 offset 现在改为 progress。

• RectangleShape2D 的 extents 现在改为 size

• TextureProgressBar 的 percent_visible 现在改为 show_percentage。

• Theme 的 off 现在改为 unchecked。

• Theme 的 ofs 现在改为 offset。

• Theme 的 on 现在改为 checked。

• Window 的 window_title 现在改为 title。

• WorldMarginShape2D 的 d 现在改为 distance。

• CSG 节点和 VoxelGI 上的 extents 属性必须被替换成 size，并且将设置的值减半（因为它们不再是半个范围了）。这也同样影响它的 setter/getter 方法，set_extents() 和 get_extents()。

• Engine.editor_hint 属性被移除以支持 Engine.is_editor_hint() 方法 。这是由于它是只读的，而 Godot 中属性不可用于只读的值。

枚举

• CPUParticles2D 中的 FLAG_MAX 现在为 PARTICLE_FLAG_MAX。

信号

• FileSystemDock中的 instantiate 现在为 instance。

• CanvasItem 中的 hide 现在是 hidden 。 这种重命名不适用于 hide() 方法，仅适用于信号。

• Tween 中的 tween_all_completed 现在为 loop_finished。

• EditorSettings 中的 changed 现在为 settings_changed。

常量

• Color 中的所有属性现在均为大写并由下划线来分割。例如，Color.palegreen 现在为 Color.PALE_GREEN。

• Mainloop的 Notification_ 常量被复制到 Node ，这意味着你可以在引用它们时移除 Mainloop. 前缀。

• MainLoop 中的 NOTIFICATION_WM_QUIT_REQUEST 现在为 NOTIFICATION_WM_CLOSE_REQUEST。

检查项目设置

数个项目设置已被重命名，其中一些项目以不兼容的方式（例如阴影滤波质量 shadow filter quality ）改变了枚举。这意味着你可能需要再次设置一些项目设置的值。确保在项目设置对话框中启用了 高级 切换选项，以便你可以看到所有项目设置。

检查环境设置

图形质量设置已从环境属性转移到项目设置。这样做是为了使运行时质量调整更加容易，而无需访问当前活动的环境资源再去修改其属性。

因此，你必须在项目设置中配置环境质量设置，因为旧的环境质量设置并不会自动转换为项目设置。

在 Godot 3.x 中，如果你在图形设置菜单中更改了环境属性，则必须更改相关的代码来调用 RenderingServer 中能影响环境效果质量的方法。只有每个环境效果的“基本”切换及其视觉旋钮保留在环境资源中。

更新着色器

着色器有一些变更未包含在升级工具中。你可能需要手动进行一些修改，特别是当你的着色器使用了坐标空间变换或自定义的 light() 函数时。

不在支持后缀为 .shader 的文件，你需要把后缀为 .shader 的文件重命名为 .gdshader 并且在 场景/资源 设置中重新引用。

在着色器中你可能需要作出的调整：

• 纹理过滤和重复模式现在在单独的 uniform 上设置，而不是在纹理文件本身。

• hint_albedo 现在是 source_color。

• hint_color 现在是 source_color。

• 内置矩阵变量已重命名。

• 粒子着色器不再使用 vertex() 处理器函数。使用 start() 和 process() 来代替它。

• 在 Forward+ 和 Mobile 渲染器中，归一化设备坐标（NDC）的 Z 范围现在为 [0.0, 1.0]，而非原来的 [-1.0, 1.0]。 在从 SCREEN_UV 和深度值重建 NDC 时，应使用 vec3 ndc = vec3(SCREEN_UV * 2.0 - 1.0, depth); 而不是 vec3 ndc = vec3(SCREEN_UV, depth) * 2.0 - 1.0;。 兼容性（Compatibility）渲染器保持不变，其 NDC 的 Z 范围与 Godot 3.x 相同。

• 光照模型已更改。如果你的着色器有自定义的 light() 函数，可能需要进行调整才能获得相同的视觉效果。

• 在 4.3 及以上版本中，反向 Z 深度缓冲技术被实现了，这可能会破坏高级着色器。请参阅 Introducing Reverse Z (AKA I'm sorry for breaking your shader)。

详见 着色语言。

这份列表并非详尽无遗。如果你已作出了这里提到的所有更改，但着色器仍无法正常工作，尝试在 Godot 社区论坛 中寻求帮助.

更新脚本时将向后不兼容的更改考虑在内

Godot 3.x 和 4 之间的一些变化并没有重新命名，但由于默认行为的不同，它们仍然会破坏向后兼容性。

最显著的例子如下：

• _ready() 和 _process() 等生命周期函数不再隐式调用同名的父类函数。相反，你必须在子类中的生命周期函数的顶部使用 super() 以调用父类中的这些生命周期函数。

• String 和 StringName 现在都暴露给了GDScript，这使优化成为可能，因为 StringName 是专门为“常量”字符串设计的，这些字符串创建一次后可能会重复使用多次。String 与 StringName 类型严格来说并不等同，这意味着 is_same("example", &"example") 会返回 false。虽然在大多数情况下它们可以互换（"example" == &"example" 返回 true），但是有时候你可能需要使用 &"example" 来替换 "example"。

• GDScript 的 setter 和 getter 语法 已经发生了变化，但是转换工具仅对其进行了部分转换，在大多数情况下，需要手动更改才能使 setter 和 getter 重新工作。

• GDScript 信号连接语法已被更改。转换工具将使用 Godot 4 中仍然存在的基于字符串的语法，但建议改用链接页面中描述的基于 Signal 的语法。通过这种方式，就不会在信号连接中涉及字符串，从而避免了只能在运行时发现的信号名称错误问题。

• 作为 tool scripts 的内置脚本不会将 tool 关键字转换为 @tool 注解。

• Tween 节点已经被移除，取而代之的是在 Godot 3.5 及更高的版本中可用的 Tweeners。详情参见原始拉取要求。

• randomize() 现在会在项目加载时自动调用，因此使用全局 RandomNumberGenerate 实例进行确定性随机化需要在脚本的 _ready() 函数中手动设置种子。

• call_group() 、 set_group() 和 notify_group() 现在默认为立即调用。如果在包含大量节点的组中调用代价高昂的函数可能会导致卡顿。要像以前一样使用延迟调用，请将 call_group(...) 替换为 call_group_flags(SceneTree.GROUP_CALL_DEFERRED, ...) （并分别对 set_group() 和 notify_group() 也进行类似的替换）。

• 现在编辑器中的 rotation 属性取代了旧有的 rotation_degrees 属性，在检查器面板中，它会自动显示为度。这可能会破坏动画，因为转换工具无法自动处理转换。

• AABB 的函数 has_no_surface() 被反转并重命名为了 has_surface()。

• AABB 及 Rect2 的 函数 has_no_area() 被反转并重命名为了 has_area()。

• AnimatedTexture 的 fps 属性被 speed_scale 属性取代，其作用与 AnimationPlayer 的 playback_speed 属性相同。

• AnimatedSprite2D 和 AnimatedSprite3D 现在允许设置负的 speed_scale 值。如果你过去的工作依赖于 speed_scale 属性在内部被限位为 0.0 ， 现在这可能会破坏动画。

• AnimatedSprite2D 和 AnimatedSprite3D 的 playing 属性现在已经被移除。请使用 play()/stop() 方法来代替或者通过 SpriteFrames 底部面板配置 autoplay 动画（但不能同时使用这两种方法）。

• Array 的 slice() 第二个参数（ end ）现在是 不包含的 ，而非包含的。例如，这意味着 [1, 2, 3].slice(0, 1) 现在返回 [1] 而不是 [1, 2]。

• BaseButton 的信号现在是 button_up 和 button_down。pressed 属性也改为了 button_pressed。

• Camera2D 的属性 rotating 现在被 ignore_rotation 所取代，而后者的行为是相反的。

• Camera2D 的 zoom 属性被反转：现在该属性的值越大，缩放越大，而并非之前的缩放越小。

• Node 的 remove_and_skip() 方法现在已经被移除，如果你需要在脚本中重新实现该方法，可以使用旧的 C++ 实现作为参考。

• OS.get_system_time_secs() 现在应该改写为 Time.get_time_dict_from_system()["second"]。

• ResourceSaver 的 save() 方法的参数现在交换了位置（ resource: Resource, path: String ）。这也适用于 ResourceFormatSaver 的 _save() 方法。

• StreamPeerTCP 必须依靠其中的 poll() 来更新状态，而不能依赖于 get_status() 自动轮询：GH-59582

• String 的 right() 方法 改变了行为：它现在返回字符串右边的字符数，而不是从给定位置开始返回字符串右边的字符数。如果需要旧的功能，可以使用 substr() 来代替。

• 根据 GH-59582，StreamPeerTCP 和 PacketPeerUDP 当中的 is_connected_to_host() 现已被删除。可在 StreamPeerTCP 当中使用 get_status() 来代替，在 PacketPeerUDP 则可以使用 is_socket_connected()。

• 在 _get_property_list() 中，or_lesser 这个属性提示字符串被更改为了 or_less。

• 在 _get_property_list() 中，noslider 这个属性提示字符串被改成了 no_slider。

• VisualShaderNodeVec4Parameter 现在使用 Vector4 作为参数，而不再使用 Quaternion。

已移除或已替换的节点/资源

这将列出所有需要被另一个不同配置的节点替换掉的那些节点。由于项目转换器不支持更新现存设置，因此必须从头开始设置：

移除节点	最接近的等价物	注释
AnimationTreePlayer	AnimationTree	AnimationTreePlayer 从 Godot 3.1 起弃用。
BakedLightmap	LightmapGI	见 使用光照贴图全局照明。
BakedLightmapData	LightmapGIData
BitmapFont	FontFile	见 使用字体。
DynamicFont	FontFile
DynamicFontData	FontFile
ClippedCamera	Camera2D 或 Camera3D	相机的金字塔形状已移至 Camera3D。
InterpolatedCamera	Camera2D 或 Camera3D
Navigation2D	Node2D	由其他 2D 导航节点代替。
Navigation3D	Node3D	由其他 3D 导航节点代替。
OpenSimplexNoise	FastNoiseLite	参数不同，额外提供了蜂窝等不同类型的噪声。不支持 4D 噪声，因为 FastNoiseLite 库中没有提供。
ToolButton	Button	ToolButton 是默认启用 Flat 属性的 Button。
YSort	Node2D 或 Control	4.0 中的 CanvasItem 新增了 Y Sort Enabled 属性。
ProximityGroup	Node3D	VisibleOnScreenNotifier3D 可以作为替代品。
Portal	Node3D	入口与房间遮挡剔除换成了光栅遮挡剔除（OccluderInstance3D 节点），设置流程不同。
Room	Node3D
RoomManager	Node3D
RoomGroup	Node3D
Occluder	Node3D	几何体遮挡剔除换成了光栅遮挡剔除（OccluderInstance3D 节点），设置流程不同。
OccluderShapeSphere	资源

如果加载一个旧版本项目，项目中的节点将自动替换为其 最近似值（即使没有使用项目升级工具）。

改变线程

Threading 的API在 4.0 当中发生了变化。例如：Godot 3.x 中的以下代码片段必须修改后才能在 4.0 当中运行：

# 3.x
var start_success = new_thread.start(self, "__threaded_background_loader",
    [resource_path, thread_num]
)

# 4.0
var start_success = new_thread.start(__threaded_background_loader.bind(resource_path, thread_num))

Thread.is_active() 已经不再使用，应该使用 Thread.is_alive() 来代替它。

参见

有关 Godot 3.x 和 4 之间的完整变化列表，请参见 更新日志。

ArrayMesh 资源不兼容问题

如果在旧版本项目中你已经将 ArrayMesh 资源保存为了 .res 或者 .tres 文件，由于 4.0 中使用的格式与 3.x 中使用的格式不兼容，那么你需要再次导入源网格文件并将其保存为 ArrayMesh 资源。

自动重命名方法、属性、信号、常量列表

editor/renames_map_3_to_4.cpp 源文件列出了项目升级工具执行的所有自动重命名。注释掉的行指的是 不能自动执行的 API重命名。

移植编辑器设置

Godot 3.x 和 4.0 使用不同的编辑器设置文件。这意味着它们的设置可以相互独立更改。

如果你希望将 Godot 3.x 的设置移植到 Godot 4 ，请打开 编辑器设置文件夹，并在 Godot 4 编辑器关闭时复制 editor_settings-3.tres 到 editor_settings-4.tres。

备注

自 Godot 3.x 版本以来，许多设置的名称和类别都发生了变化。名称或类别发生变化的编辑器设置不会延续到 Godot 4.0，你必须重新设置它们的值。

更新版本控制设置

Godot 3.x 和 4.x 各自拥有完全不同的文件和文件夹列表，这些内容应被你的 version control system 忽略。