structs redux

.gitignore

@@ -393,3 +393,5 @@ $RECYCLE.BIN/
 *.msp
 *.lnk
 *.generated.props
+.gdbinit
+CLAUDE.md

core/core_constants.cpp

@@ -776,6 +776,7 @@ void register_global_constants() {
 	BIND_CORE_ENUM_CONSTANT_CUSTOM("TYPE_PACKED_VECTOR3_ARRAY", Variant::PACKED_VECTOR3_ARRAY);
 	BIND_CORE_ENUM_CONSTANT_CUSTOM("TYPE_PACKED_COLOR_ARRAY", Variant::PACKED_COLOR_ARRAY);
 	BIND_CORE_ENUM_CONSTANT_CUSTOM("TYPE_PACKED_VECTOR4_ARRAY", Variant::PACKED_VECTOR4_ARRAY);
+	BIND_CORE_ENUM_CONSTANT_CUSTOM("TYPE_STRUCT", Variant::STRUCT);
 	BIND_CORE_ENUM_CONSTANT_CUSTOM("TYPE_MAX", Variant::VARIANT_MAX);
 
 	//comparison

core/extension/extension_api_dump.cpp

@@ -49,6 +49,9 @@
 #ifdef TOOLS_ENABLED
 #include "editor/doc/editor_help.h"
 
+// Forward declaration for struct type
+class GDScriptStructInstance;
+
 static String get_builtin_or_variant_type_name(const Variant::Type p_type) {
 	if (p_type == Variant::NIL) {
 		return "Variant";
@@ -229,6 +232,7 @@ Dictionary GDExtensionAPIDump::generate_extension_api(bool p_include_docs) {
 			{ Variant::PACKED_VECTOR3_ARRAY, ptrsize_32 * 2, ptrsize_64 * 2, ptrsize_32 * 2, ptrsize_64 * 2 },
 			{ Variant::PACKED_COLOR_ARRAY, ptrsize_32 * 2, ptrsize_64 * 2, ptrsize_32 * 2, ptrsize_64 * 2 },
 			{ Variant::PACKED_VECTOR4_ARRAY, ptrsize_32 * 2, ptrsize_64 * 2, ptrsize_32 * 2, ptrsize_64 * 2 },
+			{ Variant::STRUCT, ptrsize_32, ptrsize_64, ptrsize_32, ptrsize_64 },
 			{ Variant::VARIANT_MAX, sizeof(uint64_t) + sizeof(float) * 4, sizeof(uint64_t) + sizeof(float) * 4, sizeof(uint64_t) + sizeof(double) * 4, sizeof(uint64_t) + sizeof(double) * 4 },
 		};
 
@@ -257,6 +261,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");
@@ -281,6 +286,12 @@ Dictionary GDExtensionAPIDump::generate_extension_api(bool p_include_docs) {
 			Array sizes;
 			for (int j = 0; j <= Variant::VARIANT_MAX; j++) {
 				Variant::Type t = type_size_array[j].type;
+				// Structs are a GDScript-internal type with no GDExtension ABI; keep
+				// them out of the extension API so bindings generators don't try to
+				// emit a (nonexistent) Struct type.
+				if (t == Variant::STRUCT) {
+					continue;
+				}
 				String name = t == Variant::VARIANT_MAX ? String("Variant") : Variant::get_type_name(t);
 				Dictionary d2;
 				d2["name"] = name;
@@ -658,6 +669,11 @@ Dictionary GDExtensionAPIDump::generate_extension_api(bool p_include_docs) {
 			if (i == Variant::OBJECT) {
 				continue;
 			}
+			// Structs are a GDScript-internal type with no GDExtension ABI, so they
+			// are not exposed as a builtin class in the extension API.
+			if (i == Variant::STRUCT) {
+				continue;
+			}
 
 			Variant::Type type = Variant::Type(i);
 

core/extension/gdextension_interface.cpp

@@ -641,6 +641,7 @@ static GDExtensionVariantFromTypeConstructorFunc gdextension_get_variant_from_ty
 			return VariantTypeConstructor<PackedVector4Array>::variant_from_type;
 		case GDEXTENSION_VARIANT_TYPE_PACKED_COLOR_ARRAY:
 			return VariantTypeConstructor<PackedColorArray>::variant_from_type;
+		case GDEXTENSION_VARIANT_TYPE_STRUCT: // Structs are GDScript-internal and have no GDExtension type representation.
 		case GDEXTENSION_VARIANT_TYPE_NIL:
 		case GDEXTENSION_VARIANT_TYPE_VARIANT_MAX:
 			ERR_FAIL_V_MSG(nullptr, "Getting Variant conversion function with invalid type");
@@ -726,6 +727,7 @@ static GDExtensionTypeFromVariantConstructorFunc gdextension_get_variant_to_type
 			return VariantTypeConstructor<PackedVector4Array>::type_from_variant;
 		case GDEXTENSION_VARIANT_TYPE_PACKED_COLOR_ARRAY:
 			return VariantTypeConstructor<PackedColorArray>::type_from_variant;
+		case GDEXTENSION_VARIANT_TYPE_STRUCT: // Structs are GDScript-internal and have no GDExtension type representation.
 		case GDEXTENSION_VARIANT_TYPE_NIL:
 		case GDEXTENSION_VARIANT_TYPE_VARIANT_MAX:
 			ERR_FAIL_V_MSG(nullptr, "Getting Variant conversion function with invalid type");
@@ -811,6 +813,7 @@ static GDExtensionVariantGetInternalPtrFunc gdextension_variant_get_ptr_internal
 			return reinterpret_cast<GDExtensionVariantGetInternalPtrFunc>(static_cast<PackedColorArray *(*)(Variant *)>(VariantInternal::get_color_array));
 		case GDEXTENSION_VARIANT_TYPE_PACKED_VECTOR4_ARRAY:
 			return reinterpret_cast<GDExtensionVariantGetInternalPtrFunc>(static_cast<PackedVector4Array *(*)(Variant *)>(VariantInternal::get_vector4_array));
+		case GDEXTENSION_VARIANT_TYPE_STRUCT: // Structs are GDScript-internal and have no GDExtension type representation.
 		case GDEXTENSION_VARIANT_TYPE_NIL:
 		case GDEXTENSION_VARIANT_TYPE_VARIANT_MAX:
 			ERR_FAIL_V_MSG(nullptr, "Getting Variant get internal pointer function with invalid type.");
@@ -823,6 +826,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) {
@@ -833,6 +841,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/extension/gdextension_interface.h

@@ -122,6 +122,8 @@ typedef enum {
 	GDEXTENSION_VARIANT_TYPE_PACKED_COLOR_ARRAY,
 	GDEXTENSION_VARIANT_TYPE_PACKED_VECTOR4_ARRAY,
 
+	GDEXTENSION_VARIANT_TYPE_STRUCT,
+
 	GDEXTENSION_VARIANT_TYPE_VARIANT_MAX
 } GDExtensionVariantType;
 

core/io/json.cpp

@@ -41,6 +41,35 @@
 #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)
+// TODO: Replace this extern "C" bridge with a proper Variant-level struct serialization
+// API so core/io no longer needs to know about GDScript struct internals.
+
+extern "C" {
+// These will be defined in gdscript.cpp with C linkage to avoid name mangling issues
+void gdscript_struct_instance_serialize(const GDScriptStructInstance *p_instance, Dictionary &r_dict);
+}
+
+// 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
+	Dictionary dict;
+	gdscript_struct_instance_serialize(p_instance, dict);
+	return dict;
+}
+#endif // MODULE_GDSCRIPT_ENABLED
 
 const char *JSON::tk_name[TK_MAX] = {
 	"'{'",
@@ -830,6 +859,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;
 
@@ -1303,6 +1376,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/io/marshalls.cpp

@@ -46,6 +46,18 @@
 #include <climits>
 #include <cstdio>
 
+// GDScript struct serialization support
+// Guarded with MODULE_GDSCRIPT_ENABLED since core/io can't depend on modules/gdscript
+#ifdef MODULE_GDSCRIPT_ENABLED
+
+extern "C" {
+// These functions are defined in modules/gdscript/gdscript.cpp with C linkage
+Error gdscript_variant_encode_struct(const Variant &p_variant, uint8_t *r_buffer, int &r_len);
+Error gdscript_variant_decode_struct(const uint8_t *p_buffer, int p_len, int *r_len, Variant &r_variant);
+}
+
+#endif // MODULE_GDSCRIPT_ENABLED
+
 void EncodedObjectAsID::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("set_object_id", "id"), &EncodedObjectAsID::set_object_id);
 	ClassDB::bind_method(D_METHOD("get_object_id"), &EncodedObjectAsID::get_object_id);
@@ -1302,6 +1314,24 @@ Error decode_variant(Variant &r_variant, const uint8_t *p_buffer, int p_len, int
 			r_variant = varray;
 
 		} break;
+#ifdef MODULE_GDSCRIPT_ENABLED
+		case Variant::STRUCT: {
+			// Decode struct via GDScript helper function.
+			// The helper resets its length counter internally, so pass a local
+			// accumulator and add the bytes it consumed to r_len (which already
+			// counts the STRUCT header) instead of letting it overwrite it.
+			int used = 0;
+			Error err = gdscript_variant_decode_struct(buf, len, &used, r_variant);
+			ERR_FAIL_COND_V(err, err);
+			if (r_len) {
+				(*r_len) += used;
+			}
+		} break;
+#else
+		case Variant::STRUCT: {
+			ERR_FAIL_V(ERR_BUG);
+		} break;
+#endif
 		default: {
 			ERR_FAIL_V(ERR_BUG);
 		}
@@ -2130,6 +2160,22 @@ Error encode_variant(const Variant &p_variant, uint8_t *r_buffer, int &r_len, bo
 			r_len += sizeof(real_t) * 4 * len;
 
 		} break;
+#ifdef MODULE_GDSCRIPT_ENABLED
+		case Variant::STRUCT: {
+			// Encode struct via GDScript helper function.
+			// The helper resets its length counter to 0 internally, so pass a
+			// local accumulator and add it to r_len (which already counts the
+			// STRUCT header) instead of letting it clobber the outer accounting.
+			int used = 0;
+			Error err = gdscript_variant_encode_struct(p_variant, buf, used);
+			ERR_FAIL_COND_V(err, err);
+			r_len += used;
+		} break;
+#else
+		case Variant::STRUCT: {
+			ERR_FAIL_V(ERR_BUG);
+		} break;
+#endif
 		default: {
 			ERR_FAIL_V(ERR_BUG);
 		}

core/object/object.cpp

@@ -854,6 +854,20 @@ Variant Object::callp(const StringName &p_method, const Variant **p_args, int p_
 	Variant ret;
 	OBJ_DEBUG_LOCK
 
+#ifdef MODULE_GDSCRIPT_ENABLED
+	// Special case for GDScriptStructClass to support struct constructors
+	// This is needed because GDScriptStructClass::callp needs to be called directly,
+	// but callp is not virtual so Object::callp doesn't dispatch to it.
+	if (get_class_name() == StringName("GDScriptStructClass")) {
+		// Forward to GDScriptStructClass::callp by using a Callable
+		Callable callable = Callable(this, p_method);
+		if (callable.is_valid()) {
+			callable.callp(p_args, p_argcount, ret, r_error);
+			return ret;
+		}
+	}
+#endif
+
 	if (script_instance) {
 		ret = script_instance->callp(p_method, p_args, p_argcount, r_error);
 		// Force jump table.