From 07f8935c6965513ff030aa647eef71a284058bec Mon Sep 17 00:00:00 2001
From: Danil Alexeev <dalexeev12@yandex.ru>
Date: Fri, 3 Jan 2025 21:17:06 +0300
Subject: [PATCH] GDScript: Deprecate `inst_to_dict()` and `dict_to_inst()`
 functions

---
 modules/gdscript/doc_classes/@GDScript.xml      | 7 ++++---
 modules/gdscript/gdscript_utility_functions.cpp | 6 ++++--
 2 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/modules/gdscript/doc_classes/@GDScript.xml b/modules/gdscript/doc_classes/@GDScript.xml
index 1f7bb9d2fb3..caed2a808d4 100644
--- a/modules/gdscript/doc_classes/@GDScript.xml
+++ b/modules/gdscript/doc_classes/@GDScript.xml
@@ -74,7 +74,7 @@
 				[/codeblock]
 			</description>
 		</method>
-		<method name="dict_to_inst">
+		<method name="dict_to_inst" deprecated="Consider using [method JSON.to_native] or [method Object.get_property_list] instead.">
 			<return type="Object" />
 			<param index="0" name="dictionary" type="Dictionary" />
 			<description>
@@ -103,12 +103,11 @@
 				[b]Note:[/b] Calling this function from a [Thread] is not supported. Doing so will return an empty array.
 			</description>
 		</method>
-		<method name="inst_to_dict">
+		<method name="inst_to_dict" deprecated="Consider using [method JSON.from_native] or [method Object.get_property_list] instead.">
 			<return type="Dictionary" />
 			<param index="0" name="instance" type="Object" />
 			<description>
 				Returns the passed [param instance] converted to a Dictionary. Can be useful for serializing.
-				[b]Note:[/b] Cannot be used to serialize objects with built-in scripts attached or objects allocated within built-in scripts.
 				[codeblock]
 				var foo = "bar"
 				func _ready():
@@ -121,6 +120,8 @@
 				[@subpath, @path, foo]
 				[, res://test.gd, bar]
 				[/codeblock]
+				[b]Note:[/b] This function can only be used to serialize objects with an attached [GDScript] stored in a separate file. Objects without an attached script, with a script written in another language, or with a built-in script are not supported.
+				[b]Note:[/b] This function is not recursive, which means that nested objects will not be represented as dictionaries. Also, properties passed by reference ([Object], [Dictionary], [Array], and packed arrays) are copied by reference, not duplicated.
 			</description>
 		</method>
 		<method name="is_instance_of">
diff --git a/modules/gdscript/gdscript_utility_functions.cpp b/modules/gdscript/gdscript_utility_functions.cpp
index 7c468fd42d0..448f8a8fdf4 100644
--- a/modules/gdscript/gdscript_utility_functions.cpp
+++ b/modules/gdscript/gdscript_utility_functions.cpp
@@ -224,6 +224,8 @@ struct GDScriptUtilityFunctionsDefinitions {
 		*r_ret = ResourceLoader::load(*p_args[0]);
 	}
 
+#ifndef DISABLE_DEPRECATED
+
 	static inline void inst_to_dict(Variant *r_ret, const Variant **p_args, int p_arg_count, Callable::CallError &r_error) {
 		DEBUG_VALIDATE_ARG_COUNT(1, 1);
 		DEBUG_VALIDATE_ARG_TYPE(0, Variant::OBJECT);
@@ -315,7 +317,6 @@ struct GDScriptUtilityFunctionsDefinitions {
 		}
 	}
 
-#ifndef DISABLE_DEPRECATED
 	static inline void Color8(Variant *r_ret, const Variant **p_args, int p_arg_count, Callable::CallError &r_error) {
 		DEBUG_VALIDATE_ARG_COUNT(3, 4);
 		DEBUG_VALIDATE_ARG_TYPE(0, Variant::INT);
@@ -330,6 +331,7 @@ struct GDScriptUtilityFunctionsDefinitions {
 
 		*r_ret = Color::from_rgba8(*p_args[0], *p_args[1], *p_args[2], alpha);
 	}
+
 #endif // DISABLE_DEPRECATED
 
 	static inline void print_debug(Variant *r_ret, const Variant **p_args, int p_arg_count, Callable::CallError &r_error) {
@@ -576,9 +578,9 @@ void GDScriptUtilityFunctions::register_functions() {
 	REGISTER_FUNC( _char,          true,  RET(STRING),        ARGS( ARG("char", INT)                ), false, varray(     ));
 	REGISTER_FUNC( range,          false, RET(ARRAY),         NOARGS,                                  true,  varray(     ));
 	REGISTER_FUNC( load,           false, RETCLS("Resource"), ARGS( ARG("path", STRING)             ), false, varray(     ));
+#ifndef DISABLE_DEPRECATED
 	REGISTER_FUNC( inst_to_dict,   false, RET(DICTIONARY),    ARGS( ARG("instance", OBJECT)         ), false, varray(     ));
 	REGISTER_FUNC( dict_to_inst,   false, RET(OBJECT),        ARGS( ARG("dictionary", DICTIONARY)   ), false, varray(     ));
-#ifndef DISABLE_DEPRECATED
 	REGISTER_FUNC( Color8,         true,  RET(COLOR),         ARGS( ARG("r8", INT), ARG("g8", INT),
 																	ARG("b8", INT), ARG("a8", INT)  ), false, varray( 255 ));
 #endif // DISABLE_DEPRECATED