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()`

2 files changed, 23 insertions, 0 deletions

diff --git a/modules/visual_script/visual_script.cpp b/modules/visual_script/visual_script.cpp
index 581809fec9..8f311d11f4 100644
--- a/modules/visual_script/visual_script.cpp
+++ b/modules/visual_script/visual_script.cpp
@@ -30,6 +30,7 @@
 
 #include "visual_script.h"
 
+#include "core/core_string_names.h"
 #include "core/os/os.h"
 #include "core/project_settings.h"
 #include "scene/main/node.h"
@@ -1976,6 +1977,27 @@ void VisualScriptInstance::notification(int p_notification) {
 	call(VisualScriptLanguage::singleton->notification, &whatp, 1, ce); //do as call
 }
 
+String VisualScriptInstance::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> VisualScriptInstance::get_script() const {
 
 	return script;
diff --git a/modules/visual_script/visual_script.h b/modules/visual_script/visual_script.h
index 0171b8e6f1..91748d077b 100644
--- a/modules/visual_script/visual_script.h
+++ b/modules/visual_script/visual_script.h
@@ -405,6 +405,7 @@ public:
 	virtual bool has_method(const StringName &p_method) const;
 	virtual Variant call(const StringName &p_method, const Variant **p_args, int p_argcount, Variant::CallError &r_error);
 	virtual void notification(int p_notification);
+	String to_string(bool *r_valid);
 
 	bool set_variable(const StringName &p_variable, const Variant &p_value) {