從 Godot 4.2 升級到 Godot 4.3

對於大多數以 4.2 製作的遊戲和應用程式來說，升級到 4.3 應該相對安全。本頁將說明專案升級時需要注意的所有事項。

做出更改

如果你要從 4.2 升級到 4.3，這裡列出的不相容變更可能會影響到你的專案。變更內容依領域/系統分類整理。

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

• 二進制相容 - 現有的二進制檔案無需重新編譯即可成功載入和執行，且運行時的行為不會改變。

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

GDExtension

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
GDExtension
方法 close_library 已移除	❌	❌	❌	GH-88418
方法 initialize_library 已移除	❌	❌	❌	GH-88418
方法 open_library 已移除	❌	❌	❌	GH-88418

由於這些方法實際上無法被有效利用，因此已將其移除。請改用 GDExtensionManager::load_extension 和 GDExtensionManager::unload_extension 來正確載入與卸載 GDExtension。

動畫

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
動畫
方法 position_track_interpolate 新增了 backward 選用參數	✔️	✔️	✔️	GH-86629
方法 rotation_track_interpolate 新增了 backward 選用參數	✔️	✔️	✔️	GH-86629
方法 scale_track_interpolate 新增了 backward 選用參數	✔️	✔️	✔️	GH-86629
方法 blend_shape_track_interpolate 新增了 backward 選用參數	✔️	✔️	✔️	GH-86629
方法 value_track_interpolate 新增了 backward 選用參數	✔️	✔️	✔️	GH-86629
方法 track_find_key 新增了 limit 選用參數	✔️	✔️	✔️	GH-86661
方法 track_find_key 新增了 backward 選用參數	✔️	✔️	✔️	GH-92861
動畫混合器（AnimationMixer）
方法 _post_process_key_value 的 object 參數型別由 Object 改為 uint64	✔️	❌	❌	GH-86687
Skeleton3D
方法 add_bone 的回傳型別由 void 改為 int32	✔️	❌	✔️	GH-88791
訊號 bone_pose_changed 已被 skeleton_updated 取代	❌	❌	❌	GH-90575
BoneAttachment3D
方法 on_bone_pose_update 已被 on_skeleton_update 取代	✔️	✔️	✔️	GH-90575

建立節點

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
AcceptDialog
方法 register_text_enter 的 line_edit 參數型別由 Control 改為 LineEdit	✔️	✔️	✔️	GH-89419
方法 remove_button 的 button 參數型別由 Control 改為 Button	✔️	✔️	✔️	GH-89419

物理

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
PhysicsShapeQueryParameters3D
屬性 motion 的型別由 Vector2 改為 Vector3	❌	❌	❌	GH-85393

備註

在 C# 中，列舉 PhysicsServer3D.G6DofJointAxisFlag 因綁定產生器解析列舉前綴方式而導致相容性問題。在 GH-89851 中新增的成員會讓該列舉的成員名稱被重新命名。

算繪

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
算繪
列舉欄位 FinalAction.FINAL_ACTION_CONTINUE 的值由 2 改為 0	✔️	❌	❌	GH-84976
列舉欄位 InitialAction.INITIAL_ACTION_CLEAR 的值由 0 改為 1	✔️	❌	❌	GH-84976
列舉欄位 InitialAction.INITIAL_ACTION_CLEAR_REGION_CONTINUE 的值由 2 改為 1	✔️	❌	❌	GH-84976
列舉欄位 InitialAction.INITIAL_ACTION_CONTINUE 的值由 5 改為 0	✔️	❌	❌	GH-84976
列舉欄位 InitialAction.INITIAL_ACTION_DROP 的值由 4 改為 2	✔️	❌	❌	GH-84976
列舉欄位 InitialAction.INITIAL_ACTION_KEEP 的值由 3 改為 0	✔️	❌	❌	GH-84976
方法 buffer_clear 移除了 post_barrier 參數	✔️	✔️	✔️	GH-84976
方法 buffer_update 移除了 post_barrier 參數	✔️	✔️	✔️	GH-84976
方法 compute_list_begin 移除了 allow_draw_overlap 參數	✔️	✔️	✔️	GH-84976
方法 compute_list_end 移除了 post_barrier 參數	✔️	✔️	✔️	GH-84976
方法 draw_list_begin 移除了 storage_textures 參數	✔️	✔️	✔️	GH-84976
方法 draw_list_end 移除了 post_barrier 參數	✔️	✔️	✔️	GH-84976
方法 texture_clear 移除了 post_barrier 參數	✔️	✔️	✔️	GH-84976
方法 texture_copy 移除了 post_barrier 參數	✔️	✔️	✔️	GH-84976
方法 texture_resolve_multisample 移除了 post_barrier 參數	✔️	✔️	✔️	GH-84976
方法 texture_update 移除了 post_barrier 參數	✔️	✔️	✔️	GH-84976
RenderingServer
方法 environment_set_fog 新增了 fog_mode 選用參數	✔️	✔️	✔️	GH-84792
RenderSceneBuffersRD
方法 get_color_layer 新增了 msaa 選用參數	✔️	✔️	✔️	GH-80214
方法 get_depth_layer 新增了 msaa 選用參數	✔️	✔️	✔️	GH-80214
方法 get_velocity_layer 新增了 msaa 選用參數	✔️	✔️	✔️	GH-80214
方法 get_color_texture 新增了 msaa 選用參數	✔️	✔️	✔️	GH-80214
方法 get_depth_texture 新增了 msaa 選用參數	✔️	✔️	✔️	GH-80214
方法 get_velocity_texture 新增了 msaa 選用參數	✔️	✔️	✔️	GH-80214

備註

雖然 RenderingDevice.InitialAction 及 RenderingDevice.FinalAction 中的列舉值已改變，但唯一會使用它們的方法（draw_list_begin）已新增相容舊值的支援。因此實務上並不會破壞相容性。

備註

在 C# 中，列舉 RenderingDevice.DriverResource 由於綁定產生器解析列舉前綴的方式，當 GH-83452 新增新成員時會造成成員名稱被重新命名，進而導致相容性問題。

文字

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
字型
方法 find_variation 新增了 baseline_offset 選用參數	✔️	✔️	✔️	GH-87668
RichTextLabel
方法 push_meta 新增了 underline_mode 選用參數	✔️	✔️	✔️	GH-89024
TextServer
方法 shaped_text_get_word_breaks 新增了 skip_grapheme_flags 選用參數	✔️	✔️	✔️	GH-90732
TextServerExtension
方法 _shaped_text_get_word_breaks 新增了 skip_grapheme_flags 參數	❌	❌	❌	GH-90732

音訊

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
AudioStreamPlaybackPolyphonic
方法 play_stream 新增了 playback_type 及 bus 選用參數	✔️	✔️	✔️	GH-91382

導覽

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
AStar2D
方法 get_id_path 新增了 allow_partial_path 選用參數	✔️	✔️	✔️	GH-88047
方法 get_point_path 新增了 allow_partial_path 選用參數	✔️	✔️	✔️	GH-88047
AStar3D
方法 get_id_path 新增了 allow_partial_path 選用參數	✔️	✔️	✔️	GH-88047
方法 get_point_path 新增了 allow_partial_path 選用參數	✔️	✔️	✔️	GH-88047
AStarGrid2D
方法 get_id_path 新增了 allow_partial_path 選用參數	✔️	✔️	✔️	GH-88047
方法 get_point_path 新增了 allow_partial_path 選用參數	✔️	✔️	✔️	GH-88047
NavigationRegion2D
屬性 avoidance_layers 已移除	❌	❌	❌	GH-90747
屬性 constrain_avoidance 已移除	❌	❌	❌	GH-90747
方法 get_avoidance_layer_value 已移除	❌	❌	❌	GH-90747
方法 set_avoidance_layer_value 已移除	❌	❌	❌	GH-90747

備註

NavigationRegion2D 的避障限制功能曾為實驗性，現已移除且無替代方案。

圖塊地圖（TileMap）

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
TileData
方法 get_navigation_polygon 新增了 flip_h、flip_v 及 transpose 選用參數	✔️	✔️	✔️	GH-84660
方法 get_occluder 新增了 flip_h、flip_v 及 transpose 選用參數	✔️	✔️	✔️	GH-84660

XR

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
WebXRInterface
方法 get_input_source_tracker 的回傳型別由 XRPositionalTracker 改為 XRControllerTracker	✔️	❌	✔️	GH-90645
XRServer
方法 get_tracker 的回傳型別由 XRPositionalTracker 改為 XRTracker	✔️	❌	❌	GH-90645

編輯器外掛程式

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
EditorInspectorPlugin
方法 add_property_editor 新增了 label 選用參數	✔️	✔️	✔️	GH-92322
EditorPlugin
方法 add_control_to_bottom_panel 新增了 shortcut 選用參數	✔️	✔️	✔️	GH-88081
方法 add_control_to_dock 新增了 shortcut 選用參數	✔️	✔️	✔️	GH-88081
EditorSceneFormatImporterFBX
型別已更名為 EditorSceneFormatImporterFBX2GLTF	❌	❌	❌	GH-81746

做出更改

In 4.3, some behavior changes have been introduced, which might require you to adjust your project.

核心

備註

二進位序列化已調整，修復了腳本物件與型別化陣列序列化的相關問題（詳見 GH-78219）。這會導致舊有腳本編碼/解碼的相容性中斷。

備註

PackedByteArray 現在能使用更精簡的 base64 編碼來儲存資料。但這樣會影響相容性，代表舊版 Godot 可能無法開啟由 4.3 儲存的資源（詳見 GH-89186）。

為了最大化相容性，目前僅對包含大量 PackedByteArray 的資源與場景啟用這個新儲存格式。未來此格式也會陸續回補至舊版 Godot 的修補更新中。待所有支援中的 Godot 版本都能讀取新格式後，將逐步淘汰相容性措施，讓所有資源與場景都採用新格式。

備註

於 C# 中，Transform3D.InterpolateWith 的實作已修正為先進行旋轉、再進行縮放的正確運算順序（詳見 GH-89843）。

備註

於 C# 中，Aabb.GetSupport 的實作已修正，現在能正確回傳支撐向量（詳見 GH-88919）。

備註

於 C# 中，Variant 型別的 ToString 實作現在預設會使用 InvariantCulture``（詳見 `GH-89547`_），這代表像 ``Vector2(1.2, 3.4) 這樣的格式，無論作業系統語言為何，都會以 . 作為小數點分隔符。

動畫

備註

AnimationMixer 的捕捉（Capture）模式已被全新設計的捕捉功能所取代，效能與可靠性都大幅提升，並且也取代了原有的快取機制（詳見 GH-86715）。

備註

AnimationNode 取得語意時間資訊的流程已重構。這確保與時間相關的行為能如預期運作，但也改變了混合（blending）行為。實作 _process 虛擬方法的開發者請注意，此方法已被標記為過時，未來將會有新方法取而代之（詳見 GH-87171）。

關於動畫相關變更的更多資訊，請參考《Migrating Animations from Godot 4.0 to 4.3 <https://godotengine.org/article/migrating-animations-from-godot-4-0-to-4-3>》。

建立節點

備註

預設字型外框顏色已由白色改為黑色（詳見 GH-54641）。

備註

auto_translate 屬性已廢棄，請改用現在新增至 Node 的 auto_translate_mode 屬性（詳見 GH-87530）。auto_translate_mode 的預設值為 AUTO_TRANSLATE_INHERIT，代表節點會繼承父節點的翻譯模式。這表示，原本有設定 auto_translate = true 的節點，如果其父節點 auto_translate 為 false，可能就不會再被自動翻譯。

多人連線

備註

SceneMultiplayer 的快取協定已改為在發送節點移除確認封包時，傳送收到的 ID，而非節點路徑（詳見 GH-90027）。

此為高階多人連線協定的不相容變更，與舊版 Godot 並不相容。請同時將你的伺服器與客戶端一併升級到 Godot 4.3，才能正常運作。

請注意，高階多人連線設施僅設計給相同 Godot 版本的伺服器與客戶端共同使用。建議你在專案中實作版本檢查機制。

算繪

備註

貼花（Decal）現在會將調變（modulate）顏色從 sRGB 色彩空間轉換為線性色彩，與其他輸入一致，以確保正確的混色效果（詳見 GH-89849）。如果你的專案有用到貼花的調變屬性，將會發現畫面有些微變化。

備註

已導入反向 Z（Reverse Z）深度緩衝技術。這可能會讓部分著色器（Shader）出現不相容。請參考《Introducing Reverse Z (AKA I'm sorry for breaking your shader) <https://godotengine.org/article/introducing-reverse-z/>》一文，取得更多資訊與修正建議。

圖塊地圖（TileMap）

備註

TileMap 圖層現在拆分為獨立節點（詳見 GH-87379 與 GH-89179）。

Android

備註

Android 權限不會再自動請求，因為這不符合官方建議的最佳實踐（詳見 GH-87080）。請自行在 OS 使用 request_permission 方法，並透過 MainLoop 的 on_request_permissions_result 訊號來請求權限並等待使用者回應。