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.4 до Godot 4.5

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

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

Якщо ви переходите з версії 4.4 на 4.5, перелічені тут критичні зміни можуть вплинути на вас. Зміни згруповано за областями/системами.

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

Для підтримки нових вимог Google Play Android тепер вимагає націлювання на .NET 9 під час експорту проектів C# на Android, інші платформи продовжують використовувати .NET 8 як мінімально необхідну версію, але новіші версії підтримуються і рекомендуються.

Якщо ви використовуєте C# у своєму проєкті та хочете експортувати дані на Android, вам потрібно буде оновити свій проєкт до .NET 9 (див. інструкції в розділі Оновлення до нової версії .NET).

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

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

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

Ядро

Зміна	Сумісність з GDScript	C# двійковий сумісний	Сумісність із вихідним кодом C#	Введено
JSONRPC
Метод set_scope замінено на set_method	❌	❌	❌	GH-104890
вузол
Метод get_rpc_config перейменовано на get_node_rpc_config	❌	✔️	✔️	GH-106848
Метод set_name змінює тип параметра name з String на StringName	✔️	✔️	✔️	GH-76560

Рендеринг

Зміна	Сумісність з GDScript	C# двійковий сумісний	Сумісність із вихідним кодом C#	Введено
DisplayServer
Метод file_dialog_show додає новий необов'язковий параметр parent_window_id	✔️	✔️	✔️	GH-98194
Метод file_dialog_with_options_show додає новий необов'язковий параметр parent_window_id	✔️	✔️	✔️	GH-98194
RenderingDevice
Метод texture_create_from_extension додає новий необов'язковий параметр mipmaps	✔️	✔️	✔️	GH-105570
RenderingServer
Метод instance_reset_physics_interpolation вилучено	❌	✔️	✔️	GH-104269
Метод instance_set_interpolated вилучено	❌	✔️	✔️	GH-104269

Примітка

У C# перелік RenderingDevice.Features порушує сумісність через спосіб, у який генератор прив'язок виявляє префікс переліку. До переліку GH-103941 було додано нові члени, що призвело до перейменування члена переліку Address на BufferDeviceAddress.

GLTF

Зміна	Сумісність з GDScript	C# двійковий сумісний	Сумісність із вихідним кодом C#	Введено
GLTFAccessor
Властивість byte_offset змінює метадані типу з int32 на int64	✔️	❌	❌	GH-106220
Властивість component_type змінює тип з int на GLTFAccessor::GLTFComponentType	✔️	❌	❌	GH-106220
Властивість count змінює метадані типу з int32 на int64	✔️	❌	❌	GH-106220
Властивість sparse_count змінює метадані типу з int32 на int64	✔️	❌	❌	GH-106220
Властивість sparse_indices_byte_offset змінює метадані типу з int32 на int64	✔️	❌	❌	GH-106220
Властивість sparse_indices_component_type змінює тип з int на GLTFAccessor::GLTFComponentType	✔️	❌	❌	GH-106220
Властивість sparse_values_byte_offset змінює метадані типу з int32 на int64	✔️	❌	❌	GH-106220
GLTFBufferView
Властивість byte_length змінює метадані типу з int32 на int64	✔️	❌	❌	GH-106220
Властивість byte_offset змінює метадані типу з int32 на int64	✔️	❌	❌	GH-106220
Властивість byte_stride змінює метадані типу з int32 на int64	✔️	❌	❌	GH-106220

Примітка

В результаті зміни метаданих типу, прив'язки C# змінили тип з int (32 байти) на long (64 байти).

текст

Зміна	Сумісність з GDScript	C# двійковий сумісний	Сумісність із вихідним кодом C#	Введено
CanvasItem
Метод draw_char додає новий необов'язковий параметр oversampling	✔️	✔️	✔️	GH-104872
Метод draw_char_outline додає новий необов'язковий параметр oversampling	✔️	✔️	✔️	GH-104872
Метод draw_multiline_string додає новий необов'язковий параметр oversampling	✔️	✔️	✔️	GH-104872
Метод draw_multiline_string_outline додає новий необов'язковий параметр oversampling	✔️	✔️	✔️	GH-104872
Метод draw_string додає новий необов'язковий параметр oversampling	✔️	✔️	✔️	GH-104872
Метод draw_string_outline додає новий необов'язковий параметр oversampling	✔️	✔️	✔️	GH-104872
Шрифт
Метод draw_char додає новий необов'язковий параметр oversampling	✔️	✔️	✔️	GH-104872
Метод draw_char_outline додає новий необов'язковий параметр oversampling	✔️	✔️	✔️	GH-104872
Метод draw_multiline_string додає новий необов'язковий параметр oversampling	✔️	✔️	✔️	GH-104872
Метод draw_multiline_string_outline додає новий необов'язковий параметр oversampling	✔️	✔️	✔️	GH-104872
Метод draw_string додає новий необов'язковий параметр oversampling	✔️	✔️	✔️	GH-104872
Метод draw_string_outline додає новий необов'язковий параметр oversampling	✔️	✔️	✔️	GH-104872
RichTextLabel
Метод add_image додає новий необов'язковий параметр alt_text	✔️	✔️	✔️	GH-76829
Метод add_image замінив параметр size_in_percent на width_in_percent та height_in_percent	✔️	✔️	✔️	GH-107347
Метод push_strikethrough додає необов'язковий параметр color	✔️	✔️	✔️	GH-106300
Метод push_table додає новий необов'язковий параметр name	✔️	✔️	✔️	GH-76829
Метод push_underline додає необов'язковий параметр color	✔️	✔️	✔️	GH-106300
Метод update_image замінив параметр size_in_percent на width_in_percent та height_in_percent	✔️	✔️	✔️	GH-107347
TextLine
Метод draw додає новий необов'язковий параметр oversampling	✔️	✔️	✔️	GH-104872
Метод draw_outline додає новий необов'язковий параметр oversampling	✔️	✔️	✔️	GH-104872
TextParagraph
Метод draw додає новий необов'язковий параметр oversampling	✔️	✔️	✔️	GH-104872
Метод draw_dropcap додає новий необов'язковий параметр oversampling	✔️	✔️	✔️	GH-104872
Метод draw_dropcap_outline додає новий необов'язковий параметр oversampling	✔️	✔️	✔️	GH-104872
Метод draw_line додає новий необов'язковий параметр oversampling	✔️	✔️	✔️	GH-104872
Метод draw_line_outline додає новий необов'язковий параметр oversampling	✔️	✔️	✔️	GH-104872
Метод draw_outline додає новий необов'язковий параметр oversampling	✔️	✔️	✔️	GH-104872
TextServer
Метод font_draw_glyph додає новий необов'язковий параметр oversampling	✔️	✔️	✔️	GH-104872
Метод font_draw_glyph_outline додає новий необов'язковий параметр oversampling	✔️	✔️	✔️	GH-104872
Метод shaped_text_draw додає новий необов'язковий параметр oversampling	✔️	✔️	✔️	GH-104872
Метод shaped_text_draw_outline додає новий необов'язковий параметр oversampling	✔️	✔️	✔️	GH-104872
TreeItem
Метод add_button додає новий необов'язковий параметр alt_text	✔️	✔️	✔️	GH-76829
TextServerExtension
Метод _font_draw_glyph додає новий необов'язковий параметр oversampling	❌	❌	❌	GH-104872
Метод _font_draw_glyph_outline додає новий необов'язковий параметр oversampling	❌	❌	❌	GH-104872
Метод _shaped_text_draw додає новий необов'язковий параметр oversampling	❌	❌	❌	GH-104872
Метод _shaped_text_draw_outline додає новий необов'язковий параметр oversampling	❌	❌	❌	GH-104872

XR

Зміна	Сумісність з GDScript	C# двійковий сумісний	Сумісність із вихідним кодом C#	Введено
OpenXRAPIExtension
Метод register_composition_layer_provider змінює тип параметра extension з OpenXRExtensionWrapperExtension на OpenXRExtensionWrapper	✔️	✔️	✔️	GH-104087
Метод register_projection_views_extension змінює тип параметра extension з OpenXRExtensionWrapperExtension на OpenXRExtensionWrapper	✔️	✔️	✔️	GH-104087
Метод unregister_composition_layer_provider змінює тип параметра extension з OpenXRExtensionWrapperExtension на OpenXRExtensionWrapper	✔️	✔️	✔️	GH-104087
Метод unregister_projection_views_extension змінює тип параметра extension з OpenXRExtensionWrapperExtension на OpenXRExtensionWrapper	✔️	✔️	✔️	GH-104087
OpenXRBindingModifierEditor
Тип API OpenXRBindingModifierEditor змінено з Core на Editor	❌	❌	❌	GH-103869
OpenXRInteractionProfileEditor
Тип API OpenXRInteractionProfileEditor змінено з Core на Editor	❌	❌	❌	GH-103869
OpenXRInteractionProfileEditorBase
Тип API OpenXRInteractionProfileEditorBase змінено з Core на Editor	❌	❌	❌	GH-103869

Примітка

Класи OpenXRBindingModifierEditor, OpenXRInteractionProfileEditor, в OpenXRInteractionProfileEditorBase доступні лише в редакторі. Їх використання поза редактором призведе до помилки компіляції.

У C# це означає, що типи переміщуються з збірки GodotSharp до збірки GodotSharpEditor. Обов'язково оберніть код, що використовує ці типи, в блок #if TOOLS, щоб вони не були включені в експортовану гру.

Цю зміну також було перенесено до версії 4.4.1.

Додатки редактора

Зміна	Сумісність з GDScript	C# двійковий сумісний	Сумісність із вихідним кодом C#	Введено
EditorExportPlatform
Метод get_forced_export_files додає новий необов'язковий параметр preset	✔️	✔️	✔️	GH-71542
EditorUndoRedoManager
Метод create_action додає новий необов'язковий параметр mark_unsaved	✔️	✔️	✔️	GH-106121
EditorExportPlatformExtension
Метод _get_option_icon змінює тип повернення з ImageTexture на Texture2D	✔️	❌	❌	GH-108825

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

У версії 4.5 було введено деякі зміни в поведінці, які можуть вимагати від вас коригування вашого проєкту.

TileMapLayer

TileMapLayer.get_coords_for_body_rid() повертатиме різні значення у версії 4.5 порівняно з 4.4, оскільки фрагментація фізики TileMapLayer увімкнена за замовчуванням. Вищі значення TileMapLayer.physics_quadrant_size зроблять цю функцію менш точною. Щоб отримати точні координати комірок, як у версії 4.4 та попередніх версіях, потрібно встановити TileMapLayer.physics_quadrant_size у значення 1, що вимикає фрагментацію фізики.

3D Імпорт моделі

Виправлено імпортери 3D-моделей для коректної обробки вузлів, що не є суглобами, в ієрархії скелета (GH-104184). Для збереження сумісності за замовчуванням існуючі файли імпортуються так само, як і раніше (GH-107352). Нові файли .gltf, .glb, .blend та .fbx (без відповідного файлу .import) імпортуватимуться з новою поведінкою. Однак для існуючих файлів, якщо ви хочете використовувати нову поведінку, ви повинні змінити опцію «Naming Version» (Версія іменування) внизу дока імпорту:

Ядро

Примітка

Resource.duplicate(true) (який виконує глибоке дублювання) тепер дублює лише ресурси всередині файлу ресурсів, для якого він викликається. У версії 4.4 це дублювало все, включаючи зовнішні ресурси. Якщо ви глибоко дублювали ресурс, який містив посилання на інші зовнішні ресурси, ці зовнішні ресурси більше не дублюються. Щоб зберегти стару поведінку, вам потрібно викликати Resource.duplicate_deep(DEEP_DUPLICATE_ALL).

Примітка

ProjectSettings.add_property_info() тепер друкує попередження, коли параметр словника містить відсутні або недійсні ключі. Найголовніше, що тепер він попереджатиме, коли передається ключ usage, оскільки цей ключ не використовується. Це також було так до версії 4.5, але натомість це мовчки ігнорувалося. Нагадуємо, що для правильного встановлення інформації про використання властивості необхідно використовувати ProjectSettings.set_as_basic(), ProjectSettings.set_restart_if_changed() або ProjectSettings.set_as_internal().

Примітка

У C#, StringExtensions.PathJoin тепер дозволяє уникнути додавання додаткового роздільника шляху, коли вихідний рядок порожній або коли доданий шлях починається з роздільника шляху (GH-105281).

Примітка

У C#, StringExtensions.GetExtension тепер повертає порожній рядок замість оригінального рядка, якщо оригінальний рядок не містить розширення (GH-108041).

Примітка

У C# конструктор Quaternion(Vector3, Vector3) тепер правильно створює кватерніон, що представляє найкоротшу дугу між двома вхідними векторами. Раніше він повертав неправильні значення для певних вхідних даних (GH-107618).

Навігація

Примітка

За замовчуванням регіони на карті NavigationServer тепер оновлюються асинхронно за допомогою потоків для покращення продуктивності. Це може спричинити додаткову затримку оновлення через синхронізацію потоків. Асинхронне оновлення регіонів можна перемкнути за допомогою налаштування проекту navigation/world/region_use_async_iterations.

Примітка

Об'єднання навігаційних сіток (navmeshes) у NavigationServer змінило порядок обробки. Тепер регіони спочатку об'єднуються та кешуються внутрішні навігаційні сітки, а потім решта вільних ребер об'єднуються навігаційною картою. Якщо раніше в проекті були помилки синхронізації навігаційної карти, тепер уражені ребра могли зміститися, що зробило вже існуючі помилки в макеті більш помітними під час пошуку шляху. Налаштування проекту navigation/2d_or_3d/merge_rasterizer_cell_scale можна встановити на менше значення, щоб збільшити деталізацію сітки растеризації (де 0.01 – найменший можливий розмір комірки). Якщо помилки об'єднання ребер все ще зберігаються з найменшим можливим значенням масштабу растеризації, помилка може бути спричинена перекриттям: дві навігаційні сітки накладаються одна на одну, що призводить до конфлікту геометрії.

Фізика

Примітка

Коли 3D-фізичний движок налаштований на Jolt Physics, тепер ви завжди будете бачити перекриття між Area3D і статичними тілами, про які повідомляється за замовчуванням, оскільки налаштування проекту physics/jolt_physics_3d/simulation/areas_detect_static_bodies було видалено (GH-105746). Якщо ви все ще хочете, щоб такі перекриття ігнорувалися, вам потрібно буде змінити маску зіткнення або шар або Area3D, або статичного тіла.

текст

Примітка

У GDScript виклики функцій RichTextLabel::add_image та RichTextLabel::update_image продовжуватимуть працювати, але аргумент size_in_percent тепер використовуватиметься як значення для width_in_percent, а height_in_percent за замовчуванням матиме значення false (GH-107347). Щоб відновити попередню поведінку, ви можете явно встановити height_in_percent на те саме значення, яке ви передавали як size_in_percent.