從 Godot 3 升級到 Godot 4

我應該升級到 Godot4 嗎？

在開始升級之前，有必要考慮一下升級會給你的專案帶來的優點和缺點。

升級的優點

除了 Godot 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 建置版本仍然會比較大。這對於 匯出至網頁 來說可能是一個問題，因為二進制檔案大小直接影響引擎初始化的速度（無論下載速度如何）。

• Godot 4 沒有也不會有 GLES2 算繪支援。（新的相容性算繪器仍然支援 GLES3 算繪，這表示沒有 Vulkan 支援的裝置仍然可以運行 Godot 4。）

  • 如果你的目標設備為 Intel Sandy Bridge（第二代）集成顯示等**極舊硬體**，升級後專案將無法在這些硬體上執行。雖然可以使用 軟體 OpenGL 實作 來繞過限制，但速度對遊戲來說過慢。

升級的注意事項

由於 Godot 4 在許多面向皆為完全重寫，因此部分功能於此過程中不幸遺失。 這些功能有些可能會在未來的 Godot 版本中恢復：

• Bullet 物理引擎被移除以支援 GodotPhysics。這只會影響使用預設物理引擎（即 Bullet）且沒有手動更改為 GodotPhysics 的3D專案。沒有在核心中重新新增 Bullet 物理引擎的計畫，但由於 GDExtension，可以為其建立協力廠商附加元件。

• 預設情況下，2D 算繪不再以 HDR 執行，這表示「過亮」的 modulate 值不再有可見的效果。從 Godot 4.2 開始，您可以啟用專案設定 HDR 2D 以執行 2D HDR 算繪。另請參閱 在 2D 中使用發光。

• 雖然在使用 Forward+ 或行動算繪器時，3D 場景的算繪仍然以 HDR 進行，但 Viewport 無法再回傳 HDR 資料。此功能計畫在未來某個時間點恢復。

• Mono 已被 .NET 6 取代。這表示目前不再支援將 C# 專案匯出至 Android、iOS 和 HTML5 平台。匯出 C# 專案至桌上型平台仍然受到支援，且自 4.2 版本起，已提供實驗性支援匯出至行動平台。對更多平台匯出 C# 專案的支援將在未來的 4.x 版本中恢復，並隨著上游支援的改善而進一步完善。

你可以在 GitHub 上搜尋 標記為「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
監聽器	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 <https://github.com/chmln/sd>`__ 等命令列工具。

如果使用 C#，請記住在專案中使用 PascalCase 標記法（即帕斯卡命名法）搜索過時的 API 使用情況（並使用 PascalCase 標記法執行替換）。

方法

• 檔和目錄類已被 FileAccess 與 DirAccess 取代，它們擁有完全不同的 API。現在有幾種方法是靜態的，這意味著你可以不建立物件而直接使用 FileAccess 或 DirAccess 的方法。

• OS 單例中與螢幕和視窗相關的方法（例如 OS.get_screen_size()）已被移至 DisplayServer 單例。方法命名也改為使用 DisplayServer.<物件>_<get/set>_property() 的形式。例如，OS.get_screen_size() 變成了 DisplayServer.screen_get_size()。

• 時間和日期方法已從 OS 單例移動至 Time 單例。（ 在Godot 3.5 以及其後的版本中依舊如此。）

• 你可能需要將一些``instance()``呼叫替換為``instantiate()``。轉換器*應該*會自動處理這個，但這依賴於可能無法在100%的情況下工作的自訂程式碼。

• 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's 的 invert() 現在是 reverse() 。

• Array's的 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's xform() is mat * vec and xform_inv() is 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's device``現在是 ``output_device.

• BaseButton's group 現在是 button_group.

• Camera3D's zfar 現在是 far.

• Camera3D's znear``現在是 ``near

• Control 中的 margin 現改為 offset。

• InputEventMouseButton's doubleclick 現在是 double_click.

• InputEventWithModifiers's alt 現在是 alt_pressed.

• InputEventWithModifiers's command 現在是 command_pressed.

• InputEventWithModifiers's control 現在是 ctrl_pressed.

• InputEventWithModifiers's meta``現在是 ``meta_pressed.

• InputEventWithModifiers's shift 現在是 shift_pressed.

• Label 中的 percent_visible 現改為 visible_ratio。

• MultiPlayerAPI 中的 refuse_new_network_connections 現改為 refuse_new_connections。

• Node's filename 現在是 scene_file_path.

• PathFollow2D's rotate 現在是 rotates.

• PathFollow2D 和 PathFollow3D 中的 offset 現改為 progress。

• RectangleShape2D's extents 現在是 size

• TextureProgressBar 中的 percent_visible 現改為 show_percentage。

• Theme's off 現在是 unchecked.

• Theme's ofs 現在是 offset.

• Theme's on 現在是 checked.

• Window's window_title 現在是 title.

• WorldMarginShape2D's d 現在是 distance.

• CSG 節點和 VoxelGI 上的 extents``屬性必須被替換成 ``size，並且將設定的值減半（因為它們不再是半個範圍了）。這也同樣影響它的 setter/getter 方法， set_extents() 和 get_extents() 。

• Engine.editor_hint 屬性被移除以支援 Engine.is_editor_hint() 方法 。這是由於它是唯讀的，而 Godot 中屬性不可用於唯讀的值。

Enum 列舉型別

• 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 算繪器維持不變，使用與 3.x 相同的 NDC Z 範圍。

• 光照模型已變更。如果您的著色器有自訂的 light() 函式，您可能需要進行修改才能獲得相同的視覺效果。

• 在 4.3 及更新版本中，現在實作了反向 Z 深度緩衝區技術，這可能會破壞進階著色器。請參閱 Introducing Reverse Z (AKA I'm sorry for breaking your shader) 。

更多資訊請參閱 著色語言。

這份清單並未詳盡列出所有可能情況。如果您已完成此處提及的所有變更，但您的著色器仍然無法運作，請嘗試在我們的`社群管道 <https://godotengine.org/community/>`__ 尋求協助。

更新腳本時將向後不相容的更改考慮在內

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 的訊號連接語法 GDScript signal connection syntax 已變更。轉換工具將使用 Godot 4 中仍然存在的字串基礎語法，但建議切換到連結頁面中描述的 Signal 基礎語法。這樣一來，就不再涉及字串，避免了只能在運行時發現的訊號名稱錯誤問題。

• 作為 tool scripts 的內建腳本不會將 tool 關鍵字轉換為 @tool 注解。

• Tween 節點已被移除，改用 Tweeners， 在 Godot 3.5 及更新版本中也可用。詳情請參閱原始的 pull request 。

• 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) 現在是*不包含*（exclusive），而不是包含（inclusive）了。舉例來說，這表示 [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 <https://github.com/godotengine/godot/pull/59582> __

• String 的 right() 方法 改變了功能表現 <https://github.com/godotengine/godot/pull/36180> __：它現在返回字串右邊的字元數，而不是從給定位置開始返回字串右邊的字元數。如果需要舊的功能，可以使用 substr() 來代替。

• 根據 GH-59582 <https://github.com/godotengine/godot/pull/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	攝影機的金字塔形狀被移至 :ref:'class_Camera3D'.
InterpolatedCamera	Camera2D 或 Camera3D
Navigation2D	Node2D	由 other 2D Navigation nodes 代替。
Navigation3D	Node3D	由 other 3D Navigation nodes 代替。
OpenSimplexNoise	FastNoiseLite	具有不同的參數和更多雜訊類型，例如細胞雜訊。由於 FastNoiseLite 函式庫中沒有 4D 雜訊，因此不支援。
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	幾何體遮擋剔除換成了光柵 occlusion culling （OccluderInstance3D 節點），設定流程不同。
OccluderShapeSphere	Resource

如果載入舊專案，該節點會自動被其 最接近的近似值 取代（即使沒有使用專案升級工具）。

線程更改

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 之間的完整變化列表，請參見 更新紀錄 <https://github.com/godotengine/godot/blob/master/CHANGELOG.md> __。

ArrayMesh 資源不相容問題

如果在舊版本專案中你已經將 ArrayMesh 資源保存為了 .res 或者 .tres 檔，由於 4.0 中使用的格式與 3.x 中使用的格式不相容，那麼你需要再次匯入源網格檔並將其保存為 ArrayMesh 資源。

自動重命名方法、屬性、訊號、常數列表

editor/renames_map_3_to_4.cpp <https://github.com/godotengine/godot/blob/master/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 忽略的檔案與資料夾清單上完全不同。