Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

從 Godot 4.3 升級到 Godot 4.4

對於大多數以 4.3 製作的遊戲與應用程式，遷移到 4.4 應該相對安全。此頁面旨在涵蓋專案遷移時需要留意的所有事項。

做出更改

如果你要從 4.3 遷移到 4.4，這裡列出的不相容變更可能會影響到你。變更依領域/系統分類整理。

這篇文章指出了每項破壞性改動是否會影響 GDScript，以及 C# 的破壞性改動是 二進位相容 還是 原始程式碼相容：

• 二進位相容 - 現有二進位檔可在無需重新編譯的情況下成功載入與執行，且執行時行為不會改變。

• ** 原始程式碼相容** —— 在升級 Godot 時，原始程式碼可成功編譯，無需更改。

核心

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
FileAccess
方法 open_encrypted 新增了可選參數 iv	✔️	✔️	✔️	GH-98918
方法 store_8 的回傳型別由 void 改為 bool	✔️	❌	✔️	GH-78289
方法 store_16 的回傳型別由 void 改為 bool	✔️	❌	✔️	GH-78289
方法 store_32 的回傳型別由 void 改為 bool	✔️	❌	✔️	GH-78289
方法 store_64 的回傳型別由 void 改為 bool	✔️	❌	✔️	GH-78289
方法 store_buffer 的回傳型別由 void 改為 bool	✔️	❌	✔️	GH-78289
方法 store_csv_line 的回傳型別由 void 改為 bool	✔️	❌	✔️	GH-78289
方法 store_double 的回傳型別由 void 改為 bool	✔️	❌	✔️	GH-78289
方法 store_float 的回傳型別由 void 改為 bool	✔️	❌	✔️	GH-78289
方法 store_half 的回傳型別由 void 改為 bool	✔️	❌	✔️	GH-78289
方法 store_line 的回傳型別由 void 改為 bool	✔️	❌	✔️	GH-78289
方法 store_pascal_string 的回傳型別由 void 改為 bool	✔️	❌	✔️	GH-78289
方法 store_real 的回傳型別由 void 改為 bool	✔️	❌	✔️	GH-78289
方法 store_string 的回傳型別由 void 改為 bool	✔️	❌	✔️	GH-78289
方法 store_var 的回傳型別由 void 改為 bool	✔️	❌	✔️	GH-78289
OS
方法 execute_with_pipe 新增了可選參數 blocking	✔️	✔️	✔️	GH-94434
方法 read_string_from_stdin 新增了 buffer_size 參數 [1]	❌	✔️	✔️	GH-91201
RegEx
方法 compile 新增了可選參數 show_error	✔️	✔️	✔️	GH-95212
方法 create_from_string 新增了可選參數 show_error	✔️	✔️	✔️	GH-95212
Semaphore
方法 post 新增了可選參數 count	✔️	✔️	✔️	GH-93605
TranslationServer
方法 standardize_locale 新增了可選參數 add_defaults	✔️	✔️	✔️	GH-98972

匯出註解

警告

Godot 4.4 更動了 @export_file 的行為。當在屬性面板指派新值時，路徑現在會以 uid:// 參照儲存與回傳，而非傳統的 res:// 路徑（GH-97912）。這是 破壞性變更，若你的腳本或序列化檔案預期使用基於 res:// 的路徑，可能會造成問題。

例如，匯出的檔案陣列現在可能同時包含 uid:// 與 res:// 路徑，特別是在它們曾部分於屬性面板中編輯過的情況下。

在 4.4 中，保留 res:// 格式的唯一方法是以文字編輯器 手動編輯 .tscn 或 .tres 檔案。從 Godot 4.5 起，可使用新的註解 @export_file_path 來明確保留舊行為並匯出原始的 res:// 路徑。

[1]

4.3 的預設緩衝區大小為 1024。

建立節點

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
RichTextLabel
方法 push_meta 新增了可選參數 tooltip	✔️	✔️	✔️	GH-99481
方法 set_table_column_expand 新增了可選參數 shrink	✔️	✔️	✔️	GH-101482
圖形編輯器（GraphEdit）
方法 connect_node 新增了可選參數 keep_alive	✔️	✔️	✔️	GH-97449
訊號 frame_rect_changed 的參數 new_rect 型別由 Vector2 改為 Rect2	❌	❌	❌	GH-102796

物理

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
SoftBody3D
方法 set_point_pinned 新增了可選參數 insert_at	✔️	✔️	✔️	GH-94684

算繪

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
CPUParticles2D
方法 restart 新增了可選參數 keep_seed	✔️	✔️	✔️	GH-92089
CPUParticles3D
方法 restart 新增了可選參數 keep_seed	✔️	✔️	✔️	GH-92089
GPUParticles2D
方法 restart 新增了可選參數 keep_seed	✔️	✔️	✔️	GH-92089
GPUParticles3D
方法 restart 新增了可選參數 keep_seed	✔️	✔️	✔️	GH-92089
算繪
方法 draw_list_begin 新增了可選參數 breadcrumb	✔️	✔️	✔️	GH-90993
方法 draw_list_begin 移除了多個參數	❌	✔️	✔️	GH-98670
方法 index_buffer_create 新增了可選參數 enable_device_address	✔️	✔️	✔️	GH-100062
方法 uniform_buffer_create 新增了可選參數 enable_device_address	✔️	✔️	✔️	GH-100062
方法 vertex_buffer_create 新增了可選參數 enable_device_address	✔️	✔️	✔️	GH-100062
RenderingServer
方法 multimesh_allocate_data 新增了可選參數 use_indirect	✔️	✔️	✔️	GH-99455
Shader
方法 get_default_texture_parameter 的回傳型別由 Texture2D 改為 Texture	✔️	❌	❌	GH-95126
方法 set_default_texture_parameter 的 texture 參數型別由 Texture2D 改為 Texture	✔️	❌	✔️	GH-95126
VisualShaderNodeCubemap
屬性 cube_map 的型別由 Cubemap 改為 TextureLayered	✔️	❌	❌	GH-95126
VisualShaderNodeTexture2DArray
屬性 texture_array 的型別由 Texture2DArray 改為 TextureLayered	✔️	❌	❌	GH-95126

備註

在 C# 中，列舉 RenderingDevice.StorageBufferUsage 因綁定產生器判定列舉前綴的方式而出現相容性破壞。GH-100062 新增了成員，導致列舉成員被重新命名。

導覽

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
導覽網格
方法 query_path 新增了可選參數 callback	✔️	✔️	✔️	GH-100129
導覽網格
方法 query_path 新增了可選參數 callback	✔️	✔️	✔️	GH-100129

編輯器外掛程式

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
編輯器界面 (C++)
方法 open_scene_from_path 新增了可選參數 set_inherited	✔️	✔️	✔️	GH-90057
方法 popup_node_selector 新增了可選參數 current_value	✔️	✔️	✔️	GH-94323
方法 popup_property_selector 新增了可選參數 current_value	✔️	✔️	✔️	GH-94323
EditorSceneFormatImporter
方法 _get_import_flags 已移除	❌	❌	❌	GH-101531
EditorTranslationParserPlugin
方法 _parse_file 的回傳型別改為 Array，並移除了參數 msgids 與 msgids_context_plural	❌	❌	❌	GH-99297

備註

方法 _get_import_flags 從未被引擎使用。雖然會造成相容性破壞，但因為使用者無法依賴此方法來影響引擎行為，因此予以移除。

做出更改

核心

備註

Curve 資源現在會強制套用其數值範圍，因此如果任何節點超出預設的 [0, 1] 範圍，就需要調整 min_value 與 max_value。

算繪

備註

VisualShaderNodeVec4Constant 著色器節點的輸入型別已改為 Vector4。使用者需要重新建立其常數中的數值。

CSG

備註

CSG 的實作現在改用 Emmett Lalish 的 Manifold 程式庫（GH-94321）。新的實作更符合流形的定義，並修正了多項錯誤與穩定性問題。因此，不再支援非流形網格。你可以使用 MeshInstance3D 來繪製非流形幾何（例如四邊形或平面）。

Android

備註

Android 感測器事件不再預設啟用（GH-94799）。使用感測器事件的專案可於專案設定的 Input Devices > Sensors 依需求啟用。