Allow overriding how scripted objects are converted to strings

solves #26796

- ADD `String to_string()` method to Object which can be overriden by `String _to_string()` in scripts
- ADD `String to_string(r_valid)` method to ScriptInstance to allow langauges to control how scripted objects are converted to strings
- IMPLEMENT to_string for GDScriptInstance, VisualScriptInstance, and NativeScriptInstance
- ADD Documentation about `Object.to_string` and `Object._to_string`
- Changed `Variant::operator String` to use `obj->to_string()`

1 files changed, 22 insertions, 0 deletions

diff --git a/modules/gdscript/gdscript.cpp b/modules/gdscript/gdscript.cpp
index 0676317f6e..5e327bdd92 100644
--- a/modules/gdscript/gdscript.cpp
+++ b/modules/gdscript/gdscript.cpp
@@ -30,6 +30,7 @@
 
 #include "gdscript.h"
 
+#include "core/core_string_names.h"
 #include "core/engine.h"
 #include "core/global_constants.h"
 #include "core/io/file_access_encrypted.h"
@@ -1234,6 +1235,27 @@ void GDScriptInstance::notification(int p_notification) {
 	}
 }
 
+String GDScriptInstance::to_string(bool *r_valid) {
+	if (has_method(CoreStringNames::get_singleton()->_to_string)) {
+		Variant::CallError ce;
+		Variant ret = call(CoreStringNames::get_singleton()->_to_string, NULL, 0, ce);
+		if (ce.error == Variant::CallError::CALL_OK) {
+			if (ret.get_type() != Variant::STRING) {
+				if (r_valid)
+					*r_valid = false;
+				ERR_EXPLAIN("Wrong type for " + CoreStringNames::get_singleton()->_to_string + ", must be a String.");
+				ERR_FAIL_V(String());
+			}
+			if (r_valid)
+				*r_valid = true;
+			return ret.operator String();
+		}
+	}
+	if (r_valid)
+		*r_valid = false;
+	return String();
+}
+
 Ref<Script> GDScriptInstance::get_script() const {
 
 	return script;