Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

從 Godot 4.0 升級到 Godot 4.1

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

做出更改

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

警告

GDExtension API 在 4.1 中完全不相容，因此未列入下表。更多資訊請參見 將 GDExtension 更新到 4.1 部分。

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

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

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

核心

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
Basis
looking_at 方法新增了可選的 use_model_front 參數	✔️	✔️	✔️	GH-76082
Object
get_meta_list 方法的返回型別從 PackedStringArray 改成了 Array[StringName]	✔️	❌	❌	GH-76418
Transform3D
looking_at 方法新增了可選的 use_model_front 參數	✔️	✔️	✔️	GH-76082
UndoRedo
create_action 新增了可選的 backward_undo_ops 參數	✔️	✔️	✔️	GH-76688
WorkerThreadPool
wait_for_task_completion 方法的返回型別從 void 改成了 Error	✔️	❌	✔️	GH-77143

動畫

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
動畫模式
_process 方法新增了 test_only 參數	❌	❌	❌	GH-75759
blend_input 方法新增了可選的 test_only 參數	✔️	✔️	✔️	GH-75759
blend_node 方法新增了可選的 test_only 參數	✔️	✔️	✔️	GH-75759
AnimationNodeStateMachinePlayback
get_travel_path 方法的返回型別從 PackedStringArray 改成了 Array[StringName]	✔️	❌	❌	GH-76418

節點

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
PathFollow2D
移除了 lookahead 屬性	❌	❌	❌	GH-72842

節點

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
一般：
方法 segment_intersects_convex 將 planes 參數型別從無型別的 Array 改為 Array[Plane]	✔️	✔️	❌	GH-76418
使用泛型方法
方法 create_multiple_convex_collisions 增加了一個新的 settings 可選參數	✔️	✔️	✔️	GH-72152
節點:
方法 look_at 增加了一個新的 use_model_front 可選參數	✔️	✔️	✔️	GH-76082
方法 look_at_from_position 增加了一個新的 use_model_front 可選參數	✔️	✔️	✔️	GH-76082

建立節點

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
CodeEdit
方法 add_code_completion_option 新增了一個新的 location 可選參數	✔️	✔️	✔️	GH-75746
RichTextLabel
方法 push_list 增加了一個新的 bullet 可選參數	✔️	✔️	✔️	GH-75017
方法 push_paragraph 增加了一個新的 justification_flags 可選參數	✔️	✔️	✔️	GH-75250
方法 push_paragraph 增加了一個新的 tab_stops 可選參數	✔️	✔️	✔️	GH-76401
是
方法 edit_selected 增加了一個新的 force_edit 可選參數	✔️	✔️	✔️	GH-76794

物理

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
Area2D
屬性 priority 型別從 float 改為 int	❌	❌	❌	GH-72749
Area3D
屬性 priority 型別從 float 改為 int	❌	❌	❌	GH-72749
PhysicsDirectSpaceState2D
方法 collide_shape 將返回型別從 Array[PackedVector2Array] 改為 Array[Vector2]	❌	❌	❌	GH-75260
PhysicsDirectSpaceState3D
方法 collide_shape 將返回型別從 Array[PackedVector3Array] 改為 Array[Vector3]	❌	❌	❌	GH-75260

渲染

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
RDShaderFile
方法 get_version_list 將返回型別從 PackedStringArray 改為 Array[StringName]	✔️	❌	❌	GH-76418
渲染
方法 draw_list_begin 將 storage_textures 參數型別從無型別的 Array 改為 Array[RID]	✔️	✔️	❌	GH-76418
RenderingServer
方法 global_shader_parameter_get_list 將返回型別從 PackedStringArray 改為 Array[StringName]	✔️	❌	❌	GH-76418
建立內容
方法 add_triangle_fan 將 tangents 參數型別從無型別的 Array 改為 Array[Plane]	✔️	✔️	❌	GH-76418

導覽

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
導覽
方法 set_velocity 被屬性 velocity 所取代	✔️	❌	❌	GH-69988
屬性 time_horizon 被拆分為 time_horizon_agents 和 time_horizon_obstacles	❌	❌	❌	GH-69988
導覽
屬性 agent_height_offset 更名為 path_height_offset	❌	❌	❌	GH-69988
刪除了屬性 ignore_y	❌	❌	❌	GH-69988
方法 set_velocity 被屬性 velocity 所取代	✔️	❌	❌	GH-69988
屬性 time_horizon 被拆分為 time_horizon_agents 和 time_horizon_obstacles	❌	❌	❌	GH-69988
導覽
刪除了屬性 estimate_radius	❌	❌	❌	GH-69988
方法 get_rid 更名為 get_agent_rid	❌	❌	❌	GH-69988
導覽
刪除了屬性 estimate_radius	❌	❌	❌	GH-69988
方法 get_rid 更名為 get_agent_rid	❌	❌	❌	GH-69988
導覽網格
方法 agent_set_callback 更名為 agent_set_avoidance_callback	❌	❌	❌	GH-69988
刪除了方法 agent_set_target_velocity	❌	❌	❌	GH-69988
方法 agent_set_time_horizon 拆分為 agent_set_time_horizon_agents 和 agent_set_time_horizon_obstacles	❌	❌	❌	GH-69988
導覽網格
方法 agent_set_callback 更名為 agent_set_avoidance_callback	❌	❌	❌	GH-69988
刪除了方法 agent_set_target_velocity	❌	❌	❌	GH-69988
方法 agent_set_time_horizon 拆分為 agent_set_time_horizon_agents 和 agent_set_time_horizon_obstacles	❌	❌	❌	GH-69988

網路

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
WebRTCPeerConnectionExtension
方法 _create_data_channel 將返回型別從 Object 改為 WebRTCDataChannel	✔️	❌	✔️	GH-78237

編輯器外掛程式

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
動畫軌編輯器
動畫軌編輯器	❌	❌	❌	GH-76413
編輯器界面 (C++)
EditorInterface 類現在繼承自 Object 而不是 Node	✔️	❌	❌	GH-76176
方法 set_movie_maker_enabled 替換為 movie_maker_enabled 屬性	✔️	❌	❌	GH-76176
方法 is_movie_maker_enabled 替換為 movie_maker_enabled 屬性	✔️	❌	❌	GH-76176
EditorResourcePreviewGenerator
_generate 方法新增了 metadata 參數	❌	❌	❌	GH-64628
_generate_from_path 方法新增了 metadata 參數	❌	❌	❌	GH-64628
EditorUndoRedoManager
create_action 新增了可選的 backward_undo_ops 參數	✔️	✔️	✔️	GH-76688

做出更改

4.1 中引入了一些行為的更改，你可能需要調整專案。

改動	簡介
建立內容
當輸入事件應傳播到 SubViewport 及其子節點時，SubViewportContainer.mouse_filter 現在需要改為 MOUSE_FILTER_STOP 或 MOUSE_FILTER_PASS。詳見 GH-79271。	GH-57894
如果多層 SubViewportContainer 節點都應接收滑鼠輸入事件，現在需要用 Area2D 節點代替。詳見 GH-79128。	GH-57894
檢視區
啟用 Physics Picking 的 Viewport 節點現在會自動將 InputEvent 標記為已處理。變通方法見 GH-79897。	GH-77595

將 GDExtension 更新到 4.1

GDExtension 仍處於測試階段。在它被標記為穩定版之前，升級到新的 Godot 小版本時可能會出現相容性問題。

為了修復一個嚴重的錯誤，在 Godot 4.1 中，我們不得不在很大程度上打破二進位相容性，在很小程度上打破原始程式碼相容性。

這意味著為 Godot 4.0 製作的 GDExtensions 將需要為 Godot 4.1 重新編譯（使用 godot-cpp 的 4.1 分支），並對其原始程式碼稍作修改。

最後場景應該長這樣。

GDExtensionBool GDE_EXPORT example_library_init(const GDExtensionInterface *p_interface, const GDExtensionClassLibraryPtr p_library, GDExtensionInitialization *r_initialization) {
    godot::GDExtensionBinding::InitObject init_obj(p_interface, p_library, r_initialization);

    init_obj.register_initializer(initialize_example_module);
    init_obj.register_terminator(uninitialize_example_module);
    init_obj.set_minimum_library_initialization_level(MODULE_INITIALIZATION_LEVEL_SCENE);

    return init_obj.init();
}

不過，對於 Godot 4.1 來說，它應該是這樣的：

GDExtensionBool GDE_EXPORT example_library_init(GDExtensionInterfaceGetProcAddress p_get_proc_address, const GDExtensionClassLibraryPtr p_library, GDExtensionInitialization *r_initialization) {
    godot::GDExtensionBinding::InitObject init_obj(p_get_proc_address, p_library, r_initialization);

    init_obj.register_initializer(initialize_example_module);
    init_obj.register_terminator(uninitialize_example_module);
    init_obj.set_minimum_library_initialization_level(MODULE_INITIALIZATION_LEVEL_SCENE);

    return init_obj.init();
}

有下列事項需注意：

1. 第一個參數從 const GDExtensionInterface *p_interface 改為 GDExtensionInterfaceGetProcAddress p_get_proc_address

2. init_obj 變數的建構子現在會接收 p_get_proc_address 作為第一個參數

您還需要在 .gdextension 檔中新增額外的 compatibility_minimum 行，使其看起來類似於：

[configuration]

entry_symbol = "example_library_init"
compatibility_minimum = 4.1

這會讓 Godot 知道您的 GDExtension 已經更新，可以在 Godot 4.1 中安全載入。