Implement Structs in GDScript

.gitignore

@@ -390,3 +390,4 @@ $RECYCLE.BIN/
 *.msp
 *.lnk
 *.generated.props
+.gdbinit

core/extension/extension_api_dump.cpp

@@ -40,6 +40,9 @@
 #include "core/templates/pair.h"
 #include "core/version.h"
 
+// Forward declaration for struct type
+class GDScriptStructInstance;
+
 #ifdef TOOLS_ENABLED
 #include "editor/doc/editor_help.h"
 
@@ -210,6 +213,7 @@ Dictionary GDExtensionAPIDump::generate_extension_api(bool p_include_docs) {
 			{ Variant::NODE_PATH, ptrsize_32, ptrsize_64, ptrsize_32, ptrsize_64 },
 			{ Variant::RID, sizeof(uint64_t), sizeof(uint64_t), sizeof(uint64_t), sizeof(uint64_t) },
 			{ Variant::OBJECT, ptrsize_32, ptrsize_64, ptrsize_32, ptrsize_64 },
+			{ Variant::STRUCT, ptrsize_32, ptrsize_64, ptrsize_32, ptrsize_64 },
 			{ Variant::CALLABLE, sizeof(Callable), sizeof(Callable), sizeof(Callable), sizeof(Callable) }, // Hardcoded align.
 			{ Variant::SIGNAL, sizeof(Signal), sizeof(Signal), sizeof(Signal), sizeof(Signal) }, // Hardcoded align.
 			{ Variant::DICTIONARY, ptrsize_32, ptrsize_64, ptrsize_32, ptrsize_64 },
@@ -252,6 +256,7 @@ Dictionary GDExtensionAPIDump::generate_extension_api(bool p_include_docs) {
 		static_assert(type_size_array[Variant::NODE_PATH][sizeof(void *)] == sizeof(NodePath), "Size of NodePath mismatch");
 		static_assert(type_size_array[Variant::RID][sizeof(void *)] == sizeof(RID), "Size of RID mismatch");
 		static_assert(type_size_array[Variant::OBJECT][sizeof(void *)] == sizeof(Object *), "Size of Object mismatch");
+		static_assert(type_size_array[Variant::STRUCT][sizeof(void *)] == sizeof(GDScriptStructInstance *), "Size of Struct mismatch");
 		static_assert(type_size_array[Variant::CALLABLE][sizeof(void *)] == sizeof(Callable), "Size of Callable mismatch");
 		static_assert(type_size_array[Variant::SIGNAL][sizeof(void *)] == sizeof(Signal), "Size of Signal mismatch");
 		static_assert(type_size_array[Variant::DICTIONARY][sizeof(void *)] == sizeof(Dictionary), "Size of Dictionary mismatch");

core/extension/gdextension_interface.cpp

@@ -817,6 +817,11 @@ static GDExtensionPtrOperatorEvaluator gdextension_variant_get_ptr_operator_eval
 	return (GDExtensionPtrOperatorEvaluator)Variant::get_ptr_operator_evaluator(Variant::Operator(p_operator), Variant::Type(p_type_a), Variant::Type(p_type_b));
 }
 static GDExtensionPtrBuiltInMethod gdextension_variant_get_ptr_builtin_method(GDExtensionVariantType p_type, GDExtensionConstStringNamePtr p_method, GDExtensionInt p_hash) {
+	// STRUCT type doesn't support built-in methods
+	if (p_type == (int)Variant::STRUCT) {
+		return nullptr;
+	}
+
 	const StringName method = *reinterpret_cast<const StringName *>(p_method);
 	uint32_t hash = Variant::get_builtin_method_hash(Variant::Type(p_type), method);
 	if (hash != p_hash) {
@@ -827,6 +832,11 @@ static GDExtensionPtrBuiltInMethod gdextension_variant_get_ptr_builtin_method(GD
 	return (GDExtensionPtrBuiltInMethod)Variant::get_ptr_builtin_method(Variant::Type(p_type), method);
 }
 static GDExtensionPtrConstructor gdextension_variant_get_ptr_constructor(GDExtensionVariantType p_type, int32_t p_constructor) {
+	// STRUCT type doesn't support constructors (yet)
+	if (p_type == (int)Variant::STRUCT) {
+		return nullptr;
+	}
+
 	return (GDExtensionPtrConstructor)Variant::get_ptr_constructor(Variant::Type(p_type), p_constructor);
 }
 static GDExtensionPtrDestructor gdextension_variant_get_ptr_destructor(GDExtensionVariantType p_type) {

core/io/json.cpp

@@ -35,6 +35,38 @@
 #include "core/config/engine.h"
 #include "core/object/script_language.h"
 #include "core/variant/container_type_validate.h"
+#include "core/variant/variant_internal.h"
+
+// GDScript struct serialization support
+// Guarded with MODULE_GDSCRIPT_ENABLED since core/io can't depend on modules/gdscript
+#ifdef MODULE_GDSCRIPT_ENABLED
+// Forward declaration for GDScript struct serialization
+class GDScriptStructInstance;
+class GDScriptStruct;
+
+// We need to declare these methods without including the GDScript headers
+// This is a bit of a hack, but necessary due to layering (core/io can't include modules/gdscript)
+// In the future, this should be replaced with a proper Variant-level API
+
+extern "C" {
+// These will be defined in gdscript.cpp with C linkage to avoid name mangling issues
+Dictionary gdscript_struct_instance_serialize(const GDScriptStructInstance *p_instance);
+bool gdscript_struct_instance_get_type_name(const GDScriptStructInstance *p_instance, String &r_name);
+}
+
+// Helper function to serialize a struct
+static Dictionary _serialize_struct(const GDScriptStructInstance *p_instance) {
+	ERR_FAIL_NULL_V(p_instance, Dictionary());
+
+	// Call the GDScript helper function
+	return gdscript_struct_instance_serialize(p_instance);
+}
+#else
+// Stub implementation when GDScript module is disabled
+static Dictionary _serialize_struct(const void *p_instance) {
+	ERR_FAIL_V_MSG(Dictionary(), "STRUCT serialization requires MODULE_GDSCRIPT_ENABLED.");
+}
+#endif // MODULE_GDSCRIPT_ENABLED
 
 const char *JSON::tk_name[TK_MAX] = {
 	"'{'",
@@ -824,6 +856,50 @@ Variant JSON::_from_native(const Variant &p_variant, bool p_full_objects, int p_
 			return ret;
 		} break;
 
+#ifdef MODULE_GDSCRIPT_ENABLED
+		case Variant::STRUCT: {
+			// Serialize struct as tagged dictionary with __type__ metadata
+			// This allows round-trip deserialization
+			const GDScriptStructInstance *struct_instance = reinterpret_cast<const GDScriptStructInstance *>(VariantInternal::get_struct(&p_variant));
+			ERR_FAIL_NULL_V(struct_instance, Variant());
+
+			Dictionary ret;
+			ret[TYPE] = Variant::get_type_name(p_variant.get_type());
+
+			// Get the serialized data from the struct instance using helper
+			Dictionary struct_data = _serialize_struct(struct_instance);
+
+			// Ensure __type__ field exists (it should from serialize())
+			if (!struct_data.has("__type__")) {
+				ERR_FAIL_V_MSG(Variant(), "Struct serialization failed: missing __type__ field.");
+			}
+
+			// Encode field values using _from_native to ensure proper JSON encoding
+			// This handles non-JSON-native types (nested structs, objects, typed arrays, etc.)
+			Dictionary encoded_struct_data;
+			encoded_struct_data["__type__"] = struct_data["__type__"]; // Copy type identifier as-is
+
+			for (const KeyValue<Variant, Variant> &kv : struct_data) {
+				if (kv.key == "__type__") {
+					continue; // Already copied above
+				}
+				// Encode the value using _from_native, keys are strings (field names) and don't need encoding
+				encoded_struct_data[kv.key] = _from_native(kv.value, p_full_objects, p_depth + 1);
+			}
+
+			// Wrap the encoded serialized data in the expected format
+			Array args;
+			args.push_back(encoded_struct_data);
+			ret[ARGS] = args;
+
+			return ret;
+		} break;
+#else
+		case Variant::STRUCT: {
+			ERR_FAIL_V_MSG(Variant(), "STRUCT serialization requires MODULE_GDSCRIPT_ENABLED.");
+		} break;
+#endif // MODULE_GDSCRIPT_ENABLED
+
 		case Variant::DICTIONARY: {
 			const Dictionary dict = p_variant;
 
@@ -1297,6 +1373,44 @@ Variant JSON::_to_native(const Variant &p_json, bool p_allow_objects, int p_dept
 					// Nothing to do at this stage. `Object` should be treated as a class, not as a built-in type.
 				} break;
 
+#ifdef MODULE_GDSCRIPT_ENABLED
+				case Variant::STRUCT: {
+					// Deserialize struct from tagged dictionary
+					LOAD_ARGS();
+
+					ERR_FAIL_COND_V_MSG(args.size() != 1, Variant(), "Invalid struct data: expected single dictionary argument.");
+
+					Dictionary encoded_data = args[0];
+					ERR_FAIL_COND_V_MSG(!encoded_data.has("__type__"), Variant(), "Invalid struct data: missing __type__ field.");
+
+					String type_name = encoded_data["__type__"];
+					ERR_FAIL_COND_V_MSG(type_name.is_empty(), Variant(), "Invalid struct data: empty __type__ field.");
+
+					// Decode field values using _to_native to properly reconstruct non-JSON-native types
+					// This handles nested structs, objects, typed arrays, etc.
+					Dictionary decoded_struct_data;
+					decoded_struct_data["__type__"] = encoded_data["__type__"]; // Copy type identifier as-is
+
+					for (const KeyValue<Variant, Variant> &kv : encoded_data) {
+						if (kv.key == "__type__") {
+							continue; // Already copied above
+						}
+						// Decode the value using _to_native, keys are strings (field names) and don't need decoding
+						decoded_struct_data[kv.key] = _to_native(kv.value, p_allow_objects, p_depth + 1);
+					}
+
+					// Use ScriptServer to create the struct instance with decoded data
+					Variant struct_instance = ScriptServer::create_struct_instance(type_name, decoded_struct_data);
+					ERR_FAIL_COND_V_MSG(struct_instance.get_type() != Variant::STRUCT, Variant(), vformat("Failed to create struct instance for type '%s'.", type_name));
+
+					return struct_instance;
+				} break;
+#else
+				case Variant::STRUCT: {
+					ERR_FAIL_V_MSG(Variant(), "STRUCT deserialization requires MODULE_GDSCRIPT_ENABLED.");
+				} break;
+#endif // MODULE_GDSCRIPT_ENABLED
+
 				case Variant::DICTIONARY: {
 					LOAD_ARGS_CHECK_FACTOR(2);
 

core/object/script_language.cpp

@@ -550,6 +550,48 @@ void ScriptServer::save_global_classes() {
 	ProjectSettings::get_singleton()->store_global_class_list(gcarr);
 }
 
+/***************** STRUCT SERIALIZATION *****************/
+
+Variant ScriptServer::create_struct_instance(const String &p_fully_qualified_name, const Dictionary &p_data) {
+	MutexLock lock(languages_mutex);
+	if (!languages_ready) {
+		ERR_FAIL_V_MSG(Variant(), "Cannot create struct instance: languages not initialized.");
+	}
+
+	// Try each language to see if it can create the struct
+	for (int i = 0; i < _language_count; i++) {
+		ScriptLanguage *lang = _languages[i];
+		if (lang && lang->can_create_struct_by_name()) {
+			Variant result = lang->create_struct_by_name(p_fully_qualified_name, p_data);
+			if (result.get_type() != Variant::NIL) {
+				return result;
+			}
+		}
+	}
+
+	ERR_FAIL_V_MSG(Variant(), vformat("Cannot create struct instance: no language supports struct '%s'.", p_fully_qualified_name));
+}
+
+bool ScriptServer::global_struct_exists(const String &p_fully_qualified_name) {
+	MutexLock lock(languages_mutex);
+	if (!languages_ready) {
+		return false;
+	}
+
+	// Check if any language can create this struct
+	for (int i = 0; i < _language_count; i++) {
+		ScriptLanguage *lang = _languages[i];
+		if (lang && lang->can_create_struct_by_name()) {
+			// Try to create with empty data to check if it exists
+			Variant result = lang->create_struct_by_name(p_fully_qualified_name, Dictionary());
+			if (result.get_type() != Variant::NIL) {
+				return true;
+			}
+		}
+	}
+	return false;
+}
+
 Vector<Ref<ScriptBacktrace>> ScriptServer::capture_script_backtraces(bool p_include_variables) {
 	if (is_program_exiting) {
 		return Vector<Ref<ScriptBacktrace>>();

core/object/script_language.h

@@ -104,6 +104,10 @@ class ScriptServer {
 	static void get_inheriters_list(const StringName &p_base_type, List<StringName> *r_classes);
 	static void save_global_classes();
 
+	// Struct serialization utilities (for GDScript)
+	static Variant create_struct_instance(const String &p_fully_qualified_name, const Dictionary &p_data);
+	static bool global_struct_exists(const String &p_fully_qualified_name);
+
 	static Vector<Ref<ScriptBacktrace>> capture_script_backtraces(bool p_include_variables = false);
 
 	static void init_languages();
@@ -446,6 +450,11 @@ class ScriptLanguage : public Object {
 	virtual bool handles_global_class_type(const String &p_type) const { return false; }
 	virtual String get_global_class_name(const String &p_path, String *r_base_type = nullptr, String *r_icon_path = nullptr, bool *r_is_abstract = nullptr, bool *r_is_tool = nullptr) const { return String(); }
 
+	/* STRUCT SERIALIZATION */
+	// These methods allow serialization systems to create struct instances without knowing about GDScript
+	virtual bool can_create_struct_by_name() const { return false; }
+	virtual Variant create_struct_by_name(const String &p_fully_qualified_name, const Dictionary &p_data) { return Variant(); }
+
 	virtual ~ScriptLanguage() {}
 };
 

core/variant/variant.cpp

@@ -37,6 +37,7 @@
 #include "core/io/resource.h"
 #include "core/math/math_funcs.h"
 #include "core/variant/variant_parser.h"
+#include "modules/gdscript/gdscript_struct.h"
 
 PagedAllocator<Variant::Pools::BucketSmall, true> Variant::Pools::_bucket_small;
 PagedAllocator<Variant::Pools::BucketMedium, true> Variant::Pools::_bucket_medium;
@@ -119,6 +120,9 @@ String Variant::get_type_name(Variant::Type p_type) {
 		case OBJECT: {
 			return "Object";
 		}
+		case STRUCT: {
+			return "Struct";
+		}
 		case CALLABLE: {
 			return "Callable";
 		}
@@ -1311,6 +1315,15 @@ void Variant::reference(const Variant &p_variant) {
 				_data.packed_array = PackedArrayRef<Vector4>::create();
 			}
 		} break;
+		case STRUCT: {
+			// Reference the struct instance
+			GDScriptStructInstance *struct_instance = const_cast<GDScriptStructInstance *>(reinterpret_cast<const GDScriptStructInstance *>(p_variant._data._mem));
+			if (struct_instance) {
+				struct_instance->reference();
+			}
+			// Copy the pointer - only copy pointer size, not entire _mem
+			memcpy(_data._mem, p_variant._data._mem, sizeof(void *));
+		} break;
 		default: {
 		}
 	}
@@ -1480,6 +1493,18 @@ void Variant::_clear_internal() {
 		case PACKED_VECTOR4_ARRAY: {
 			PackedArrayRefBase::destroy(_data.packed_array);
 		} break;
+		case STRUCT: {
+			// Unreference the struct instance
+			GDScriptStructInstance *struct_instance = reinterpret_cast<GDScriptStructInstance *>(_data._mem);
+			if (struct_instance) {
+				struct_instance->unreference();
+				if (struct_instance->get_reference_count() == 0) {
+					memdelete(struct_instance);
+				}
+			}
+			// Clear the pointer
+			memset(_data._mem, 0, sizeof(_data._mem));
+		} break;
 		default: {
 			// Not needed, there is no point. The following do not allocate memory:
 			// VECTOR2, VECTOR3, VECTOR4, RECT2, PLANE, QUATERNION, COLOR.
@@ -3490,7 +3515,7 @@ void Variant::construct_from_string(const String &p_string, Variant &r_value, Ob
 
 String Variant::get_construct_string() const {
 	String vars;
-	VariantWriter::write_to_string(*this, vars, nullptr, nullptr, true, true);
+	VariantWriter::write_to_string(*this, vars);
 
 	return vars;
 }

core/variant/variant.h

@@ -67,6 +67,7 @@
 
 class Object;
 class RefCounted;
+class GDScriptStructInstance;
 
 template <typename T>
 class Ref;
@@ -123,6 +124,7 @@ class Variant {
 		NODE_PATH,
 		RID,
 		OBJECT,
+		STRUCT,
 		CALLABLE,
 		SIGNAL,
 		DICTIONARY,
@@ -175,6 +177,7 @@ class Variant {
 
 	friend struct _VariantCall;
 	friend class VariantInternal;
+	friend class GDScriptStructClass; // Needed for proper struct construction
 	// Variant takes 24 bytes when real_t is float, and 40 bytes if double.
 	// It only allocates extra memory for AABB/Transform2D (24, 48 if double),
 	// Basis/Transform3D (48, 96 if double), Projection (64, 128 if double),
@@ -310,6 +313,7 @@ class Variant {
 		true, //NODE_PATH,
 		false, //RID,
 		true, //OBJECT,
+		true, //STRUCT,
 		true, //CALLABLE,
 		true, //SIGNAL,
 		true, //DICTIONARY,