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...
Усунення порушень сумісності
Отже, ви додали новий параметр до методу, змінили тип повернення, змінили тип параметра або змінили його значення за замовчуванням, і тепер автоматизоване тестування скаржиться на порушення сумісності?
Слід уникати порушення сумісності, але за необхідності існують системи, які впораються з цим таким чином, щоб зробити перехід максимально плавним.
Практичний приклад
Ці зміни взято з запиту на витягування #88047, який додав нові параметри шляху до AStarGrid2D та інших класів AStar. Серед інших змін, ці методи були змінені в core/math/a_star_grid_2d.h:
Vector<Vector2> get_point_path(const Vector2i &p_from, const Vector2i &p_to);
TypedArray<Vector2i> get_id_path(const Vector2i &p_from, const Vector2i &p_to);
до:
Vector<Vector2> get_point_path(const Vector2i &p_from, const Vector2i &p_to, bool p_allow_partial_path = false);
TypedArray<Vector2i> get_id_path(const Vector2i &p_from, const Vector2i &p_to, bool p_allow_partial_path = false);
Це означало додавання нових прив’язок методів сумісності до файлу, який повинен бути в розділі protected коду, зазвичай розміщеному поруч з _bind_methods():
#ifndef DISABLE_DEPRECATED
TypedArray<Vector2i> _get_id_path_bind_compat_88047(const Vector2i &p_from, const Vector2i &p_to);
Vector<Vector2> _get_point_path_bind_compat_88047(const Vector2i &p_from, const Vector2i &p_to);
static void _bind_compatibility_methods();
#endif
Вони повинні починатися з символу _, щоб вказати, що вони є внутрішніми, і закінчуватися на _bind_compat_, за яким слідує номер зміни, що ввела зміну (88047 у цьому прикладі). Ці методи сумісності потрібно реалізувати у спеціальному файлі, наприклад, у цьому випадку core/math/a_star_grid_2d.compat.inc:
/**************************************************************************/
/* a_star_grid_2d.compat.inc */
/**************************************************************************/
/* This file is part of: */
/* GODOT ENGINE */
/* https://godotengine.org */
/**************************************************************************/
/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */
/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur. */
/* */
/* Permission is hereby granted, free of charge, to any person obtaining */
/* a copy of this software and associated documentation files (the */
/* "Software"), to deal in the Software without restriction, including */
/* without limitation the rights to use, copy, modify, merge, publish, */
/* distribute, sublicense, and/or sell copies of the Software, and to */
/* permit persons to whom the Software is furnished to do so, subject to */
/* the following conditions: */
/* */
/* The above copyright notice and this permission notice shall be */
/* included in all copies or substantial portions of the Software. */
/* */
/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, */
/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF */
/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */
/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY */
/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, */
/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE */
/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */
/**************************************************************************/
#ifndef DISABLE_DEPRECATED
#include "core/variant/typed_array.h"
TypedArray<Vector2i> AStarGrid2D::_get_id_path_bind_compat_88047(const Vector2i &p_from_id, const Vector2i &p_to_id) {
return get_id_path(p_from_id, p_to_id, false);
}
Vector<Vector2> AStarGrid2D::_get_point_path_bind_compat_88047(const Vector2i &p_from_id, const Vector2i &p_to_id) {
return get_point_path(p_from_id, p_to_id, false);
}
void AStarGrid2D::_bind_compatibility_methods() {
ClassDB::bind_compatibility_method(D_METHOD("get_id_path", "from_id", "to_id"), &AStarGrid2D::_get_id_path_bind_compat_88047);
ClassDB::bind_compatibility_method(D_METHOD("get_point_path", "from_id", "to_id"), &AStarGrid2D::_get_point_path_bind_compat_88047);
}
#endif // DISABLE_DEPRECATED
Якщо зміна сумісності не є складною, метод сумісності повинен викликати модифікований метод безпосередньо, замість того, щоб дублювати цей метод. Переконайтеся, що аргументи за замовчуванням відповідають цьому методу (у прикладі вище це буде false).
Цей файл завжди слід розміщувати поруч із оригінальним файлом і мати .compat.inc у кінці замість .cpp або .h. Далі це слід включити у файл .cpp, до якого ми додаємо методи сумісності, тому core/math/a_star_grid_2d.cpp:
#include "a_star_grid_2d.h"
#include "a_star_grid_2d.compat.inc"
#include "core/variant/typed_array.h"
Нарешті, зміни API GDExtension потрібно записати. Для цього спочатку скомпілюйте Godot на гілці master, а потім запустіть його з прапорцем --dump-extension-api:
git switch master
scons
godot --dump-extension-api
Це створить файл з назвою extension_api.json у вашому поточному каталозі. Перейдіть до вашої гілки feature, перекомпілюйте Godot, а потім запустіть його з прапорцем --validate-extension-api, а потім шляхом до щойно згенерованого вами файлу extension_api.json:
git switch my-feature-branch
scons
godot --validate-extension-api /path/to/extension_api.json
Це згенерує кілька рядків, що починаються з Validate extension JSON, ось так:
Validate extension JSON: Error: Field 'classes/AStar2D/methods/get_id_path/arguments': size changed value in new API, from 2 to 3.
Validate extension JSON: Error: Field 'classes/AStar2D/methods/get_point_path/arguments': size changed value in new API, from 2 to 3.
Validate extension JSON: Error: Field 'classes/AStar3D/methods/get_id_path/arguments': size changed value in new API, from 2 to 3.
Validate extension JSON: Error: Field 'classes/AStar3D/methods/get_point_path/arguments': size changed value in new API, from 2 to 3.
Validate extension JSON: Error: Field 'classes/AStarGrid2D/methods/get_id_path/arguments': size changed value in new API, from 2 to 3.
Validate extension JSON: Error: Field 'classes/AStarGrid2D/methods/get_point_path/arguments': size changed value in new API, from 2 to 3.
Увага
Якщо ви отримуєте помилку Hash changed для методу, це означає, що прив'язка сумісності відсутня або неправильна. Такі рядки не слід додавати до файлу перевірки, а виправляти, прив'язуючи відповідний метод сумісності. Обов'язково перевірте наступне:
Для методу сумісності (того, чия назва закінчується номером PR) типи аргументів, імена та значення за замовчуванням мають бути ідентичними версії методу до внесення змін.
У
_bind_compatibility_methods(), імена аргументів, надані макросуD_METHOD()уClassDB::bind_compatibility_method(), повинні бути ідентичними тим, що були отримані у викликуClassDB::bind_method()для оригінального методу.
Додайте ці рядки, а потім коментар із поясненням зміни API та вжитих заходів для запобігання поломці, до файлу валідації, названого на честь ідентифікатора запиту на зняття GitHub, та поміщеного в папку версії Godot, для якої було б порушено сумісність.
Оскільки цей приклад був для PR #88047, назва його файлу буде GH-88047.txt, і оскільки це було зроблено під час розробки версії 4.3 (таким чином, змінившись з версії 4.2), файл знаходитиметься в папці misc/extension_api_validation/4.2-stable/.
Дивіться нижче повний приклад такого файлу для цього запиту на перевірку:
GH-88047
--------
Validate extension JSON: Error: Field 'classes/AStar2D/methods/get_id_path/arguments': size changed value in new API, from 2 to 3.
Validate extension JSON: Error: Field 'classes/AStar2D/methods/get_point_path/arguments': size changed value in new API, from 2 to 3.
Validate extension JSON: Error: Field 'classes/AStar3D/methods/get_id_path/arguments': size changed value in new API, from 2 to 3.
Validate extension JSON: Error: Field 'classes/AStar3D/methods/get_point_path/arguments': size changed value in new API, from 2 to 3.
Validate extension JSON: Error: Field 'classes/AStarGrid2D/methods/get_id_path/arguments': size changed value in new API, from 2 to 3.
Validate extension JSON: Error: Field 'classes/AStarGrid2D/methods/get_point_path/arguments': size changed value in new API, from 2 to 3.
Added optional "allow_partial_path" argument to get_id_path and get_point_path methods in AStar classes.
Compatibility methods registered.
Ось і все! Ви можете зіткнутися з трохи складнішими випадками, такими як перестановка аргументів, зміна типів повернення тощо, але це охоплює основи використання цієї системи.
Для отримання додаткової інформації перегляньте запит на витягування #76446.