Struct NestedLoader

pub struct NestedLoader<'ctx, 'builder, T, M> { /* private fields */ }

A builder for loading nested assets inside a LoadContext.

Loader state

The type parameters T and M determine how this will load assets:

• T: the typing of this loader. How do we know what type of asset to load?

  See StaticTyped (the default), DynamicTyped, and UnknownTyped.

• M: the load mode. Do we want to load this asset right now (in which case you will have to await the operation), or do we just want a Handle, and leave the actual asset loading to later?

  See Deferred (the default) and Immediate.

When configuring this builder, you can freely switch between these modes via functions like deferred and immediate.

Typing

To inform the loader of what type of asset to load:

• in StaticTyped: statically providing a type parameter A: Asset to load.

  This is the simplest way to get a Handle<A> to the loaded asset, as long as you know the type of A at compile time.

• in DynamicTyped: providing the TypeId of the asset at runtime.

  If you know the type ID of the asset at runtime, but not at compile time, use with_dynamic_type followed by load to start loading an asset of that type. This lets you get an UntypedHandle (via Deferred), or a ErasedLoadedAsset (via Immediate).

• in UnknownTyped: loading either a type-erased version of the asset (ErasedLoadedAsset), or a handle to a handle of the actual asset (LoadedUntypedAsset).

  If you have no idea what type of asset you will be loading (not even at runtime with a TypeId), use this.

Load mode

To inform the loader how you want to load the asset:

• in Deferred: when you request to load the asset, you get a Handle for it, but the actual loading won’t be completed until later.

  Use this if you only need a Handle or UntypedHandle.

• in Immediate: the load request will load the asset right then and there, waiting until the asset is fully loaded and giving you access to it.

  Note that this requires you to await a future, so you must be in an async context to use direct loading. In an asset loader, you will be in an async context.

  Use this if you need the value of another asset in order to load the current asset. For example, if you are deriving a new asset from the referenced asset, or you are building a collection of assets. This will add the path of the asset as a “load dependency”.

  If the current loader is used in a Process “asset preprocessor”, such as a LoadTransformAndSave preprocessor, changing a “load dependency” will result in re-processing of the asset.

Load kickoff

If the current context is a normal AssetServer::load, an actual asset load will be kicked off immediately, which ensures the load happens as soon as possible. “Normal loads” kicked from within a normal Bevy App will generally configure the context to kick off loads immediately.

If the current context is configured to not load dependencies automatically (ex: AssetProcessor), a load will not be kicked off automatically. It is then the calling context’s responsibility to begin a load if necessary.

Lifetimes

• ctx: the lifetime of the associated AssetServer reference
• builder: the lifetime of the temporary builder structs

Implementations

impl<'ctx, 'builder, T: Typing, M: Mode> NestedLoader<'ctx, 'builder, T, M>

pub fn with_settings<S: Settings>( self, settings: impl Fn(&mut S) + Send + Sync + 'static, ) -> Self

Configure the settings used to load the asset.

If the settings type S does not match the settings expected by A’s asset loader, an error will be printed to the log and the asset load will fail.

pub fn with_static_type(self) -> NestedLoader<'ctx, 'builder, StaticTyped, M>

When loading, you must pass in the asset type as a type parameter statically.

If you don’t know the type statically (at compile time), consider with_dynamic_type or with_unknown_type.

pub fn with_dynamic_type( self, asset_type_id: TypeId, ) -> NestedLoader<'ctx, 'builder, DynamicTyped, M>

When loading, the loader will attempt to load an asset with the given TypeId.

pub fn with_unknown_type(self) -> NestedLoader<'ctx, 'builder, UnknownTyped, M>

When loading, we will infer what type of asset to load from metadata.

pub fn deferred(self) -> NestedLoader<'ctx, 'builder, T, Deferred>

When loading, create only asset handles, rather than returning the actual asset.

pub fn immediate<'c>( self, ) -> NestedLoader<'ctx, 'builder, T, Immediate<'builder, 'c>>

The load call itself will load an asset, rather than scheduling the loading to happen later.

This gives you access to the loaded asset, but requires you to be in an async context, and be able to await the resulting future.

impl NestedLoader<'_, '_, StaticTyped, Deferred>

pub fn load<'c, A: Asset>(self, path: impl Into<AssetPath<'c>>) -> Handle<A>

Retrieves a handle for the asset at the given path and adds that path as a dependency of this asset.

This requires you to know the type of asset statically.

• If you have runtime info for what type of asset you’re loading (e.g. a TypeId), use with_dynamic_type.
• If you do not know at all what type of asset you’re loading, use with_unknown_type.

impl NestedLoader<'_, '_, DynamicTyped, Deferred>

pub fn load<'p>(self, path: impl Into<AssetPath<'p>>) -> UntypedHandle

Retrieves a handle for the asset at the given path and adds that path as a dependency of this asset.

This requires you to pass in the asset type ID into with_dynamic_type.

impl NestedLoader<'_, '_, UnknownTyped, Deferred>

pub fn load<'p>( self, path: impl Into<AssetPath<'p>>, ) -> Handle<LoadedUntypedAsset>

Retrieves a handle for the asset at the given path and adds that path as a dependency of this asset.

This will infer the asset type from metadata.

impl<'builder, 'reader, T> NestedLoader<'_, '_, T, Immediate<'builder, 'reader>>

pub fn with_reader(self, reader: &'builder mut (dyn Reader + 'reader)) -> Self

Specify the reader to use to read the asset data.

impl NestedLoader<'_, '_, StaticTyped, Immediate<'_, '_>>

pub async fn load<'p, A: Asset>( self, path: impl Into<AssetPath<'p>>, ) -> Result<LoadedAsset<A>, LoadDirectError>

Attempts to load the asset at the given path immediately.

This requires you to know the type of asset statically.

• If you have runtime info for what type of asset you’re loading (e.g. a TypeId), use with_dynamic_type.
• If you do not know at all what type of asset you’re loading, use with_unknown_type.

impl NestedLoader<'_, '_, DynamicTyped, Immediate<'_, '_>>

pub async fn load<'p>( self, path: impl Into<AssetPath<'p>>, ) -> Result<ErasedLoadedAsset, LoadDirectError>

Attempts to load the asset at the given path immediately.

This requires you to pass in the asset type ID into with_dynamic_type.

impl NestedLoader<'_, '_, UnknownTyped, Immediate<'_, '_>>

pub async fn load<'p>( self, path: impl Into<AssetPath<'p>>, ) -> Result<ErasedLoadedAsset, LoadDirectError>

Attempts to load the asset at the given path immediately.

This will infer the asset type from metadata.