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.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。