Up to date

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

從 Godot 3 升級到 Godot 4

我應該升級到 Godot4 嗎？

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

升級的優點

在這份文件之外，你可能也會想看看 Godot 的 demo 專案。

• 許多問題已經在4.0進行了修復，但是由於各種各樣的原因（例如不同的圖形API以及向後相容性等），這些問題無法在3.x版本中修復。

• 4.x 版本將享受更長的:ref:支援週期 <doc_release_policy>。Godot 3.x 也將在 4.0 發行之後支援一段時間，但最終將會放棄支援。

記錄 Godot 4.0 中新功能的文件頁面列表見 PopupMenu。

升級的缺點

如果你*不需要* Godot 4.0 中的功能，留在 Godot 3.x 中可能有如下原因：

• Godot 3.x 是身經百戰了，而 Godot 4 還太年輕。

  • Godot 4.0 應該會有一些工作流和性能問題，在 Godot 3.x 中則沒有對應的問題。這些問題會在後續的 Godot 4.x 版本中陸續解決。

• Godot 4 的協力廠商教學比 Godot 3.x 要少。如果你是遊戲引擎小白，使用 Godot 3.x 的體驗會絲滑很多。

• Godot 4 的基準硬體需求要稍高一些（例如記憶體佔用），無論是編輯器還是匯出後的專案。這些都是實作核心優化所必須的。

• 由於 Godot 4 比 Godot 3 包含更多的功能，Godot 4 匯出的專案二進位檔案相比更大。這個問題可以通過:ref:`針對大小優化建構 <doc_optimizing_for_size>`來緩解，但是啟用模組相同的前提下，4.0 建構的大小仍然會比 3.x 建構要大。:ref:`為 Web 匯出 <doc_exporting_for_web>`時可能會造成一些問題，因為二進位檔案的大小對引擎初始化的速度有直接影響（不考慮下載速度）。

• Godot 4 不支援且不會提供對 GLES2 算繪器的支援。（使用新的 OpenGL 後臺，Godot依然支援 GLES3 算繪器，這意味著不支援Vulkan的裝置依舊可以運作Godot 4。）

  • 如果你的目標是像 Intel Sandy Bridge（第二代）集成圖形一樣**極其**老舊的硬體，升級後將阻止專案在此類硬體上運作。`軟體 OpenGL 實作 <https://github.com/pal1000/mesa-dist-win>`__可以用來繞過這個限制，但對於遊戲來說太慢了。

升級的注意事項

**由於 Godot 4 在許多方面都是完全重寫的，一些功能在這個過程中不幸地丟失了。**其中一些功能可能會在未來的 Godot 版本中恢復：

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

• By default, rendering in 2D is no longer performed in HDR, which means "overbright" modulate values have no visible effect. Since Godot 4.2, you can enable the project setting HDR 2D to perform 2D rendering in HDR. See also Using glow in 2D.

• 雖然使用 Forward Plus 或 Forward Mobile 後端時，算繪仍然會以 3D HDR 形式進行，但視口無法再返回 HDR 資料。 計畫在未來某個時候恢復這一功能。

• Mono was replaced by .NET 6. This means exporting C# projects to Android, iOS and HTML5 is no longer supported for now. Exporting C# projects to desktop platforms is still supported, and as of 4.2 there's experimental support for exporting to mobile platforms. Support for exporting C# projects to more platforms will be restored in future 4.x releases as upstream support improves.

在 GitHub 上搜尋有 junior jobs (或十月時的 Hacktoberfest) 標籤的 Issue 是個不錯的開始。

準備專案

如果你想在未來升級到 Godot 4，可以考慮在你的專案中使用 Tweener 和 Time 單例。這些類在 Godot 3.5 及更高版本中都已可用。

如此，你便不用再依賴已放棄使用的 Tween node 和 OS time 函式，這兩個函式在 Godot 4.0 中都被刪除了。

使用 .gdshader 後綴來替換 .shader 後綴是一個很好的點子。Godot 3.x 支援這兩種後綴，但 Godot 4.0 僅支援 .gdshader 這一種。

設定專案路徑

警告

升級前，請將顯示進行完整備份！專案升級工具*不會*對升級的專案進行備份。

你可以使用版本控制備份專案，也可以將專案檔案夾複製到其他位置。

專案管理員

設定專案路徑

1. 專案管理員

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）
動畫	AnimatedSprite2D
相機	相機
Control	Control
ARVRAnchor	XRAnchor3D
ARVRInterface	使用者介面 (UI)
ARVROrigin	XROrigin3D
ARVRPositionalTracker	XRPositionalTracker
ARVRServer	XRServer
CubeMesh	網格
編輯器使用手冊	EditorNode3DGizmo
doc_spatial_gizmo_plugins	EditorNode3DGizmoPlugin
GIProbe	VoxelGI
GIProbeData	VoxelGIData
匯入紋理	匯入紋理
動力學形體。	CharacterBody3D
KinematicBody2D	CharacterBody2D
光照	PointLight2D
LineShape2D	WorldBoundaryShape2D
Listener	AudioListener3D
導覽網格	導覽
導覽	導覽
導覽	導覽
PanoramaSky	天空
粒子	粒子
粒子	粒子
ParticlesMaterial	ParticleProcessMaterial
Physics2DDirectBodyState	PhysicsDirectBodyState2D
Physics2DDirectSpaceState	PhysicsDirectSpaceState2D
物理	物理
Physics2DShapeQueryParameters	PhysicsShapeQueryParameters2D
Physics2DTestMotionResult	PhysicsTestMotionResult2D
平面	WorldBoundaryShape3D
Condition 條件	Marker2D
Condition 條件	Marker3D
程式性天空。	天空
RayShape	SeparationRayShape3D
RayShape2D	SeparationRayShape2D
ShortCut	快捷鍵
Spatial	Node2D
Spatial	Node3DGizmo
材質	StandardMaterial3D
Sprite	Sprite2D
紋理貼圖	壓縮模式
紋理貼圖	TextureProgressBar
設定 Godot	VideoStreamPlayer
ViewportContainer	建立內容
檢視區	檢視區
VisibilityNotifier2D	VisibleOnScreenEnabler3D
VisibilityNotifier	VisibleOnScreenNotifier3D
VisibilityNotifier2D	VisibleOnScreenNotifier2D
VisibilityNotifier3D	VisibleOnScreenNotifier3D
視覺腳本 (VisualScript)	算繪
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()``（注意前面的底線，表示虛方法）。

• AStar2D和AStar3D的``get_points()``現在改為``get_points_id()``。

• BaseButton的``set_event()``現在改為``set_shortcut()``。

• Camera2D的``get_v_offset()``現在改為``get_drag_vertical_offset()``。

• Camera2D的``set_v_offset()``現在改為``set_drag_vertical_offset()``。

• CanvasItem的``update()``現在改為``queue_redraw()``。

• 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的``world_to_map()``現在改為``local_to_map()``。

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

• Image的 get_rect() 方法現在為 get_region() 。

• 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()。

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

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

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

• ResourceFormatLoader 的 get_dependencies() 現在是 ``_get_dependencies()``（注意前面的底線表示虛方法）。

• SceneTree 中的 change_scene() 現改為 change_scene_to_file()。

• Shortcut 中的 is_valid() 現改為 has_valid_event()。

• TileMap 中的 world_to_map() 現改為 local_to_map() 。

• TileMap 中的 map_to_world() 現改為 map_to_local() 。

• Transform2D's xform() is mat * vec and xform_inv() is vec * mat.

屬性。

備註

如果此處列出了屬性，則要在專案中使用，必須手動重命名其關聯的 getter 和 setter 方法。例如， PathFollow2D 和 PathFollow3D 的 set_offset() 和 get_offset() 必須分別重命名為 set_progress() 和 get_progress() 。

• Control 中的 margin 現改為 offset。

• Label 中的 percent_visible 現改為 visible_ratio。

• MultiPlayerAPI 中的 refuse_new_network_connections 現改為 refuse_new_connections。

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

• TextureProgressBar 中的 percent_visible 現改為 show_percentage。

• 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 中能影響環境效果品質的方法。只有每個環境效果的“基本”切換及其視覺旋鈕保留在環境資源中。

更新著色器

There have been some changes to shaders that aren't covered by the upgrade tool. You will need to make some manual changes, especially if your shader uses coordinate space transformations or a custom light() function.

不在支援後綴為 .shader 的檔，你需要把後綴為 .shader 的檔重命名為 .gdshader 並且在 場景/資源 設定中重新引用。

Some notable changes you will need to perform in shaders are:

• 紋理篩選和重複模式現在在單獨的 uniform 上設定，而不是在紋理檔本身。

• hint_albedo 現在是 source_color。

• hint_color is now source_color.

• Spatial 著色器

• 粒子著色器不再使用 vertex() 處理器函式。使用 start() 和 process() 來代替它。

• In the Forward+ and Mobile renderers, normalized device coordinates now have a Z-range of [0.0,1.0] instead of [-1.0,1.0]. When reconstructing NDC from SCREEN_UV and depth, use vec3 ndc = vec3(SCREEN_UV * 2.0 - 1.0, depth); instead of vec3 ndc = vec3(SCREEN_UV, depth) * 2.0 - 1.0;. The Compatibility renderer is unchanged, using the same NDC Z-range as 3.x.

• The lighting model changed. If your shader has a custom light() function, you may need to make changes to get the same visual result.

• In 4.3 and up, the reverse Z depth buffer technique is now implemented, which may break advanced shaders. See Introducing Reverse Z (AKA I'm sorry for breaking your shader).

更多資訊請參考 匯出專案 。

This list is not exhaustive. If you made all the changes mentioned here and your shader still doesn't work, try asking for help in one of the community channels.

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

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 訊號連接語法 <doc_gdscript_signals>`已經做了改動。轉換工具將使用 Godot 4 中仍然存在的基於字串的語法，但建議改用連結頁面中描述的基於 :ref:`class_Signal 的語法。通過這種方式，就不會在訊號連接中涉及字串，從而避免了只能在運作時發現的訊號名稱錯誤問題。

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

• Tween 節點已經被移除，取而代之的是在 Godot 3.5 及更高的版本中可用的 Tweeners。詳情請參見 original pull request <https://github.com/godotengine/godot/pull/41794> 。

• 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's slice() second parameter (end) is now exclusive, instead of being inclusive. For example, this means that [1, 2, 3].slice(0, 1) now returns [1] instead of [1, 2].

• BaseButton 的訊號現在是 button_up 和 button_down 。 pressed 屬性也改為了 button_pressed 。

• Camera2D 的屬性 rotating 現在被 ignore_rotation 所取代，而後者的行為是相反的。

• Camera2D 的 zoom 屬性被反轉：現在該屬性的值越大，縮放越大，而並非之前的縮放越小。

• Node 的 remove_and_skip() 方法現在已經被移除，如果你需要在腳本中重新實作該方法，可以使用 old C++ implementation <https://github.com/godotengine/godot/blob/7936b3cc4c657e4b273b376068f095e1e0e4d82a/scene/main/node.cpp#L1910-L1945> __ 作為參考。

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

已移除或已替換的節點/資源

這將列出所有需要被另一個不同配置的節點替換掉的那些節點。由於專案轉換器不支援更新現存設定，因此必須從頭開始設定：

刪除節點 (-noimp)	類別宣告	Comment 註解
AnimationTreePlayer	動畫樹	AnimationTreePlayer 從 Godot 3.1 起廢棄。
BakedLightmap	LightmapGI	使用 MultiMesh 進行優化
BakedLightmapData	LightmapGIData
BitmapFont	篩選檔案	使用容器
動態語言：	篩選檔案
動態性	篩選檔案
導覽	Node2D	由:ref:`其他 2D 導覽節點 <doc_navigation_overview_2d>`代替。
導覽	Node2D	由:ref:`其他 3D 導覽節點 <doc_navigation_overview_3d>`代替。
OpenSimplexNoise	FastNoiseLite	參數不同，額外提供了蜂窩等不同型別的雜訊。不支援 4D 雜訊，因為 FastNoiseLite 庫中沒有提供。
按鈕。	按鈕	ToolButton 是預設啟用 Flat 屬性的 Button。
YSort	Flow Control 流程控制	4.0 中的 CanvasItem 新增了 Y Sort Enabled 屬性。
ProximityGroup	Node2D	VisibleOnScreenNotifier3D 可以作為替代品。
連接埠	Node2D	入口與房間遮擋剔除換成了光柵:ref:`遮擋剔除 <doc_occlusion_culling>`（OccluderInstance3D 節點），設定流程不同。
房間	Node2D
專案管理員	Node2D
群組	Node2D
遮擋模式	Node2D	幾何體遮擋剔除換成了光柵:ref:`遮擋剔除 <doc_occlusion_culling>`（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 之間的完整變化列表，請參見 更新紀錄 <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，您必須重新設定它們的值。