Struct bevy::asset::Handle

pub struct Handle<T>where
    T: Asset,{ /* private fields */ }

A handle into a specific Asset of type T.

Handles contain a unique id that corresponds to a specific asset in the Assets collection.

Accessing the Asset

A handle is not the asset itself, but should be seen as a pointer to the asset. Modifying a handle’s id only modifies which asset is being pointed to. To get the actual asset, try using Assets::get or Assets::get_mut.

Strong and Weak

A handle can be either “Strong” or “Weak”. Simply put: Strong handles keep the asset loaded, while Weak handles do not affect the loaded status of assets. This is due to a type of reference counting. When the number of Strong handles that exist for any given asset reach zero, the asset is dropped and becomes unloaded. In some cases, you might want a reference to an asset but don’t want to take the responsibility of keeping it loaded that comes with a Strong handle. This is where a Weak handle can be very useful.

For example, imagine you have a Sprite component and a Collider component. The Collider uses the Sprite’s image size to check for collisions. It does so by keeping a Weak copy of the Sprite’s Strong handle to the image asset.

If the Sprite is removed, its Strong handle to the image is dropped with it. And since it was the only Strong handle for that asset, the asset is unloaded. Our Collider component still has a Weak handle to the unloaded asset, but it will not be able to retrieve the image data, resulting in collisions no longer being detected for that entity.

Implementations

impl<T> Handle<T>where
    T: Asset,

pub fn weak(id: HandleId) -> Handle<T>

Creates a weak handle into an Asset identified by id.

pub fn id(&self) -> HandleId

The ID of the asset as contained within its respective Assets collection.

pub fn cast_weak<U>(&self) -> Handle<U>where
    U: Asset,

Recasts this handle as a weak handle of an Asset U.

pub fn is_weak(&self) -> bool

Returns true if this is a weak handle.

pub fn is_strong(&self) -> bool

Returns true if this is a strong handle.

pub fn make_strong(&mut self, assets: &Assets<T>)

Makes this handle Strong if it wasn’t already.

This method requires the corresponding Assets collection.

pub fn clone_weak(&self) -> Handle<T>

Creates a weak copy of this handle.

pub fn clone_untyped(&self) -> HandleUntyped

Creates an untyped copy of this handle.

pub fn clone_weak_untyped(&self) -> HandleUntyped

Creates a weak, untyped copy of this handle.

Trait Implementations

impl<T> Clone for Handle<T>where
    T: Asset,

fn clone(&self) -> Handle<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Component for Handle<T>where
    T: Asset,
    Handle<T>: 'static + Send + Sync,

type Storage = TableStorage

impl<T> Debug for Handle<T>where
    T: Asset,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T> Default for Handle<T>where
    T: Asset,

fn default() -> Handle<T>

Returns the “default value” for a type.

impl<T> Drop for Handle<T>where
    T: Asset,

fn drop(&mut self)

Executes the destructor for this type.

impl<T> ExtractComponent for Handle<T>where
    T: Asset,

type Query = &'static Handle<T>

ECS WorldQuery to fetch the components to extract.

type Filter = ()

Filters the entities with additional constraints.

fn extract_component(
    handle: <<Handle<T> as ExtractComponent>::Query as WorldQuery>::Item<'_>
) -> Handle<T>

Defines how the component is transferred into the “render world”.

impl<T> From<&Handle<T>> for HandleIdwhere
    T: Asset,

fn from(value: &Handle<T>) -> HandleId

Converts to this type from the input type.

impl<A> From<Handle<A>> for HandleUntypedwhere
    A: Asset,

fn from(handle: Handle<A>) -> HandleUntyped

Converts to this type from the input type.

impl From<Handle<Image>> for ColorMaterial

fn from(texture: Handle<Image>) -> ColorMaterial

Converts to this type from the input type.

impl From<Handle<Image>> for StandardMaterial

fn from(texture: Handle<Image>) -> StandardMaterial

Converts to this type from the input type.

impl From<Handle<Image>> for UiImage

fn from(handle: Handle<Image>) -> UiImage

Converts to this type from the input type.

impl From<Handle<Mesh>> for Mesh2dHandle

fn from(handle: Handle<Mesh>) -> Mesh2dHandle

Converts to this type from the input type.

impl From<Handle<Shader>> for ShaderRef

fn from(handle: Handle<Shader>) -> ShaderRef

Converts to this type from the input type.

impl<T> From<Handle<T>> for HandleIdwhere
    T: Asset,

fn from(value: Handle<T>) -> HandleId

Converts to this type from the input type.

impl<T> FromReflect for Handle<T>where
    T: Asset,
    HandleId: FromReflect,

fn from_reflect(reflect: &(dyn Reflect + 'static)) -> Option<Handle<T>>

Constructs a concrete instance of Self from a reflected value.

impl<A> FromType<Handle<A>> for ReflectHandlewhere
    A: Asset,

fn from_type() -> ReflectHandle

impl<T> GetTypeRegistration for Handle<T>where
    T: Asset,

fn get_type_registration() -> TypeRegistration

impl<T> Hash for Handle<T>where
    T: Asset,

fn hash<H>(&self, state: &mut H)where
    H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where
    H: Hasher,
    Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T> Ord for Handle<T>where
    T: Asset,

fn cmp(&self, other: &Handle<T>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Selfwhere
    Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Selfwhere
    Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere
    Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl<T> PartialEq<Handle<T>> for Handle<T>where
    T: Asset,

fn eq(&self, other: &Handle<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialOrd<Handle<T>> for Handle<T>where
    T: Asset,

fn partial_cmp(&self, other: &Handle<T>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T> Reflect for Handle<T>where
    T: Asset,

fn type_name(&self) -> &str

Returns the type name of the underlying type.

fn get_type_info(&self) -> &'static TypeInfo

Returns the TypeInfo of the underlying type.

fn into_any(self: Box<Handle<T>, Global>) -> Box<dyn Any + 'static, Global>

Returns the value as a Box<dyn Any>.

fn as_any(&self) -> &(dyn Any + 'static)

Returns the value as a &dyn Any.

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Returns the value as a &mut dyn Any.

fn into_reflect(
    self: Box<Handle<T>, Global>
) -> Box<dyn Reflect + 'static, Global>

Casts this type to a boxed reflected value.

fn as_reflect(&self) -> &(dyn Reflect + 'static)

Casts this type to a reflected value.

fn as_reflect_mut(&mut self) -> &mut (dyn Reflect + 'static)

Casts this type to a mutable reflected value.

fn clone_value(&self) -> Box<dyn Reflect + 'static, Global>

Clones the value as a Reflect trait object.

fn set(
    &mut self,
    value: Box<dyn Reflect + 'static, Global>
) -> Result<(), Box<dyn Reflect + 'static, Global>>

Performs a type-checked assignment of a reflected value to this value.

fn apply(&mut self, value: &(dyn Reflect + 'static))

Applies a reflected value to this value.

fn reflect_ref(&self) -> ReflectRef<'_>

Returns an enumeration of “kinds” of type.

fn reflect_mut(&mut self) -> ReflectMut<'_>

Returns a mutable enumeration of “kinds” of type.

fn reflect_owned(self: Box<Handle<T>, Global>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type.

fn reflect_partial_eq(&self, value: &(dyn Reflect + 'static)) -> Option<bool>

Returns a “partial equality” comparison result.

fn reflect_hash(&self) -> Option<u64>

Returns a hash of the value (which includes the type).

fn debug(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Debug formatter for the value.

fn serializable(&self) -> Option<Serializable<'_>>

Returns a serializable version of the value.

impl<T> Struct for Handle<T>where
    T: Asset,

fn field(&self, name: &str) -> Option<&(dyn Reflect + 'static)>

Returns a reference to the value of the field named name as a &dyn Reflect.

fn field_mut(&mut self, name: &str) -> Option<&mut (dyn Reflect + 'static)>

Returns a mutable reference to the value of the field named name as a &mut dyn Reflect.

fn field_at(&self, index: usize) -> Option<&(dyn Reflect + 'static)>

Returns a reference to the value of the field with index index as a &dyn Reflect.

fn field_at_mut(&mut self, index: usize) -> Option<&mut (dyn Reflect + 'static)>

Returns a mutable reference to the value of the field with index index as a &mut dyn Reflect.

fn name_at(&self, index: usize) -> Option<&str>

Returns the name of the field with index index.

fn field_len(&self) -> usize

Returns the number of fields in the struct.

fn iter_fields(&self) -> FieldIter<'_>

Returns an iterator over the values of the reflectable fields for this struct.

fn clone_dynamic(&self) -> DynamicStruct

Clones the struct into a DynamicStruct.

impl<T> Typed for Handle<T>where
    T: Asset,

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.

impl<T> Eq for Handle<T>where
    T: Asset,