Rename `GDExtensionCompatHashes` to make it clear it's only for exceptional situations

core/extension/extension_api_dump.cpp

@@ -32,7 +32,7 @@
 
 #include "core/config/engine.h"
 #include "core/core_constants.h"
-#include "core/extension/gdextension_compat_hashes.h"
+#include "core/extension/gdextension_special_compat_hashes.h"
 #include "core/io/file_access.h"
 #include "core/io/json.h"
 #include "core/templates/pair.h"
@@ -1094,7 +1094,7 @@ Dictionary GDExtensionAPIDump::generate_extension_api(bool p_include_docs) {
 						}
 
 #ifndef DISABLE_DEPRECATED
-						GDExtensionCompatHashes::get_legacy_hashes(class_name, method_name, compatibility);
+						GDExtensionSpecialCompatHashes::get_legacy_hashes(class_name, method_name, compatibility);
 #endif
 
 						if (compatibility.size() > 0) {

core/extension/gdextension_interface.cpp

@@ -32,7 +32,7 @@
 
 #include "core/config/engine.h"
 #include "core/extension/gdextension.h"
-#include "core/extension/gdextension_compat_hashes.h"
+#include "core/extension/gdextension_special_compat_hashes.h"
 #include "core/io/file_access.h"
 #include "core/io/image.h"
 #include "core/io/xml_parser.h"
@@ -1604,7 +1604,7 @@ static GDExtensionMethodBindPtr gdextension_classdb_get_method_bind(GDExtensionC
 	// If lookup failed, see if this is one of the broken hashes from issue #81386.
 	if (!mb && exists) {
 		uint32_t mapped_hash;
-		if (GDExtensionCompatHashes::lookup_current_hash(classname, methodname, p_hash, &mapped_hash)) {
+		if (GDExtensionSpecialCompatHashes::lookup_current_hash(classname, methodname, p_hash, &mapped_hash)) {
 			mb = ClassDB::get_method_with_compatibility(classname, methodname, mapped_hash, &exists);
 		}
 	}

core/extension/gdextension_manager.cpp

@@ -30,8 +30,8 @@
 
 #include "gdextension_manager.h"
 
-#include "core/extension/gdextension_compat_hashes.h"
 #include "core/extension/gdextension_library_loader.h"
+#include "core/extension/gdextension_special_compat_hashes.h"
 #include "core/io/dir_access.h"
 #include "core/io/file_access.h"
 #include "core/object/script_language.h"
@@ -385,7 +385,7 @@ GDExtensionManager::GDExtensionManager() {
 	singleton = this;
 
 #ifndef DISABLE_DEPRECATED
-	GDExtensionCompatHashes::initialize();
+	GDExtensionSpecialCompatHashes::initialize();
 #endif
 }
 
@@ -394,6 +394,6 @@ GDExtensionManager::~GDExtensionManager() {
 		singleton = nullptr;
 	}
 #ifndef DISABLE_DEPRECATED
-	GDExtensionCompatHashes::finalize();
+	GDExtensionSpecialCompatHashes::finalize();
 #endif
 }

core/extension/gdextension_compat_hashes.cpp → core/extension/gdextension_special_compat_hashes.cpp

@@ -1,5 +1,5 @@
 /**************************************************************************/
-/*  gdextension_compat_hashes.cpp                                         */
+/*  gdextension_special_compat_hashes.cpp                                 */
 /**************************************************************************/
 /*                         This file is part of:                          */
 /*                             GODOT ENGINE                               */
@@ -28,16 +28,16 @@
 /* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                 */
 /**************************************************************************/
 
-#include "gdextension_compat_hashes.h"
+#include "gdextension_special_compat_hashes.h"
 
 #ifndef DISABLE_DEPRECATED
 
 #include "core/object/class_db.h"
 #include "core/variant/variant.h"
 
-HashMap<StringName, LocalVector<GDExtensionCompatHashes::Mapping>> GDExtensionCompatHashes::mappings;
+HashMap<StringName, LocalVector<GDExtensionSpecialCompatHashes::Mapping>> GDExtensionSpecialCompatHashes::mappings;
 
-bool GDExtensionCompatHashes::lookup_current_hash(const StringName &p_class, const StringName &p_method, uint32_t p_legacy_hash, uint32_t *r_current_hash) {
+bool GDExtensionSpecialCompatHashes::lookup_current_hash(const StringName &p_class, const StringName &p_method, uint32_t p_legacy_hash, uint32_t *r_current_hash) {
 	LocalVector<Mapping> *methods = mappings.getptr(p_class);
 	if (!methods) {
 		return false;
@@ -53,7 +53,7 @@ bool GDExtensionCompatHashes::lookup_current_hash(const StringName &p_class, con
 	return false;
 }
 
-bool GDExtensionCompatHashes::get_legacy_hashes(const StringName &p_class, const StringName &p_method, Array &r_hashes, bool p_check_valid) {
+bool GDExtensionSpecialCompatHashes::get_legacy_hashes(const StringName &p_class, const StringName &p_method, Array &r_hashes, bool p_check_valid) {
 	LocalVector<Mapping> *methods = mappings.getptr(p_class);
 	if (!methods) {
 		return false;
@@ -65,7 +65,7 @@ bool GDExtensionCompatHashes::get_legacy_hashes(const StringName &p_class, const
 			if (p_check_valid) {
 				MethodBind *mb = ClassDB::get_method_with_compatibility(p_class, p_method, mapping.current_hash);
 				if (!mb) {
-					WARN_PRINT(vformat("Compatibility hash %d for %s::%s() mapped to non-existent hash %d. Please update gdextension_compat_hashes.cpp.", mapping.legacy_hash, p_class, p_method, mapping.current_hash));
+					WARN_PRINT(vformat("Compatibility hash %d for %s::%s() mapped to non-existent hash %d. Please update gdextension_special_compat_hashes.cpp.", mapping.legacy_hash, p_class, p_method, mapping.current_hash));
 					continue;
 				}
 			}
@@ -77,7 +77,7 @@ bool GDExtensionCompatHashes::get_legacy_hashes(const StringName &p_class, const
 	return found;
 }
 
-void GDExtensionCompatHashes::initialize() {
+void GDExtensionSpecialCompatHashes::initialize() {
 	// clang-format off
 	mappings.insert("AESContext", {
 		{ "start", 3167574919, 3122411423 },
@@ -1013,7 +1013,7 @@ void GDExtensionCompatHashes::initialize() {
 	// clang-format on
 }
 
-void GDExtensionCompatHashes::finalize() {
+void GDExtensionSpecialCompatHashes::finalize() {
 	mappings.clear();
 }
 

core/extension/gdextension_compat_hashes.h → core/extension/gdextension_special_compat_hashes.h

@@ -1,5 +1,5 @@
 /**************************************************************************/
-/*  gdextension_compat_hashes.h                                           */
+/*  gdextension_special_compat_hashes.h                                   */
 /**************************************************************************/
 /*                         This file is part of:                          */
 /*                             GODOT ENGINE                               */
@@ -28,8 +28,8 @@
 /* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                 */
 /**************************************************************************/
 
-#ifndef GDEXTENSION_COMPAT_HASHES_H
-#define GDEXTENSION_COMPAT_HASHES_H
+#ifndef GDEXTENSION_SPECIAL_COMPAT_HASHES_H
+#define GDEXTENSION_SPECIAL_COMPAT_HASHES_H
 
 #ifndef DISABLE_DEPRECATED
 
@@ -37,7 +37,11 @@
 #include "core/templates/hash_map.h"
 #include "core/templates/local_vector.h"
 
-class GDExtensionCompatHashes {
+// Note: In most situations, compatibility methods should be registered via ClassDB::bind_compatibility_method().
+//       This class is only meant to be used in exceptional circumstances, for example, when Godot's hashing
+//       algorithm changes and registering compatibility methods for all affect methods would be onerous.
+
+class GDExtensionSpecialCompatHashes {
 	struct Mapping {
 		StringName method;
 		uint32_t legacy_hash;
@@ -55,4 +59,4 @@ public:
 
 #endif // DISABLE_DEPRECATED
 
-#endif // GDEXTENSION_COMPAT_HASHES_H
+#endif // GDEXTENSION_SPECIAL_COMPAT_HASHES_H