從 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 依需求啟用。