Оновлення з Godot 4.0 до Godot 4.1

Для більшості ігор і програм, створених з версією 4.0, перехід на 4.1 має бути відносно безпечним. На цій сторінці описано все, на що потрібно звернути увагу під час міграції вашого проекту.

Ломальні зміни

Якщо ви переходите з 4.0 на 4.1, перелічені тут критичні зміни можуть вплинути на вас. Зміни згруповано за сферами/системами.

Попередження

API GDExtension повністю порушує сумісність у версії 4.1, тому його не включено в таблицю нижче. Перегляньте розділ Оновлення GDExtension до 4.1 для отримання додаткової інформації.

У цій статті вказується, чи кожна порушна зміна впливає на GDScript і чи є порушна зміна C# бінарною сумісністю чи сумісною з джерелом:

• Сумісність із двійковими файлами – наявні двійкові файли завантажуватимуться та успішно виконуватимуться без повторної компіляції, а поведінка під час виконання не зміниться.

• Сумісність із вихідним кодом – вихідний код буде успішно скомпільовано без змін під час оновлення Godot.

Ядро

Зміна	Сумісність з GDScript	C# двійковий сумісний	Сумісність із вихідним кодом C#	Введено
Основа
Метод looking_at додає новий необов’язковий параметр use_model_front	✔️	✔️	✔️	GH-76082
Об'єкт
Метод get_meta_list змінює тип повернення з PackedStringArray на Array[StringName]	✔️	❌	❌	GH-76418
Transform3D
Метод looking_at додає новий необов’язковий параметр use_model_front	✔️	✔️	✔️	GH-76082
Відмінити Повторити
Метод create_action додає новий необов’язковий параметр backward_undo_ops	✔️	|✔️ з compat|	✔️	GH-76688
WorkerThreadPool
Метод wait_for_task_completion змінює тип повернення з void на Error	✔️	❌	✔️	GH-77143

Анімація

Зміна	Сумісність з GDScript	C# двійковий сумісний	Сумісність із вихідним кодом C#	Введено
AnimationNode
Метод _process додає новий параметр test_only	❌	❌	❌	GH-75759
Метод blend_input додає новий необов'язковий параметр test_only	✔️	|✔️ з compat|	✔️	GH-75759
Метод blend_node додає новий необов'язковий параметр test_only	✔️	|✔️ з compat|	✔️	GH-75759
AnimationNodeStateMachinePlayback
Метод get_travel_path змінює тип повернення з PackedStringArray на Array[StringName]	✔️	❌	❌	GH-76418

2D вузли

Зміна	Сумісність з GDScript	C# двійковий сумісний	Сумісність із вихідним кодом C#	Введено
Дотримуйтеся шляху 2D
Властивість lookahead видалено	❌	❌	❌	GH-72842

3D вузли

Зміна	Сумісність з GDScript	C# двійковий сумісний	Сумісність із вихідним кодом C#	Введено
Geometry3D
Метод segment_intersects_convex змінює тип параметра planes з нетипового Array на Array[Plane]	✔️	|✔️ з compat|	❌	GH-76418
MeshInstance3D
Метод create_multiple_convex_collision додає новий необов’язковий параметр settings	✔️	|✔️ з compat|	✔️	GH-72152
Node3D
Метод look_at додає новий необов'язковий параметр use_model_front	✔️	|✔️ з compat|	✔️	GH-76082
Метод look_at_from_position додає новий необов’язковий параметр use_model_front	✔️	|✔️ з compat|	✔️	GH-76082

Вузли GUI

Зміна	Сумісність з GDScript	C# двійковий сумісний	Сумісність із вихідним кодом C#	Введено
Редагування коду
Метод add_code_completion_option додає новий необов'язковий параметр location	✔️	|✔️ з compat|	✔️	GH-75746
RichTextLabel
Метод push_list додає новий необов’язковий параметр bullet	✔️	|✔️ з compat|	✔️	GH-75017
Метод push_paragraph додає новий необов'язковий параметр justification_flags	✔️	|✔️ з compat|	✔️	GH-75250
Метод push_paragraph додає новий необов’язковий параметр tab_stops	✔️	|✔️ з compat|	✔️	GH-76401
Дерево
Метод edit_selected додає новий необов’язковий параметр force_edit	✔️	|✔️ з compat|	✔️	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
RenderingDevice
Метод draw_list_begin змінює тип параметра storage_textures з нетипового Array на Array[RID]	✔️	|✔️ з compat|	❌	GH-76418
RenderingServer
Метод global_shader_parameter_get_list змінює тип повернення з PackedStringArray на Array[StringName]	✔️	❌	❌	GH-76418
Інструмент SurfaceTool
Метод add_triangle_fan змінює тип параметра tangents з нетипового Array на Array[Plane]	✔️	|✔️ з compat|	❌	GH-76418

Навігація

Зміна	Сумісність з GDScript	C# двійковий сумісний	Сумісність із вихідним кодом C#	Введено
NavigationAgent2D
Метод set_velocity замінено властивістю velocity	✔️	❌	❌	GH-69988
Властивість time_horizon розділена на time_horizon_agents і time_horizon_obstacles	❌	❌	❌	GH-69988
NavigationAgent3D
Властивість 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
NavigationObstacle2D
Властивість estimate_radius видалено	❌	❌	❌	GH-69988
Метод get_rid перейменовано на get_agent_rid	❌	❌	❌	GH-69988
NavigationObstacle3D
Властивість estimate_radius видалено	❌	❌	❌	GH-69988
Метод get_rid перейменовано на get_agent_rid	❌	❌	❌	GH-69988
НавігаційнийСервер2D
Метод 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
НавігаційнийСервер3D
Метод 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#	Введено
Плагін AnimationTrackEdit
Тип AnimationTrackEditPlugin видалено	❌	❌	❌	GH-76413
Інтерфейс редактора
Тип EditorInterface змінює успадкування з Node на Object	✔️	❌	❌	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	✔️	|✔️ з compat|	✔️	GH-76688

Зміни поведінки

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

Зміна	Введено
SubViewportContainer
Коли події введення мають досягати SubViewports та їхніх дітей, SubViewportContainer.mouse_filter тепер має бути MOUSE_FILTER_STOP або MOUSE_FILTER_PASS. Докладніше див. GH-79271.	GH-57894
Багатошарові вузли SubViewportContainer, які мають отримувати події введення миші, тепер потрібно замінити вузлами Area2D. Докладніше див. GH-79128.	GH-57894
Вікно перегляду
Вузли Viewport, для яких увімкнено Physics Picking, тепер автоматично встановлюють InputEvents як оброблені. Перегляньте GH-79897 для обхідних шляхів.	GH-77595

Оновлення GDExtension до 4.1

Щоб виправити серйозну помилку, у Godot 4.1 нам довелося значною мірою порушити двійкову сумісність і меншою мірою сумісність з джерелами.

Це означає, що GDExtensions, створені для Godot 4.0, потрібно буде перекомпілювати для Godot 4.1 (використовуючи гілку 4.1 godot-cpp), з невеликою зміною їх вихідного коду.

У Godot 4.0 ваша функція "entry_symbol" виглядає приблизно так:

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 як перший параметр

Також потрібно додати додатковий рядок compatibility_minimum до вашого файлу .gdextension, щоб він виглядав приблизно так:

[configuration]

entry_symbol = "example_library_init"
compatibility_minimum = 4.1

Це дає Godot знати, що ваше GDExtension оновлено та безпечно завантажувати у Godot 4.1.