From 30f2a30f9bb539eb3631fec8559e61a362774f6e Mon Sep 17 00:00:00 2001
From: Danil Alexeev <dalexeev12@yandex.ru>
Date: Mon, 4 May 2026 11:38:49 +0300
Subject: [PATCH] GDScript: Preserve compatibility for untyped return of
 `_get_property_list()`

---
 doc/classes/Object.xml                        |  2 +-
 modules/gdscript/gdscript.cpp                 | 41 ++++++++++++++++++-
 modules/gdscript/gdscript.h                   |  3 +-
 modules/gdscript/gdscript_analyzer.cpp        | 14 +++++++
 .../errors/compat_get_property_list.gd        | 20 +++++++++
 .../errors/compat_get_property_list.out       |  6 +++
 .../errors/compat_get_property_list.gd        | 36 ++++++++++++++++
 .../errors/compat_get_property_list.out       |  6 +++
 8 files changed, 125 insertions(+), 3 deletions(-)
 create mode 100644 modules/gdscript/tests/scripts/analyzer/errors/compat_get_property_list.gd
 create mode 100644 modules/gdscript/tests/scripts/analyzer/errors/compat_get_property_list.out
 create mode 100644 modules/gdscript/tests/scripts/runtime/errors/compat_get_property_list.gd
 create mode 100644 modules/gdscript/tests/scripts/runtime/errors/compat_get_property_list.out

diff --git a/doc/classes/Object.xml b/doc/classes/Object.xml
index 7a83f77835..058162ae8a 100644
--- a/doc/classes/Object.xml
+++ b/doc/classes/Object.xml
@@ -97,7 +97,7 @@
 				var numbers = PackedInt32Array([0, 0, 0])
 
 				func _get_property_list():
-					var properties = []
+					var properties: Array[Dictionary] = []
 
 					for i in range(number_count):
 						properties.append({
diff --git a/modules/gdscript/gdscript.cpp b/modules/gdscript/gdscript.cpp
index 0fb2de8914..f9f9567ec2 100644
--- a/modules/gdscript/gdscript.cpp
+++ b/modules/gdscript/gdscript.cpp
@@ -1741,9 +1741,48 @@ void GDScriptInstance::get_property_list(List<PropertyInfo> *p_properties) const
 				Callable::CallError err;
 				Variant ret = E->value->call(const_cast<GDScriptInstance *>(this), nullptr, 0, err);
 				if (err.error == Callable::CallError::CALL_OK) {
-					ERR_FAIL_COND_MSG(ret.get_type() != Variant::ARRAY, "Wrong type for _get_property_list, must be an array of dictionaries.");
+					// GH-118877. We decided to make an exception to maintain compatibility, since the problem can only be detected at runtime.
+#ifdef DISABLE_DEPRECATED
+					ERR_FAIL_COND_MSG(ret.get_type() != Variant::ARRAY, R"*(Wrong type for "_get_property_list()", must be "Array[Dictionary]".)*");
+#else // !DISABLE_DEPRECATED
+					ERR_FAIL_COND_MSG(ret.get_type() != Variant::ARRAY, R"*(Wrong type for "_get_property_list()", must be an array of dictionaries.)*");
+#endif // DISABLE_DEPRECATED
 
 					Array arr = ret;
+
+					// GH-118877. We decided to make an exception to maintain compatibility, since the problem can only be detected at runtime.
+#ifdef DISABLE_DEPRECATED
+					ERR_FAIL_COND_MSG(arr.get_typed_builtin() != Variant::DICTIONARY, R"*(Wrong type for "_get_property_list()", must be "Array[Dictionary]".)*");
+#else // !DISABLE_DEPRECATED
+#ifdef DEBUG_ENABLED
+					if (arr.get_typed_builtin() != Variant::DICTIONARY) {
+						static bool error_shown = false;
+						if (unlikely(!error_shown)) {
+							error_shown = true;
+
+							String elem_type;
+							if (arr.is_typed()) {
+								const Ref<Script> script_type = arr.get_typed_script();
+								if (script_type.is_valid() && script_type->is_valid()) {
+									elem_type = GDScript::debug_get_script_name(script_type);
+								} else if (!arr.get_typed_class_name().is_empty()) {
+									elem_type = arr.get_typed_class_name();
+								} else {
+									elem_type = Variant::get_type_name((Variant::Type)arr.get_typed_builtin());
+								}
+								elem_type = vformat("[%s]", elem_type);
+							}
+
+							String msg = vformat(R"*("_get_property_list()" should return "Array[Dictionary]", not "Array%s".)*", elem_type);
+							msg += " The old behavior is supported for compatibility and may be removed in the future.";
+							msg += " This message is printed once and will not be repeated for similar errors.";
+
+							ERR_PRINT(msg);
+						}
+					}
+#endif // DEBUG_ENABLED
+#endif // DISABLE_DEPRECATED
+
 					for (int i = 0; i < arr.size(); i++) {
 						Dictionary d = arr[i];
 						ERR_CONTINUE(!d.has("name"));
diff --git a/modules/gdscript/gdscript.h b/modules/gdscript/gdscript.h
index c36c418fc4..b88596b6fe 100644
--- a/modules/gdscript/gdscript.h
+++ b/modules/gdscript/gdscript.h
@@ -402,7 +402,8 @@ public:
 
 	virtual const Variant get_rpc_config() const;
 
-	GDScriptInstance() : script_instance_list(this) {}
+	GDScriptInstance() :
+			script_instance_list(this) {}
 	~GDScriptInstance();
 };
 
diff --git a/modules/gdscript/gdscript_analyzer.cpp b/modules/gdscript/gdscript_analyzer.cpp
index 85cc00cea5..97aeba684e 100644
--- a/modules/gdscript/gdscript_analyzer.cpp
+++ b/modules/gdscript/gdscript_analyzer.cpp
@@ -1876,7 +1876,21 @@ void GDScriptAnalyzer::resolve_function_signature(GDScriptParser::FunctionNode *
 			bool valid = p_function->is_static == method_flags.has_flag(METHOD_FLAG_STATIC);
 
 			if (p_function->return_type == nullptr) {
+				// GH-118877. We decided to make an exception to maintain compatibility, since the problem can only be detected at runtime.
+#ifdef DISABLE_DEPRECATED
 				p_function->set_datatype(parent_return_type);
+#else // !DISABLE_DEPRECATED
+				if (function_name == GDScriptLanguage::get_singleton()->strings._get_property_list && method_flags.has_flag(METHOD_FLAG_VIRTUAL)) {
+					GDScriptParser::DataType array_type;
+					array_type.type_source = GDScriptParser::DataType::ANNOTATED_INFERRED;
+					array_type.kind = GDScriptParser::DataType::BUILTIN;
+					array_type.builtin_type = Variant::ARRAY;
+
+					p_function->set_datatype(array_type);
+				} else {
+					p_function->set_datatype(parent_return_type);
+				}
+#endif // DISABLE_DEPRECATED
 			} else {
 				// Check return type covariance.
 				GDScriptParser::DataType return_type = p_function->get_datatype();
diff --git a/modules/gdscript/tests/scripts/analyzer/errors/compat_get_property_list.gd b/modules/gdscript/tests/scripts/analyzer/errors/compat_get_property_list.gd
new file mode 100644
index 0000000000..9088453eec
--- /dev/null
+++ b/modules/gdscript/tests/scripts/analyzer/errors/compat_get_property_list.gd
@@ -0,0 +1,20 @@
+# GH-118877
+
+class Test1:
+	func _get_property_list() -> Array[int]:
+		return []
+
+class Test2:
+	func _get_property_list() -> int:
+		return 0
+
+class Test3:
+	func _get_property_list() -> void:
+		pass
+
+class Test4:
+	func _get_property_list():
+		return 0
+
+func test():
+	pass
diff --git a/modules/gdscript/tests/scripts/analyzer/errors/compat_get_property_list.out b/modules/gdscript/tests/scripts/analyzer/errors/compat_get_property_list.out
new file mode 100644
index 0000000000..6c0dd469b5
--- /dev/null
+++ b/modules/gdscript/tests/scripts/analyzer/errors/compat_get_property_list.out
@@ -0,0 +1,6 @@
+GDTEST_ANALYZER_ERROR
+>> ERROR at line 4: The function signature doesn't match the parent. Parent signature is "_get_property_list() -> Array[Dictionary]".
+>> ERROR at line 8: The function signature doesn't match the parent. Parent signature is "_get_property_list() -> Array[Dictionary]".
+>> ERROR at line 12: The function signature doesn't match the parent. Parent signature is "_get_property_list() -> Array[Dictionary]".
+>> ERROR at line 17: Cannot return a value of type "int" as "Array".
+>> ERROR at line 17: Cannot return value of type "int" because the function return type is "Array".
diff --git a/modules/gdscript/tests/scripts/runtime/errors/compat_get_property_list.gd b/modules/gdscript/tests/scripts/runtime/errors/compat_get_property_list.gd
new file mode 100644
index 0000000000..ab65df5543
--- /dev/null
+++ b/modules/gdscript/tests/scripts/runtime/errors/compat_get_property_list.gd
@@ -0,0 +1,36 @@
+# GH-118877
+
+class Test1:
+	func _get_property_list():
+		return [
+			{ "name": "test_property", "type": TYPE_INT },
+		]
+
+class Test2:
+	func _get_property_list():
+		var properties = []
+
+		properties.append({ "name": "test_property", "type": TYPE_INT })
+
+		return properties
+
+class Test3:
+	func _get_property_list() -> Array[Dictionary]:
+		var properties = []
+
+		properties.append({ "name": "test_property", "type": TYPE_INT })
+
+		return properties
+
+func check(instance: Object) -> void:
+	var has_property: bool = false
+	for property in instance.get_property_list():
+		if str(property.name) == "test_property":
+			has_property = true
+			break
+	print(has_property)
+
+func test():
+	check(Test1.new())
+	check(Test2.new())
+	check(Test3.new())
diff --git a/modules/gdscript/tests/scripts/runtime/errors/compat_get_property_list.out b/modules/gdscript/tests/scripts/runtime/errors/compat_get_property_list.out
new file mode 100644
index 0000000000..221f927ed7
--- /dev/null
+++ b/modules/gdscript/tests/scripts/runtime/errors/compat_get_property_list.out
@@ -0,0 +1,6 @@
+GDTEST_RUNTIME_ERROR
+>> ERROR: "_get_property_list()" should return "Array[Dictionary]", not "Array". The old behavior is supported for compatibility and may be removed in the future. This message is printed once and will not be repeated for similar errors.
+true
+true
+>> SCRIPT ERROR at runtime/errors/compat_get_property_list.gd:23 on Test3._get_property_list(): Trying to return a value of type "Array" from a function whose return type is "Array[Dictionary]".
+false