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

做出更改

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

改動	簡介
建立內容
當輸入事件應傳播到 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

為了修復一個嚴重的錯誤，在 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 中安全載入。