從 Godot 4.1 升級到 Godot 4.2

對於大多數使用 4.1 製作的遊戲和應用程式來說，遷移到 4.2 應該相對安全。本頁旨在介紹遷移專案時需要注意的所有事項。

做出更改

如果你要從 4.1 遷移到 4.2，這裡列出的破壞性更改可能會影響到你。更改按照領域/系統群組。

警告

Mesh 資源格式在 4.2 版本中已變更，以支援 頂點與屬性壓縮 。這能提升算繪效能，尤其是在受限於記憶體頻寬的平台（如行動裝置）上。

仍然可以載入 Godot 4.0-4.1 的網格格式，但**無法**在舊版的 Godot 中載入 Godot 4.2 的網格格式。當開啟使用 4.2 之前的版本製作的 Godot 專案時，您可能會看到一個升級對話框，提供兩個選項：

• 重新啟動並升級： 升級專案中所有網格（Mesh）的格式並儲存到磁碟。選擇此選項後，將無法將專案降版回 Godot 4.2 之前的版本。請務必在選擇此選項*之前*，設定好版本控制系統並推送你的變更！

• 僅升級： 只在記憶體中升級網格格式，不會寫入磁碟。這樣一來，如果未來有需要，仍可將專案降版至 4.2 以前的 Godot 版本。缺點是每次載入專案時都會重新升級網格格式，導致載入速度變慢，這種載入延遲也會影響到導出的專案。網格資源的數量與複雜度會決定載入時間受影響的程度。

如果沒有出現此對話框，請在編輯器上方選擇 專案 > 工具 > 升級網格表面… 來手動執行升級。

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

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

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

核心

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
節點
常數 NOTIFICATION_NODE_RECACHE_REQUESTED 已移除	❌	✔️	❌	GH-84419

動畫

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
動畫播放器（AnimationPlayer）
方法 _post_process_key_value 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 add_animation_library 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 advance 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
訊號 animation_finished 已移至基底類別 AnimationMixer	✔️	❌	❌	GH-80813
訊號 animation_started 已移至基底類別 AnimationMixer	✔️	❌	❌	GH-80813
訊號 animation_libraries_updated 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
訊號 animation_list_changed 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
屬性 audio_max_polyphony 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
訊號 caches_cleared 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 clear_caches 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 find_animation 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 find_animation_library 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 get_animation 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 get_animation_library 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 get_animation_library_list 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 get_animation_list 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 has_animation 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 has_animation_library 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
屬性 method_call_mode 已更名為 callback_mode_method，並移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
屬性 playback_active 已更名為 active，並移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
屬性 playback_process_mode 已更名為 callback_mode_process，並移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 remove_animation_library 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 rename_animation_library 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
屬性 reset_on_save 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
屬性 root_node 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 set_reset_on_save_enabled 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 seek 新增了 update_only 選用參數	✔️	✔️	✔️	GH-80813
動畫樹（AnimationTree）
方法 _post_process_key_value 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
屬性 active 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 advance 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
訊號 animation_finished 已移至基底類別 AnimationMixer	✔️	❌	❌	GH-80813
訊號 animation_started 已移至基底類別 AnimationMixer	✔️	❌	❌	GH-80813
屬性 audio_max_polyphony 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 get_root_motion_position 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 get_root_motion_position_accumulator 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 get_root_motion_rotation 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 get_root_motion_rotation_accumulator 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 get_root_motion_scale 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
方法 get_root_motion_scale_accumulator 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
屬性 process_callback 已更名為 callback_mode_process，並移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
屬性 root_motion_track 已移至基底類別 AnimationMixer	✔️	✔️	✔️	GH-80813
屬性 tree_root 型別由 AnimationNode 改為 AnimationRootNode	✔️	❌	❌	GH-80813

建立節點

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
彈出選單（PopupMenu）
方法 add_icon_shortcut 新增了 allow_echo 選用參數	✔️	✔️	✔️	GH-36493
方法 add_shortcut 新增了 allow_echo 選用參數	✔️	✔️	✔️	GH-36493
方法 clear 新增了 free_submenus 選用參數	✔️	✔️	✔️	GH-79965
RichTextLabel
方法 add_image 新增了 key、pad、tooltip 與 size_in_percent 選用參數	✔️	✔️	✔️	GH-80410

算繪

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
匯入網格（ImporterMesh）
方法 add_surface 的 flags 參數型別由 uint32 改為 uint64	✔️	✔️	✔️	GH-81138
方法 get_surface_format 的回傳型別由 uint32 改為 uint64	✔️	❌	❌	GH-81138
網格資料工具（MeshDataTool）
方法 commit_to_surface 新增了 compression_flags 選用參數	✔️	✔️	✔️	GH-81138
方法 get_format 的回傳型別由 uint32 改為 uint64	✔️	❌	❌	GH-81138
算繪
列舉欄位 BarrierMask.BARRIER_MASK_RASTER 的值由 1 改為 9	✔️	✔️	✔️	GH-79911
列舉欄位 BarrierMask.BARRIER_MASK_ALL_BARRIERS 的值由 7 改為 32767	✔️	✔️	✔️	GH-79911
列舉欄位 BarrierMask.BARRIER_MASK_NO_BARRIER 的值由 8 改為 32768	✔️	✔️	✔️	GH-79911
方法 shader_create_from_bytecode 新增了 placeholder_rid 選用參數	✔️	✔️	✔️	GH-79606
方法 shader_get_vertex_input_attribute_ask 的回傳型別由 uint32 改為 uint64	✔️	❌	❌	GH-81138
建立內容
方法 commit 的 flags 參數型別由 uint32 改為 uint64	✔️	✔️	✔️	GH-81138

文字

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
字型
方法 set_fallbacks 已被 fallbacks 屬性取代	✔️	❌	❌	GH-78266
方法 get_fallbacks 已被 fallbacks 屬性取代	✔️	❌	❌	GH-78266
方法 find_variation 新增了 spacing_top、spacing_bottom、spacing_space、以及 spacing_glyph 選用參數	✔️	✔️	✔️	GH-80954

GraphEdit

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
圖形編輯器（GraphEdit）
屬性 arrange_nodes_button_hidden 已更名為 show_arrange_button	❌	✔️	✔️	GH-81582
方法 get_zoom_hbox 已更名為 get_menu_hbox	❌	✔️	✔️	GH-79308
屬性 snap_distance 已更名為 snapping_distance	❌	✔️	✔️	GH-79308
屬性 use_snap 已更名為 snapping_enabled	❌	✔️	✔️	GH-79308
圖形節點（GraphNode）
屬性 comment 已移除	❌	❌	❌	GH-79307
訊號 close_request 已更名為 delete_request，並移至基底類別 GraphElement	❌	✔️	✔️	GH-79311
屬性 draggable 已移至基底類別 GraphElement	✔️	✔️	✔️	GH-79311
屬性 draggable 已移至基底類別 GraphElement	✔️	✔️	✔️	GH-79311
訊號 dragged 已移至基底類別 GraphElement	✔️	❌	❌	GH-79311
方法 get_connection_input_color 已移除	❌	❌	❌	GH-79311
方法 get_connection_input_count 已移除	❌	❌	❌	GH-79311
方法 get_connection_input_height 已移除	❌	❌	❌	GH-79311
方法 get_connection_input_position 已移除	❌	❌	❌	GH-79311
方法 get_connection_input_slot 已移除	❌	❌	❌	GH-79311
方法 get_connection_input_type 已移除	❌	❌	❌	GH-79311
方法 get_connection_output_color 已移除	❌	❌	❌	GH-79311
方法 get_connection_output_count 已移除	❌	❌	❌	GH-79311
方法 get_connection_output_height 已移除	❌	❌	❌	GH-79311
方法 get_connection_output_position 已移除	❌	❌	❌	GH-79311
方法 get_connection_output_slot 已移除	❌	❌	❌	GH-79311
方法 get_connection_output_type 已移除	❌	❌	❌	GH-79311
屬性 language 已移除	❌	❌	❌	GH-79311
訊號 node_deselected 已移至基底類別 GraphElement	✔️	✔️	✔️	GH-79311
訊號 node_selected 已移至基底類別 GraphElement	✔️	✔️	✔️	GH-79311
屬性 overlay 已移除	❌	❌	❌	GH-79311
屬性 position_offset 已移至基底類別 GraphElement	✔️	✔️	✔️	GH-79311
訊號 position_offset_changed 已移至基底類別 GraphElement	✔️	✔️	✔️	GH-79311
訊號 raise_request 已移至基底類別 GraphElement	✔️	✔️	✔️	GH-79311
屬性 resizable 已移至基底類別 GraphElement	✔️	✔️	✔️	GH-79311
訊號 resize_request 已移至基底類別 GraphElement	✔️	❌	❌	GH-79311
屬性 selectable 已移至基底類別 GraphElement	✔️	✔️	✔️	GH-79311
屬性 selected 已移至基底類別 GraphElement	✔️	✔️	✔️	GH-79311
屬性 show_close 已移除	❌	❌	❌	GH-79311
屬性 text_direction 已移除	❌	❌	❌	GH-79311

圖塊地圖（TileMap）

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
圖塊地圖（TileMap）
屬性 cell_quadrant_size 已更名為 rendering_quadrant_size	❌	✔️	✔️	GH-81070

XR

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
XR 介面（XRInterface）
新增屬性 environment_blend_mode	✔️	❌	❌	GH-81561

備註

這項變更會導致 C# 相容性問題，因為新增的屬性名稱與現有列舉型別名稱衝突，而 C# 綁定生成器會優先處理屬性，因此該列舉型別名稱已由 EnvironmentBlendMode 改為 EnvironmentBlendModeEnum。