bevy_asset/
loader.rs

1use crate::{
2    io::{AssetReaderError, MissingAssetSourceError, MissingProcessedAssetReaderError, Reader},
3    loader_builders::NestedLoadBuilder,
4    meta::{AssetHash, AssetMeta, AssetMetaDyn, ProcessedInfo, ProcessedInfoMinimal, Settings},
5    path::AssetPath,
6    Asset, AssetIndex, AssetLoadError, AssetServer, AssetServerMode, Assets, ErasedAssetIndex,
7    Handle, UntypedAssetId, UntypedHandle,
8};
9use alloc::{boxed::Box, string::ToString, vec::Vec};
10use atomicow::CowArc;
11use bevy_ecs::{error::BevyError, world::World};
12use bevy_platform::collections::{hash_map::Entry, HashMap, HashSet};
13use bevy_reflect::TypePath;
14use bevy_tasks::{BoxedFuture, ConditionalSendFuture};
15use core::{
16    any::{Any, TypeId},
17    convert::Infallible,
18};
19use downcast_rs::{impl_downcast, Downcast};
20use ron::error::SpannedError;
21use serde::{Deserialize, Serialize};
22use std::path::{Path, PathBuf};
23use thiserror::Error;
24use tracing::error;
25
26/// Loads an [`Asset`] from a given byte [`Reader`]. This can accept [`AssetLoader::Settings`], which configure how the [`Asset`]
27/// should be loaded.
28///
29/// This trait is generally used in concert with [`AssetReader`](crate::io::AssetReader) to load assets from a byte source.
30///
31/// For a complementary version of this trait that can save assets, see [`AssetSaver`](crate::saver::AssetSaver).
32pub trait AssetLoader: TypePath + Send + Sync + 'static {
33    /// The top level [`Asset`] loaded by this [`AssetLoader`].
34    type Asset: Asset;
35    /// The settings type used by this [`AssetLoader`].
36    type Settings: Settings + Default + Serialize + for<'a> Deserialize<'a>;
37    /// The type of [error](`std::error::Error`) which could be encountered by this loader.
38    type Error: Into<BevyError>;
39    /// Asynchronously loads [`AssetLoader::Asset`] (and any other labeled assets) from the bytes provided by [`Reader`].
40    fn load(
41        &self,
42        reader: &mut dyn Reader,
43        settings: &Self::Settings,
44        load_context: &mut LoadContext,
45    ) -> impl ConditionalSendFuture<Output = Result<Self::Asset, Self::Error>>;
46
47    /// Returns a list of extensions supported by this [`AssetLoader`], without the preceding dot.
48    /// Note that users of this [`AssetLoader`] may choose to load files with a non-matching extension.
49    fn extensions(&self) -> &[&str] {
50        &[]
51    }
52}
53
54/// Provides type-erased access to an [`AssetLoader`].
55pub trait ErasedAssetLoader: Send + Sync + 'static {
56    /// Asynchronously loads the asset(s) from the bytes provided by [`Reader`].
57    fn load<'a>(
58        &'a self,
59        reader: &'a mut dyn Reader,
60        settings: &'a dyn Settings,
61        load_context: LoadContext<'a>,
62    ) -> BoxedFuture<'a, Result<ErasedLoadedAsset, BevyError>>;
63
64    /// Returns a list of extensions supported by this asset loader, without the preceding dot.
65    fn extensions(&self) -> &[&str];
66    /// Deserializes metadata from the input `meta` bytes into the appropriate type (erased as [`Box<dyn AssetMetaDyn>`]).
67    fn deserialize_meta(&self, meta: &[u8]) -> Result<Box<dyn AssetMetaDyn>, DeserializeMetaError>;
68    /// Returns the default meta value for the [`AssetLoader`] (erased as [`Box<dyn AssetMetaDyn>`]).
69    fn default_meta(&self) -> Box<dyn AssetMetaDyn>;
70    /// Returns the type path of the [`AssetLoader`].
71    fn type_path(&self) -> &'static str;
72    /// Returns the [`TypeId`] of the [`AssetLoader`].
73    fn type_id(&self) -> TypeId;
74    /// Returns the type name of the top-level [`Asset`] loaded by the [`AssetLoader`].
75    fn asset_type_name(&self) -> &'static str;
76    /// Returns the [`TypeId`] of the top-level [`Asset`] loaded by the [`AssetLoader`].
77    fn asset_type_id(&self) -> TypeId;
78}
79
80impl<L> ErasedAssetLoader for L
81where
82    L: AssetLoader + Send + Sync,
83{
84    /// Processes the asset in an asynchronous closure.
85    fn load<'a>(
86        &'a self,
87        reader: &'a mut dyn Reader,
88        settings: &'a dyn Settings,
89        mut load_context: LoadContext<'a>,
90    ) -> BoxedFuture<'a, Result<ErasedLoadedAsset, BevyError>> {
91        Box::pin(async move {
92            let settings = settings
93                .downcast_ref::<L::Settings>()
94                .expect("AssetLoader settings should match the loader type");
95            let asset = <L as AssetLoader>::load(self, reader, settings, &mut load_context)
96                .await
97                .map_err(Into::into)?;
98            Ok(load_context.finish(asset).into())
99        })
100    }
101
102    fn extensions(&self) -> &[&str] {
103        <L as AssetLoader>::extensions(self)
104    }
105
106    fn deserialize_meta(&self, meta: &[u8]) -> Result<Box<dyn AssetMetaDyn>, DeserializeMetaError> {
107        let meta = AssetMeta::<L, ()>::deserialize(meta)?;
108        Ok(Box::new(meta))
109    }
110
111    fn default_meta(&self) -> Box<dyn AssetMetaDyn> {
112        Box::new(AssetMeta::<L, ()>::new(crate::meta::AssetAction::Load {
113            loader: self.type_path().to_string(),
114            settings: L::Settings::default(),
115        }))
116    }
117
118    fn type_path(&self) -> &'static str {
119        L::type_path()
120    }
121
122    fn type_id(&self) -> TypeId {
123        TypeId::of::<L>()
124    }
125
126    fn asset_type_name(&self) -> &'static str {
127        core::any::type_name::<L::Asset>()
128    }
129
130    fn asset_type_id(&self) -> TypeId {
131        TypeId::of::<L::Asset>()
132    }
133}
134
135pub(crate) struct LabeledAsset {
136    pub(crate) asset: ErasedLoadedAsset,
137    pub(crate) handle: UntypedHandle,
138}
139
140/// The successful result of an [`AssetLoader::load`] call. This contains the loaded "root" asset and any other "labeled" assets produced
141/// by the loader. It also holds the input [`AssetMeta`] (if it exists) and tracks dependencies:
142/// * normal dependencies: dependencies that must be loaded as part of this asset load (ex: assets a given asset has handles to).
143/// * Loader dependencies: dependencies whose actual asset values are used during the load process
144pub struct LoadedAsset<A: Asset> {
145    pub(crate) value: A,
146    pub(crate) dependencies: HashSet<ErasedAssetIndex>,
147    pub(crate) loader_dependencies: HashMap<AssetPath<'static>, AssetHash>,
148    /// The subassets of this asset.
149    pub(crate) labeled_assets: Vec<LabeledAsset>,
150    /// The mapping from subasset labels to their index in [`Self::labeled_assets`].
151    pub(crate) label_to_asset_index: HashMap<CowArc<'static, str>, usize>,
152    /// The mapping from a subasset asset IDs to their index in [`Self::labeled_assets`].
153    ///
154    /// This is entirely redundant with [`Self::labeled_assets`], but it allows looking up the
155    /// labeled asset by its asset ID.
156    pub(crate) asset_id_to_asset_index: HashMap<UntypedAssetId, usize>,
157}
158
159impl<A: Asset> LoadedAsset<A> {
160    /// Create a new loaded asset. This will use [`VisitAssetDependencies`](crate::VisitAssetDependencies) to populate `dependencies`.
161    pub fn new_with_dependencies(value: A) -> Self {
162        let mut dependencies = <HashSet<_>>::default();
163        value.visit_dependencies(&mut |id| {
164            let Ok(asset_index) = id.try_into() else {
165                return;
166            };
167            dependencies.insert(asset_index);
168        });
169        LoadedAsset {
170            value,
171            dependencies,
172            loader_dependencies: HashMap::default(),
173            labeled_assets: Default::default(),
174            label_to_asset_index: Default::default(),
175            asset_id_to_asset_index: Default::default(),
176        }
177    }
178
179    /// Cast (and take ownership) of the [`Asset`] value of the given type.
180    pub fn take(self) -> A {
181        self.value
182    }
183
184    /// Retrieves a reference to the internal [`Asset`] type.
185    pub fn get(&self) -> &A {
186        &self.value
187    }
188
189    /// Returns the [`ErasedLoadedAsset`] for the given label, if it exists.
190    pub fn get_labeled(&self, label: impl AsRef<str>) -> Option<&ErasedLoadedAsset> {
191        self.label_to_asset_index
192            .get(label.as_ref())
193            .map(|index| self.labeled_assets.get(*index).unwrap())
194            .map(|a| &a.asset)
195    }
196
197    /// Returns the labeled asset given its asset ID if it exists.
198    ///
199    /// This can be used to get the asset from its handle since `&Handle` implements
200    /// [`Into<UntypedAssetId>`].
201    pub fn get_labeled_by_id(&self, id: impl Into<UntypedAssetId>) -> Option<&ErasedLoadedAsset> {
202        let index = self.asset_id_to_asset_index.get(&id.into())?;
203        let labeled = &self.labeled_assets[*index];
204        Some(&labeled.asset)
205    }
206
207    /// Iterate over all labels for "labeled assets" in the loaded asset
208    pub fn iter_labels(&self) -> impl Iterator<Item = &str> {
209        self.label_to_asset_index.keys().map(|s| &**s)
210    }
211}
212
213impl<A: Asset> From<A> for LoadedAsset<A> {
214    fn from(asset: A) -> Self {
215        LoadedAsset::new_with_dependencies(asset)
216    }
217}
218
219/// A "type erased / boxed" counterpart to [`LoadedAsset`]. This is used in places where the loaded type is not statically known.
220pub struct ErasedLoadedAsset {
221    pub(crate) value: Box<dyn AssetContainer>,
222    pub(crate) dependencies: HashSet<ErasedAssetIndex>,
223    pub(crate) loader_dependencies: HashMap<AssetPath<'static>, AssetHash>,
224    /// The subassets of this asset.
225    pub(crate) labeled_assets: Vec<LabeledAsset>,
226    /// The mapping from subasset labels to their index in [`Self::labeled_assets`].
227    pub(crate) label_to_asset_index: HashMap<CowArc<'static, str>, usize>,
228    /// The mapping from subasset asset IDs to their index in [`Self::labeled_assets`].
229    ///
230    /// This is entirely redundant with [`Self::labeled_assets`], but it allows looking up the
231    /// labeled asset by its asset ID.
232    pub(crate) asset_id_to_asset_index: HashMap<UntypedAssetId, usize>,
233}
234
235impl<A: Asset> From<LoadedAsset<A>> for ErasedLoadedAsset {
236    fn from(asset: LoadedAsset<A>) -> Self {
237        ErasedLoadedAsset {
238            value: Box::new(asset.value),
239            dependencies: asset.dependencies,
240            loader_dependencies: asset.loader_dependencies,
241            labeled_assets: asset.labeled_assets,
242            label_to_asset_index: asset.label_to_asset_index,
243            asset_id_to_asset_index: asset.asset_id_to_asset_index,
244        }
245    }
246}
247
248impl ErasedLoadedAsset {
249    /// Cast (and take ownership) of the [`Asset`] value of the given type. This will return [`Some`] if
250    /// the stored type matches `A` and [`None`] if it does not.
251    pub fn take<A: Asset>(self) -> Option<A> {
252        self.value.downcast::<A>().map(|a| *a).ok()
253    }
254
255    /// Retrieves a reference to the internal [`Asset`] type, if it matches the type `A`. Otherwise returns [`None`].
256    pub fn get<A: Asset>(&self) -> Option<&A> {
257        self.value.downcast_ref::<A>()
258    }
259
260    /// Retrieves the [`TypeId`] of the stored [`Asset`] type.
261    pub fn asset_type_id(&self) -> TypeId {
262        (*self.value).type_id()
263    }
264
265    /// Retrieves the `type_name` of the stored [`Asset`] type.
266    pub fn asset_type_name(&self) -> &'static str {
267        self.value.asset_type_name()
268    }
269
270    /// Returns the [`ErasedLoadedAsset`] for the given label, if it exists.
271    pub fn get_labeled(&self, label: impl AsRef<str>) -> Option<&ErasedLoadedAsset> {
272        self.label_to_asset_index
273            .get(label.as_ref())
274            .map(|index| self.labeled_assets.get(*index).unwrap())
275            .map(|a| &a.asset)
276    }
277
278    /// Returns the labeled asset given its asset ID if it exists.
279    ///
280    /// This can be used to get the asset from its handle since `&Handle` implements
281    /// [`Into<UntypedAssetId>`].
282    pub fn get_labeled_by_id(&self, id: impl Into<UntypedAssetId>) -> Option<&ErasedLoadedAsset> {
283        let index = self.asset_id_to_asset_index.get(&id.into())?;
284        let labeled = &self.labeled_assets[*index];
285        Some(&labeled.asset)
286    }
287
288    /// Iterate over all labels for "labeled assets" in the loaded asset
289    pub fn iter_labels(&self) -> impl Iterator<Item = &str> {
290        self.label_to_asset_index.keys().map(|s| &**s)
291    }
292
293    /// Cast this loaded asset as the given type. If the type does not match,
294    /// the original type-erased asset is returned.
295    #[cfg_attr(
296        not(target_arch = "wasm32"),
297        expect(
298            clippy::result_large_err,
299            reason = "Returning the passed in ErasedLoadedAsset"
300        )
301    )]
302    pub fn downcast<A: Asset>(mut self) -> Result<LoadedAsset<A>, ErasedLoadedAsset> {
303        match self.value.downcast::<A>() {
304            Ok(value) => Ok(LoadedAsset {
305                value: *value,
306                dependencies: self.dependencies,
307                loader_dependencies: self.loader_dependencies,
308                labeled_assets: self.labeled_assets,
309                label_to_asset_index: self.label_to_asset_index,
310                asset_id_to_asset_index: self.asset_id_to_asset_index,
311            }),
312            Err(value) => {
313                self.value = value;
314                Err(self)
315            }
316        }
317    }
318}
319
320/// A type erased container for an [`Asset`] value that is capable of inserting the [`Asset`] into a [`World`]'s [`Assets`] collection.
321pub(crate) trait AssetContainer: Downcast + Any + Send + Sync + 'static {
322    fn insert(self: Box<Self>, id: AssetIndex, world: &mut World);
323    fn asset_type_name(&self) -> &'static str;
324}
325
326impl_downcast!(AssetContainer);
327
328impl<A: Asset> AssetContainer for A {
329    fn insert(self: Box<Self>, index: AssetIndex, world: &mut World) {
330        // We only ever call this if we know the asset is still alive, so it is fine to unwrap here.
331        world
332            .resource_mut::<Assets<A>>()
333            .insert(index, *self)
334            .expect("the AssetIndex is still valid");
335    }
336
337    fn asset_type_name(&self) -> &'static str {
338        core::any::type_name::<A>()
339    }
340}
341
342/// An error that occurs when attempting an async load using [`NestedLoadBuilder`].
343#[derive(Error, Debug)]
344pub enum LoadDirectError {
345    /// The asset path was empty.
346    #[error("Attempted to load an asset with an empty path \"{0}\"")]
347    EmptyPath(AssetPath<'static>),
348    /// Loading an asset path with a subasset at the end is unsupported. See issue [#18291].
349    ///
350    /// [#18291]: https://github.com/bevyengine/bevy/issues/18291
351    #[error("Requested to load an asset path ({0:?}) with a subasset, but this is unsupported. See issue #18291")]
352    RequestedSubasset(AssetPath<'static>),
353    /// A general [`AssetLoadError`] for an asset dependency.
354    #[error("Failed to load dependency {dependency:?} {error}")]
355    LoadError {
356        /// Which dependency failed.
357        dependency: AssetPath<'static>,
358        /// The original error for that dependency.
359        error: Box<AssetLoadError>,
360    },
361}
362
363/// An error that occurs while deserializing [`AssetMeta`].
364#[derive(Error, Debug, Clone, PartialEq, Eq)]
365pub enum DeserializeMetaError {
366    /// Failed to deserialize the asset metadata.
367    #[error("Failed to deserialize asset meta: {0:?}")]
368    DeserializeSettings(#[from] SpannedError),
369    /// Failed to deserialize the minimal asset metadata.
370    #[error("Failed to deserialize minimal asset meta: {0:?}")]
371    DeserializeMinimal(SpannedError),
372}
373
374/// A context that provides access to assets in [`AssetLoader`]s, tracks dependencies, and collects asset load state.
375///
376/// Any asset state accessed by [`LoadContext`] will be tracked and stored for use in dependency events and asset preprocessing.
377pub struct LoadContext<'a> {
378    pub(crate) asset_server: &'a AssetServer,
379    /// Specifies whether dependencies that are loaded deferred should be loaded.
380    ///
381    /// This allows us to skip loads for cases where we're never going to use the asset and we just
382    /// need the dependency information, for example during asset processing.
383    pub(crate) should_load_dependencies: bool,
384    populate_hashes: bool,
385    asset_path: AssetPath<'static>,
386    pub(crate) dependencies: HashSet<ErasedAssetIndex>,
387    /// Direct dependencies used by this loader.
388    pub(crate) loader_dependencies: HashMap<AssetPath<'static>, AssetHash>,
389    /// Stores the subassets added to this context.
390    pub(crate) labeled_assets: Vec<LabeledAsset>,
391    /// Maps the label of a subasset to the index into [`Self::labeled_assets`].
392    pub(crate) label_to_asset_index: HashMap<CowArc<'static, str>, usize>,
393    /// Maps the subasset asset ID to the index into [`Self::labeled_assets`].
394    ///
395    /// This is entirely redundant with [`Self::labeled_assets`], but it allows looking up the
396    /// labeled asset by its asset ID.
397    pub(crate) asset_id_to_asset_index: HashMap<UntypedAssetId, usize>,
398}
399
400impl<'a> LoadContext<'a> {
401    /// Creates a new [`LoadContext`] instance.
402    pub(crate) fn new(
403        asset_server: &'a AssetServer,
404        asset_path: AssetPath<'static>,
405        should_load_dependencies: bool,
406        populate_hashes: bool,
407    ) -> Self {
408        Self {
409            asset_server,
410            asset_path,
411            populate_hashes,
412            should_load_dependencies,
413            dependencies: HashSet::default(),
414            loader_dependencies: HashMap::default(),
415            labeled_assets: Default::default(),
416            label_to_asset_index: Default::default(),
417            asset_id_to_asset_index: Default::default(),
418        }
419    }
420
421    /// Begins a new labeled asset load. Use the returned [`LoadContext`] to load
422    /// dependencies for the new asset and call [`LoadContext::finish`] to finalize the asset load.
423    /// When finished, make sure you call [`LoadContext::add_loaded_labeled_asset`] to add the results back to the parent
424    /// context.
425    /// Prefer [`LoadContext::labeled_asset_scope`] when possible, which will automatically add
426    /// the labeled [`LoadContext`] back to the parent context.
427    /// [`LoadContext::begin_labeled_asset`] exists largely to enable parallel asset loading.
428    ///
429    /// See [`AssetPath`] for more on labeled assets.
430    ///
431    /// ```no_run
432    /// # use bevy_asset::{Asset, LoadContext};
433    /// # use bevy_reflect::TypePath;
434    /// # #[derive(Asset, TypePath, Default)]
435    /// # struct Image;
436    /// # let load_context: LoadContext = panic!();
437    /// let mut handles = Vec::new();
438    /// for i in 0..2 {
439    ///     let labeled = load_context.begin_labeled_asset();
440    ///     handles.push(std::thread::spawn(move || {
441    ///         (i.to_string(), labeled.finish(Image::default()))
442    ///     }));
443    /// }
444    ///
445    /// for handle in handles {
446    ///     let (label, loaded_asset) = handle.join().unwrap();
447    ///     load_context.add_loaded_labeled_asset(label, loaded_asset);
448    /// }
449    /// ```
450    pub fn begin_labeled_asset(&self) -> LoadContext<'_> {
451        LoadContext::new(
452            self.asset_server,
453            self.asset_path.clone(),
454            self.should_load_dependencies,
455            self.populate_hashes,
456        )
457    }
458
459    /// Creates a new [`LoadContext`] for the given `label`. The `load` function is responsible for loading an [`Asset`] of
460    /// type `A`. `load` will be called immediately and the result will be used to finalize the [`LoadContext`], resulting in a new
461    /// [`LoadedAsset`], which is registered under the `label` label.
462    ///
463    /// This exists to remove the need to manually call [`LoadContext::begin_labeled_asset`] and then manually register the
464    /// result with [`LoadContext::add_loaded_labeled_asset`].
465    ///
466    /// See [`AssetPath`] for more on labeled assets.
467    pub fn labeled_asset_scope<A: Asset, E>(
468        &mut self,
469        label: impl Into<CowArc<'static, str>>,
470        load: impl FnOnce(&mut LoadContext) -> Result<A, E>,
471    ) -> Result<Handle<A>, E> {
472        let mut context = self.begin_labeled_asset();
473        let asset = load(&mut context)?;
474        let loaded_asset = context.finish(asset);
475        Ok(self.add_loaded_labeled_asset(label, loaded_asset))
476    }
477
478    /// This will add the given `asset` as a "labeled [`Asset`]" with the `label` label.
479    ///
480    /// # Warning
481    ///
482    /// This will not assign dependencies to the given `asset`. If adding an asset
483    /// with dependencies generated from calls such as [`LoadContext::load`], use
484    /// [`LoadContext::labeled_asset_scope`] or [`LoadContext::begin_labeled_asset`] to generate a
485    /// new [`LoadContext`] to track the dependencies for the labeled asset.
486    ///
487    /// See [`AssetPath`] for more on labeled assets.
488    pub fn add_labeled_asset<A: Asset>(
489        &mut self,
490        label: impl Into<CowArc<'static, str>>,
491        asset: A,
492    ) -> Handle<A> {
493        let Ok(handle) = self.labeled_asset_scope(label, |_| Ok::<_, Infallible>(asset));
494        handle
495    }
496
497    /// Add a [`LoadedAsset`] that is a "labeled sub asset" of the root path of this load context.
498    /// This can be used in combination with [`LoadContext::begin_labeled_asset`] to parallelize
499    /// sub asset loading.
500    ///
501    /// See [`AssetPath`] for more on labeled assets.
502    pub fn add_loaded_labeled_asset<A: Asset>(
503        &mut self,
504        label: impl Into<CowArc<'static, str>>,
505        loaded_asset: LoadedAsset<A>,
506    ) -> Handle<A> {
507        let label = label.into();
508        let loaded_asset: ErasedLoadedAsset = loaded_asset.into();
509        let labeled_path = self.asset_path.clone().with_label(label.clone());
510        let handle = self
511            .asset_server
512            .get_or_create_path_handle(labeled_path, None);
513        let asset = LabeledAsset {
514            asset: loaded_asset,
515            handle: handle.clone().untyped(),
516        };
517        match self.label_to_asset_index.entry(label) {
518            Entry::Occupied(entry) => {
519                // TODO: We should probably treat this as an error. It seems unlikely someone wants
520                // to replace a subasset - this is probably accidental.
521                let index = *entry.get();
522                // Note: we don't need to mess with the `asset_id_to_asset_index` here, since we
523                // know the same path to `get_or_create_path_handle` will return the same handle as
524                // long as the handle remains alive, and we hold the handle in `LabeledAsset`.
525                self.labeled_assets[index] = asset;
526            }
527            Entry::Vacant(entry) => {
528                entry.insert(self.labeled_assets.len());
529                self.asset_id_to_asset_index
530                    .insert(handle.id().untyped(), self.labeled_assets.len());
531                self.labeled_assets.push(asset);
532            }
533        }
534        handle
535    }
536
537    /// Returns `true` if an asset with the label `label` exists in this context.
538    ///
539    /// See [`AssetPath`] for more on labeled assets.
540    pub fn has_labeled_asset<'b>(&self, label: impl Into<CowArc<'b, str>>) -> bool {
541        let path = self.asset_path.clone().with_label(label.into());
542        !self.asset_server.get_handles_untyped(&path).is_empty()
543    }
544
545    /// "Finishes" this context by populating the final [`Asset`] value.
546    pub fn finish<A: Asset>(mut self, value: A) -> LoadedAsset<A> {
547        // At this point, we assume the asset/subasset is "locked in" and won't be changed, so we
548        // can ensure all the dependencies are included (in case a handle was used without loading
549        // it through this `LoadContext`). If in the future we provide an API for mutating assets in
550        // `LoadedAsset`, `ErasedLoadedAsset`, or `LoadContext` (for mutating existing subassets),
551        // we should move this to some point after those mutations are not possible. This spot is
552        // convenient because we still have access to the static type of `A`.
553        value.visit_dependencies(&mut |asset_id| {
554            let (type_id, index) = match asset_id {
555                UntypedAssetId::Index { type_id, index } => (type_id, index),
556                // UUID assets can't be loaded anyway, so just ignore this ID.
557                UntypedAssetId::Uuid { .. } => return,
558            };
559            self.dependencies
560                .insert(ErasedAssetIndex { index, type_id });
561        });
562        LoadedAsset {
563            value,
564            dependencies: self.dependencies,
565            loader_dependencies: self.loader_dependencies,
566            labeled_assets: self.labeled_assets,
567            label_to_asset_index: self.label_to_asset_index,
568            asset_id_to_asset_index: self.asset_id_to_asset_index,
569        }
570    }
571
572    /// Gets the source asset path for this load context.
573    pub fn path(&self) -> &AssetPath<'static> {
574        &self.asset_path
575    }
576
577    /// Reads the asset at the given path and returns its bytes
578    pub async fn read_asset_bytes<'b, 'c>(
579        &'b mut self,
580        path: impl Into<AssetPath<'c>>,
581    ) -> Result<Vec<u8>, ReadAssetBytesError> {
582        let path = path.into();
583        if path.path() == Path::new("") {
584            error!("Attempted to load an asset with an empty path \"{path}\"!");
585            return Err(ReadAssetBytesError::EmptyPath(path.into_owned()));
586        }
587
588        let source = self.asset_server.get_source(path.source())?;
589        let asset_reader = match self.asset_server.mode() {
590            AssetServerMode::Unprocessed => source.reader(),
591            AssetServerMode::Processed => source.processed_reader()?,
592        };
593        let mut reader = asset_reader.read(path.path()).await?;
594        let hash = if self.populate_hashes {
595            // NOTE: ensure meta is read while the asset bytes reader is still active to ensure transactionality
596            // See `ProcessorGatedReader` for more info
597            let meta_bytes = asset_reader.read_meta_bytes(path.path()).await?;
598            let minimal: ProcessedInfoMinimal = ron::de::from_bytes(&meta_bytes)
599                .map_err(DeserializeMetaError::DeserializeMinimal)?;
600            let processed_info = minimal
601                .processed_info
602                .ok_or(ReadAssetBytesError::MissingAssetHash)?;
603            processed_info.full_hash
604        } else {
605            Default::default()
606        };
607        let mut bytes = Vec::new();
608        reader
609            .read_to_end(&mut bytes)
610            .await
611            .map_err(|source| ReadAssetBytesError::Io {
612                path: path.path().to_path_buf(),
613                source,
614            })?;
615        self.loader_dependencies.insert(path.clone_owned(), hash);
616        Ok(bytes)
617    }
618
619    /// Returns a handle to an asset of type `A` with the label `label`. This [`LoadContext`] must produce an asset of the
620    /// given type and the given label or the dependencies of this asset will never be considered "fully loaded". However you
621    /// can call this method before _or_ after adding the labeled asset.
622    pub fn get_label_handle<'b, A: Asset>(
623        &mut self,
624        label: impl Into<CowArc<'b, str>>,
625    ) -> Handle<A> {
626        let path = self.asset_path.clone().with_label(label);
627        let handle = self.asset_server.get_or_create_path_handle(path, None);
628        // `get_or_create_path_handle` always returns a Strong variant, so we are safe to unwrap.
629        let index = (&handle).try_into().unwrap();
630        self.dependencies.insert(index);
631        handle
632    }
633
634    /// Returns the labeled asset if it exists.
635    pub fn get_labeled(&self, label: impl AsRef<str>) -> Option<&ErasedLoadedAsset> {
636        let index = self.label_to_asset_index.get(label.as_ref())?;
637        let labeled = &self.labeled_assets[*index];
638        Some(&labeled.asset)
639    }
640
641    /// Returns the labeled asset given its asset ID if it exists.
642    ///
643    /// This can be used to get the asset from its handle since `&Handle` implements
644    /// [`Into<UntypedAssetId>`].
645    pub fn get_labeled_by_id(&self, id: impl Into<UntypedAssetId>) -> Option<&ErasedLoadedAsset> {
646        let index = self.asset_id_to_asset_index.get(&id.into())?;
647        let labeled = &self.labeled_assets[*index];
648        Some(&labeled.asset)
649    }
650
651    pub(crate) async fn load_direct_internal(
652        &mut self,
653        path: AssetPath<'static>,
654        settings: &dyn Settings,
655        loader: &dyn ErasedAssetLoader,
656        reader: &mut dyn Reader,
657        processed_info: Option<&ProcessedInfo>,
658    ) -> Result<ErasedLoadedAsset, LoadDirectError> {
659        let loaded_asset = self
660            .asset_server
661            .load_with_settings_loader_and_reader(
662                &path,
663                settings,
664                loader,
665                reader,
666                self.should_load_dependencies,
667                self.populate_hashes,
668            )
669            .await
670            .map_err(|error| LoadDirectError::LoadError {
671                dependency: path.clone(),
672                error: Box::new(error),
673            })?;
674        let hash = processed_info.map(|i| i.full_hash).unwrap_or_default();
675        self.loader_dependencies.insert(path, hash);
676        Ok(loaded_asset)
677    }
678
679    /// Create a builder for loading nested assets in this context.
680    #[must_use]
681    pub fn load_builder(&mut self) -> NestedLoadBuilder<'a, '_> {
682        NestedLoadBuilder::new(self)
683    }
684
685    /// Retrieves a handle for the asset at the given path and adds that path as a dependency of the asset.
686    /// If the current context is a normal [`AssetServer::load`], an actual asset load will be kicked off immediately, which ensures the load happens
687    /// as soon as possible.
688    /// "Normal loads" kicked from within a normal Bevy App will generally configure the context to kick off loads immediately.
689    /// If the current context is configured to not load dependencies automatically (ex: [`AssetProcessor`](crate::processor::AssetProcessor)),
690    /// a load will not be kicked off automatically. It is then the calling context's responsibility to begin a load if necessary.
691    ///
692    /// If you need to override asset settings, asset type, or load directly, please see [`LoadContext::load_builder`].
693    pub fn load<'b, A: Asset>(&mut self, path: impl Into<AssetPath<'b>>) -> Handle<A> {
694        self.load_builder().load(path)
695    }
696}
697
698/// An error produced when calling [`LoadContext::read_asset_bytes`]
699#[derive(Error, Debug)]
700pub enum ReadAssetBytesError {
701    #[error("Attempted to load an asset with an empty path \"{0}\"")]
702    EmptyPath(AssetPath<'static>),
703    #[error(transparent)]
704    DeserializeMetaError(#[from] DeserializeMetaError),
705    #[error(transparent)]
706    AssetReaderError(#[from] AssetReaderError),
707    #[error(transparent)]
708    MissingAssetSourceError(#[from] MissingAssetSourceError),
709    #[error(transparent)]
710    MissingProcessedAssetReaderError(#[from] MissingProcessedAssetReaderError),
711    /// Encountered an I/O error while loading an asset.
712    #[error("Encountered an io error while loading asset at `{}`: {source}", path.display())]
713    Io {
714        path: PathBuf,
715        source: std::io::Error,
716    },
717    #[error("The LoadContext for this read_asset_bytes call requires hash metadata, but it was not provided. This is likely an internal implementation error.")]
718    MissingAssetHash,
719}
bevy_asset/loader.rs

bevy_asset/
loader.rs
