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.

Equivalent to T::try_from_variant(&self).

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()][Self::object_id_unchecked]. This method is only available from Godot 4.4 onwards.

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(&self) -> i64

Return Godot’s hash value for the variant.

Godot equivalent : @GlobalScope.hash()

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…)