C#: Represent Variant as its own type instead of System.Object

[neikeq]

Currently, we represent Variant in C# with the object type (System.Object). We convert Variant values to the managed type that best matches the Variant type and return the result as object.

This has the following downsides:

1. Converting to and from native Variant results in boxing of basic value types (like int, or Vector2).
2. Converting object to a native Variant (ConvertManagedObjectToVariant):
   2.1. Requires runtime type checking.
   2.2. In the case of System.Collections.Generic types, we need to box value type items.
   2.3. Easy to attempt to create/marshal a Variant with an unsupported type. It's not obvious which types are supported and this results in a nil Variant and a runtime error.
3. Converting a native Variant to object (ConvertVariantToManagedObjectOfType):
   3.1. Requires runtime type checking.
   3.2. Requires reflection when dealing with generic types (e.g., to access the constructor dynamically).
4. Confusing InvalidCastException when casting the object to int.
   Variant stores 64-bit integers, so the boxed value is of type long. You can't cast a boxed long to int. You need to unbox it first and then do the cast:

   object boxed = (long)10;
   _ = (int)boxed; // Exception. Not casting, rather unboxing with the wrong type.
   _ = (int)(long)boxed; // Good. Unbox with the right type and then cast.

I propose solving these problems with the addition of a C# Variant type that replaces object in this regard.

Layout

public struct Variant
{
    short _type;
    godot_variant_basic_data _data;
    object _obj;
}

The _data field is a union that stores all basic value types. That is, types that do not require disposal:

// Variant types that don't need disposal
Bool, Int, Float
Vector2, Vector2i
Rect2, Rect2i
Vector3, Vector3i
Plane
Quaternion
Color
Rid

✔️ We don't need to box the values in the _data field (1.), it's a union of value types.

The content of the _obj field depends on whether we want lazy marshaling or not.

Lazy marshaling

We assign the _obj field with a wrapper containing the native Variant itself. No marshaling is done until the user actually attempts a type conversion.

This results in an extra allocation (the wrapper) if a conversion is eventually requested.
The wrapper (like other Godot type disposables) also has the overhead of needing to be registered/unregistered for disposal on hot-reload and app exit.

This version wins when dealing with many Variants whose value ends up not being accessed. I don't think this is very common, so it doesn't seem to be worth the downsides.

Eager marshaling

We assign the _obj field when the Variant type needs disposal. The types in this case are:

String

Transform2d, AABB, Basis, Transform3d

StringName, NodePath
Object
Callable, Signal
Dictionary, Array

Packed*Array

The value types Transform2d, AABB, Basis and Transform3d could actually go in the _data union, but they are too large. The native Variant itself mallocs them to keep the struct small, so it seems right for us to do the same. In our case, we box them.

Conversions

Creation of the Variant from a target type is implicit (implicit operator overload) for most types (generic types require a method call because overloaded operators cannot be generic).
✔️ This removes the need for runtime type checking (2.1.).
✔️ Since the method can be generic (e.g., ToVariant<T>(this List<T>)) we can avoid boxing value type items of System.Collections.Generic collections (2.2.).
✔️ Attempting to create a Variant from an unsupported type results in a compiler error rather than a runtime error and a nil Variant (2.3.).

Conversion from the Variant struct to a target type is done either via AsTypeName() methods or explicit cast operators.
✔️ This removes the need for runtime type checking (3.1.).
✔️ Since the method can be generic (e.g., AsList<T>()) there's no need for reflection when dealing with generic types (3.2.).

✔️ Since we don't box primitives, and we control conversion, we're no longer required to unbox to long before casting to int (4.).

Type checking

We can add a Type property for checking the Variant type.

Variant won't benefit from pattern matching like is and switch patterns:

// Forget about this
if (variant is Node node) { /* ... */ }

// It's now like this
if (variant.Type == Variant.Type.Object)
{
    var godotObj = variant.ToObject();
    if (godotObj is Node node) { /* ... */ }
}

While it should not be very common to deal with Variant directly, we may still want to add some helper members to help reduce that bloat:

bool IsObject<T>(out T obj) where T : Godot.Object { /* ... */ }

if (variant.IsObject(out Node node)) { /* ... */ }

That won't be of help with switch patterns, though.

We could add a getter for the _obj field:

if (variant.Obj is Node node) { /* ... */ }

switch (variant.Obj) {
case Node node: break;
case Array array: break;
}

[Pilvinen]

Great proposal. Gotta get those difficult issues resolved.

However. Please hear me out.

Do we really have to call it a "Variant" just because GDScript did that mistake? Variant means nothing.

It's a very ambiguous word. It's almost an adjective. It raises a lot of questions like "What is a variant?", "What does it do?", "Why does it exist?", and "How does it work?"

One of the first things you learn when learning C#, or almost any other modern programming language, is what an object is. So when you have something like Godot.Object, you immediately go "Oh, ok. I get it! It's a base type for all things Godot!" Natural, intuitive, and supported by your prior learning and experience. Your knowledge translates well between different paradigms due to similarity of the concepts. C# object -> Godot object? No problem.

Now.

If you arbitrarily go and change the name into something more ambiguous like a "Variant" you are, unintentionally, creating a learning gap. People will now have to go out of their way to unlearn what they already know and learn a new concept instead of smoothly transitioning their prior knowledge from C# or other programming languages to the concept of "Godot.Object".

To further back up my opinion, according to modern research on learning similarity between concepts in programming languages - or any other subject field for that matter - helps in transference of learning, eg. if you know how objects work in Java, you're probably not going to have hard time transferring your prior understanding on the subject to C#.

Finally, I would again like to say, great proposal. But please keep the intuitive and obvious name choice Object rather than replace it with Variant. There might be technical reasons that I do not understand why this is simply not possible. But if there's a way, please consider it.

Thank you.

[neikeq]

Godot.Object is already not a base type for all things Godot. What we're currently using for Variant is System.Object (C#'s ultimate base class).
Unlike many OOP languages, like C#, not all Godot types inherit the Godot Object class. In fact, that's precisely why Variant exists, which holds 33~ types in addition to Godot Object.

I don't know if Variant is the best name choice, but it's what Godot uses. Going with a different one would only cause more confusion. We definitely can't go with Object as that's already picked.

Lastly, the more scripts can avoid dealing with Variant, the better. There are some APIs that require it (due to their dynamic typing nature) but that should be the exception, not the norm.

[Shadowblitz16]

No thankyou.
I don't want to lose out on C# type checking features because Godot decided to roll it's own object class.
Also C# has 9000% better type checking features then GDScript has if we do this then it won't

[neikeq]

@Shadowblitz16 Check the last part, where I said we can add an Obj property that would return a System.Object like the one we have now, in case you want that. This would only be allocated if the property is called.

[Shadowblitz16]

Why can't you just wrap the godot object into a C# object and provide interfaces that way?

[neikeq]

Why can't you just wrap the godot object into a C# object and provide interfaces that way?

I'm not sure I understand what this means, can you elaborate more?

[Shadowblitz16]

Why can't you just wrap the godot object into a C# object and provide interfaces that way?

I'm not sure I understand what this means, can you elaborate more?

instead of wrapping a system object into a custom Godot variant object do the opposite.
make a custom Godot variant object that handles things like marshaling behind the scenes

[GeorgeS2019]

C# Godot 4.0 Roadmap: 4 => Committed to dotnet6 branch: C#: Add dedicated Variant struct, replacing System.Object

[tvardero]

Will I be wrong saying that Variant type in Godot == dynamic type in C# (link1, link2)?