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.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 訊號來請求權限並等待使用者回應。