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...
Gestione delle interruzioni di compatibilità
Allora, è stato aggiunto un nuovo parametro a un metodo, cambiato il tipo restituito, cambiato il tipo di un parametro o cambiato il suo valore predefinito e ora il test automatizzato segnala problemi di compatibilità?
Bisognerebbe evitare di compromettere la compatibilità, ma quando necessario esistono sistemi in grado di gestire la situazione in modo da rendere la transizione il più agevole possibile.
Un esempio pratico
Questi cambiamenti provengono dalla richiesta di pull #88047, che ha aggiunto nuove opzioni di percorso a AStarGrid2D e ad altre classi AStar. Tra gli altri cambiamenti, questi metodi sono stati modificati in 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);
A:
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);
Ciò significava aggiungere al file nuovi vincoli di metodi di compatibilità, che dovrebbero trovarsi nella sezione protected del codice, solitamente situata accanto a _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
Dovrebbero cominciare con _ per indicare che sono interni e terminare con _bind_compat_ seguito dal numero del PR che ha introdotto il cambiamento (88047 in questo esempio). Questi metodi di compatibilità si devono implementare in un file dedicato, come core/math/a_star_grid_2d.compat.inc in questo caso:
/**************************************************************************/
/* 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
A meno che la modifica di compatibilità non sia complessa, il metodo di compatibilità dovrebbe chiamare direttamente il metodo modificato, anziché duplicarlo. Assicurarsi di utilizzare gli argomenti predefiniti per quel metodo (nell'esempio precedente, questo sarebbe false).
Questo file si dovrebbe sempre collocare accanto al file originale e terminare con .compat.inc invece di .cpp o .h. Successivamente, questo file si dovrebbe includere nel file .cpp a cui stiamo aggiungendo metodi di compatibilità, quindi 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"
Infine, è necessario registrare le modifiche all'API GDExtension. Per fare ciò, compila prima Godot sul ramo master e poi eseguilo con il flag --dump-extension-api:
git switch master
scons
godot --dump-extension-api
Questo creerà un file chiamato extension_api.json nella cartella attuale. Passa al tuo ramo, ricompila Godot e poi eseguilo con il flag --validate-extension-api seguito dal percorso del file extension_api.json che hai appena generato:
git switch my-feature-branch
scons
godot --validate-extension-api /path/to/extension_api.json
Questo genererà alcune righe che iniziano con Validate extension JSON come queste:
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.
Attenzione
Se si verifica un errore Hash changed per un metodo, significa che il vincolo di compatibilità è mancante o errato. Queste righe non si devono aggiungere al file di validazione, ma corrette vincolando il metodo di compatibilità appropriato. Assicurarsi di ricontrollare quanto segue:
Per il metodo di compatibilità (quello il cui nome termina con il numero della PR), i tipi di argomenti, i nomi e i valori predefiniti devono essere identici alla versione del metodo precedente alle modifiche.
In
_bind_compatibility_methods(), i nomi degli argomenti forniti alla macroD_METHOD()inClassDB::bind_compatibility_method()devono essere identici a quelli della chiamataClassDB::bind_method()per il metodo originale.
Aggiungi queste righe, seguite da un commento che spieghi in cosa consisteva la modifica all'API e le azioni intraprese per evitare incompatibilità, a un file di validazione denominato con lo stesso ID della pull request di GitHub e collocato nella cartella della versione di Godot con cui si sarebbero verificati problemi di compatibilità.
Poiché questo esempio era per la PR #88047, il suo nome file sarebbe GH-88047.txt e, dato che ciò è stato fatto durante lo sviluppo della versione 4.3 (quindi passando dalla 4.2), il file si troverebbe nella cartella misc/extension_api_validation/4.2-stable/.
Di seguito è riportato un esempio completo di tale file per questa PR:
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.
E questo è tutto! Ci si potrebbe imbattere in casi un po' più complicati, come riorganizzare gli argomenti, cambiare i tipi restituiti, ecc., ma questo copre le basi su come utilizzare questo sistema.
Per maggiori informazioni, consulta pull request #76446.