Trait ArrayElement

pub trait ArrayElement:
    GodotType
    + ToGodot
    + FromGodot
    + Sealed {
    // Provided method
    fn debug_validate_elements(_array: &Array<Self>) -> Result<(), ConvertError> { ... }
}

Expand description

Marker trait to identify types that can be stored in Array<T>.

The types, for which this trait is implemented, overlap mostly with GodotType.

Notable differences are:

Only VariantArray, not Array<T> is allowed (typed arrays cannot be nested).
Option is only supported for Option<Gd<T>>, but not e.g. Option<i32>.

§Integer and float types

u8, i8, u16, i16, u32, i32 and f32 are supported by this trait, however they don’t have their own array type in Godot. The engine only knows about i64 (“int”) and f64 (“float”) types. This means that when using any integer or float type, Godot will treat it as the equivalent of GDScript’s Array[int] or Array[float], respectively.

As a result, when converting from a Godot typed array to a Rust Array<T>, the values stored may not actually fit into a T. For example, you have a GDScript Array[int] which stores value 160, and you convert it to a Rust Array<i8>. This means that you may end up with panics on element access (since the Variant storing 160 will fail to convert to i8). In Debug mode, we add additional best-effort checks to detect such errors, however they are expensive and not bullet-proof. If you need very rigid type safety, stick to i64 and f64. The other types however can be extremely convenient and work well, as long as you are aware of the limitations.

u64 is entirely unsupported since it cannot be safely stored inside a Variant.

Also, keep in mind that Godot uses Variant for each element. If performance matters and you have small element types such as u8, consider using packed arrays (e.g. PackedByteArray) instead.