Struct Variant

pub struct Variant { /* private fields */ }

Expand description

Godot variant type, able to store a variety of different types.

While Godot variants do not appear very frequently in Rust due to their lack of compile-time type-safety, they are central to all sorts of dynamic APIs. For example, if you want to call a method on an object based on a string, you will need variants to store arguments and return value.

§Conversions

For type conversions, please read the godot::meta module docs.

§Godot docs

Variant (stable)

Implementations§

§

impl Variant

pub fn nil() -> Variant

Create an empty variant (null value in GDScript).

If a Godot engine API accepts object (not variant) parameters and you’d like to pass null, use Gd::null_arg() instead.

pub fn from<T>(value: T) -> Variant
where T: ToGodot,

Create a variant holding a non-nil value.

Equivalent to value.to_variant(), but consumes the argument.

pub fn to<T>(&self) -> T
where T: FromGodot,

⚠️ Convert to type T, panicking on failure.

Equivalent to T::from_variant(&self).

§Panics

When this variant holds a different type.

pub fn try_to<T>(&self) -> Result<T, ConvertError>
where T: FromGodot,

Convert to type T, returning Err on failure.

The conversion only succeeds if the type stored in the variant matches T’s FFI representation. For lenient conversions like in GDScript, use try_to_relaxed() instead.

Equivalent to T::try_from_variant(&self).

pub fn try_to_relaxed<T>(&self) -> Result<T, ConvertError>
where T: FromGodot,

Convert to T using Godot’s less strict conversion rules.

More lenient than try_to(), which only allows exact type matches. Enables conversions between related types that Godot considers compatible under its conversion rules.

Precisely matches GDScript’s behavior to converts arguments, when a function declares a parameter of different type.

§Conversion diagram

Exhaustive list of all possible conversions, as of Godot 4.4. The arrow ──► means “converts to”.

                                                              * ───► Variant
                                                              * ───► itself (reflexive)
        float          StringName
        ▲   ▲             ▲                            Vector2 ◄───► Vector2i
       ╱     ╲            │                            Vector3 ◄───► Vector3i
      ▼       ▼           ▼                            Vector4 ◄───► Vector4i
   bool ◄───► int       GString ◄───► NodePath           Rect2 ◄───► Rect2i
                ╲       ╱
                 ╲     ╱                              Array<T> ◄───► PackedArray<T>
                  ▼   ▼
                  Color                                   Gd<T> ───► Rid
                                                            nil ───► Option<Gd<T>>

                               Basis ◄───► Quaternion
                                   ╲       ╱
                                    ╲     ╱
                                     ▼   ▼
                Transform2D ◄───► Transform3D ◄───► Projection

§Godot implementation details

See GDExtension interface and C++ implementation (Godot 4.4 at the time of writing). The “strict” part refers to excluding certain conversions, such as between int and GString.

pub fn is_nil(&self) -> bool

Checks whether the variant is empty (null value in GDScript).

pub fn get_type(&self) -> VariantType

Returns the type that is currently held by this variant.

If this variant holds a type Object but no instance (represented as a null object pointer), then Nil will be returned for consistency. This may deviate from Godot behavior – for example, calling Node::get_node_or_null() with an invalid path returns a variant that has type Object but acts like Nil for all practical purposes.

pub fn object_id(&self) -> Option<InstanceId>

For variants holding an object, returns the object’s instance ID.

If the variant is not an object, returns None.

§Panics

If the variant holds an object and that object is dead.

If you want to detect this case, use try_to::<Gd<...>>(). If you want to retrieve the previous instance ID of a freed object for whatever reason, use object_id_unchecked(). This method is only available from Godot 4.4 onwards.

pub fn object_id_unchecked(&self) -> Option<InstanceId>

Available on since_api=4.4 only.

For variants holding an object, returns the object’s instance ID.

If the variant is not an object, returns None.

If the object is dead, the instance ID is still returned, similar to Gd::instance_id_unchecked(). Unless you have a very good reason to use this, we recommend using object_id() instead.

pub fn call(&self, method: impl AsArg<StringName>, args: &[Variant]) -> Variant

⚠️ Calls the specified method with the given args.

Supports Object as well as built-ins with methods (e.g. Array, Vector3, GString, etc.).

§Panics

If self is not a variant type which supports method calls.
If the method does not exist or the signature is not compatible with the passed arguments.
If the call causes an error.

pub fn evaluate(&self, rhs: &Variant, op: VariantOperator) -> Option<Variant>

Evaluates an expression using a GDScript operator.

Returns the result of the operation, or None if the operation is not defined for the given operand types.

Recommended to be used with fully-qualified call syntax. For example, Variant::evaluate(&a, &b, VariantOperator::Add) is equivalent to a + b in GDScript.

pub fn stringify(&self) -> GString

Return Godot’s string representation of the variant.

pub fn hash_u32(&self) -> u32

Return Godot’s hash value for the variant.

Godot equivalent : @GlobalScope.hash()

pub fn hash(&self) -> i64

👎Deprecated: renamed to hash_u32 and type changed to u32

pub fn booleanize(&self) -> bool

Interpret the Variant as bool.

Returns false only if the variant’s current value is the default value for its type. For example:

nil for the nil type
false for bool
zero for numeric types
empty string
empty container (array, packed array, dictionary)
default-constructed other builtins (e.g. zero vector, degenerate plane, zero RID, etc…)