Struct bevy::asset::Handle

pub struct Handle<T> where
    T: Asset,  {
    pub id: HandleId,
    // some fields omitted
}

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.

Fields

id: HandleId

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

Implementations

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

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

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

Get a copy of this handle as a Weak handle

pub fn is_weak(&self) -> bool

pub fn is_strong(&self) -> bool

pub fn make_strong(&mut self, assets: &mut 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>

pub fn clone_untyped(&self) -> HandleUntyped

pub fn clone_weak_untyped(&self) -> HandleUntyped

Trait Implementations

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

pub 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,
    Handle<T>: Send,
    Handle<T>: Sync, 

type Storage = TableStorage

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

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

Formats the value using the given formatter.

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

pub fn default() -> Handle<T>

Returns the “default value” for a type.

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

pub 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.

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

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

impl<'_, T> From<&'_ Handle<T>> for HandleId where
    T: Asset, 

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

Performs the conversion.

impl From<Handle<Image>> for StandardMaterial

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

Performs the conversion.

impl From<Handle<Image>> for ColorMaterial

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

Performs the conversion.

impl From<Handle<Image>> for UiImage

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

Performs the conversion.

impl From<Handle<Mesh>> for Mesh2dHandle

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

Performs the conversion.

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

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

Performs the conversion.

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

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

Creates a clone of a reflected value, converting it to a concrete type if it was a dynamic types (e.g. DynamicStruct)

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

pub fn get_type_registration() -> TypeRegistration

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

pub 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, 

Feeds a slice of this type into the given Hasher.

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

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

This method returns an Ordering between self and other.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

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

pub 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 !=.

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

pub 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, 

pub fn type_name(&self) -> &str

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

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

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

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

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

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

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

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

Returns a serializable value, if serialization is supported. Otherwise None will be returned.

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

Returns a hash of the value (which includes the type) if hashing is supported. Otherwise None will be returned.

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

Returns a “partial equal” comparison result if comparison is supported. Otherwise None will be returned.

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

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

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

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

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

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

pub fn field_len(&self) -> usize

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

pub fn clone_dynamic(&self) -> DynamicStruct

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