Struct bevy_asset::AssetServer
source · pub struct AssetServer { /* private fields */ }
Expand description
Loads and tracks the state of Asset
values from a configured AssetReader
. This can be used to kick off new asset loads and
retrieve their current load states.
The general process to load an asset is:
- Initialize a new
Asset
type with theAssetServer
viaAssetApp::init_asset
, which will internally callAssetServer::register_asset
and set up related ECSAssets
storage and systems. - Register one or more
AssetLoader
s for that asset withAssetApp::init_asset_loader
- Add the asset to your asset folder (defaults to
assets
). - Call
AssetServer::load
with a path to your asset.
AssetServer
can be cloned. It is backed by an Arc
so clones will share state. Clones can be freely used in parallel.
Implementations§
source§impl AssetServer
impl AssetServer
sourcepub fn new(
sources: AssetSources,
mode: AssetServerMode,
watching_for_changes: bool
) -> Self
pub fn new( sources: AssetSources, mode: AssetServerMode, watching_for_changes: bool ) -> Self
Create a new instance of AssetServer
. If watch_for_changes
is true, the AssetReader
storage will watch for changes to
asset sources and hot-reload them.
sourcepub fn new_with_meta_check(
sources: AssetSources,
mode: AssetServerMode,
meta_check: AssetMetaCheck,
watching_for_changes: bool
) -> Self
pub fn new_with_meta_check( sources: AssetSources, mode: AssetServerMode, meta_check: AssetMetaCheck, watching_for_changes: bool ) -> Self
Create a new instance of AssetServer
. If watch_for_changes
is true, the AssetReader
storage will watch for changes to
asset sources and hot-reload them.
sourcepub fn get_source<'a>(
&'a self,
source: impl Into<AssetSourceId<'a>>
) -> Result<&'a AssetSource, MissingAssetSourceError>
pub fn get_source<'a>( &'a self, source: impl Into<AssetSourceId<'a>> ) -> Result<&'a AssetSource, MissingAssetSourceError>
Retrieves the AssetSource
for the given source
.
sourcepub fn watching_for_changes(&self) -> bool
pub fn watching_for_changes(&self) -> bool
Returns true if the AssetServer
watches for changes.
sourcepub fn register_loader<L: AssetLoader>(&self, loader: L)
pub fn register_loader<L: AssetLoader>(&self, loader: L)
Registers a new AssetLoader
. AssetLoader
s must be registered before they can be used.
sourcepub fn register_asset<A: Asset>(&self, assets: &Assets<A>)
pub fn register_asset<A: Asset>(&self, assets: &Assets<A>)
sourcepub async fn get_asset_loader_with_extension(
&self,
extension: &str
) -> Result<Arc<dyn ErasedAssetLoader>, MissingAssetLoaderForExtensionError>
pub async fn get_asset_loader_with_extension( &self, extension: &str ) -> Result<Arc<dyn ErasedAssetLoader>, MissingAssetLoaderForExtensionError>
Returns the registered AssetLoader
associated with the given extension, if it exists.
sourcepub async fn get_asset_loader_with_type_name(
&self,
type_name: &str
) -> Result<Arc<dyn ErasedAssetLoader>, MissingAssetLoaderForTypeNameError>
pub async fn get_asset_loader_with_type_name( &self, type_name: &str ) -> Result<Arc<dyn ErasedAssetLoader>, MissingAssetLoaderForTypeNameError>
Returns the registered AssetLoader
associated with the given std::any::type_name
, if it exists.
sourcepub async fn get_path_asset_loader<'a>(
&self,
path: impl Into<AssetPath<'a>>
) -> Result<Arc<dyn ErasedAssetLoader>, MissingAssetLoaderForExtensionError>
pub async fn get_path_asset_loader<'a>( &self, path: impl Into<AssetPath<'a>> ) -> Result<Arc<dyn ErasedAssetLoader>, MissingAssetLoaderForExtensionError>
Retrieves the default AssetLoader
for the given path, if one can be found.
sourcepub async fn get_asset_loader_with_asset_type_id<'a>(
&self,
type_id: TypeId
) -> Result<Arc<dyn ErasedAssetLoader>, MissingAssetLoaderForTypeIdError>
pub async fn get_asset_loader_with_asset_type_id<'a>( &self, type_id: TypeId ) -> Result<Arc<dyn ErasedAssetLoader>, MissingAssetLoaderForTypeIdError>
Retrieves the default AssetLoader
for the given Asset
TypeId
, if one can be found.
sourcepub async fn get_asset_loader_with_asset_type<'a, A: Asset>(
&self
) -> Result<Arc<dyn ErasedAssetLoader>, MissingAssetLoaderForTypeIdError>
pub async fn get_asset_loader_with_asset_type<'a, A: Asset>( &self ) -> Result<Arc<dyn ErasedAssetLoader>, MissingAssetLoaderForTypeIdError>
Retrieves the default AssetLoader
for the given Asset
type, if one can be found.
sourcepub fn load<'a, A: Asset>(&self, path: impl Into<AssetPath<'a>>) -> Handle<A>
pub fn load<'a, A: Asset>(&self, path: impl Into<AssetPath<'a>>) -> Handle<A>
Begins loading an Asset
of type A
stored at path
. This will not block on the asset load. Instead,
it returns a “strong” Handle
. When the Asset
is loaded (and enters LoadState::Loaded
), it will be added to the
associated Assets
resource.
In case the file path contains a hashtag (#
), the path
must be specified using Path
or AssetPath
because otherwise the hashtag would be interpreted as separator between
the file path and the label. For example:
// `#path` is a label.
asset_server.load("some/file#path");
// `#path` is part of the file name.
asset_server.load(Path::new("some/file#path"));
Furthermore, if you need to load a file with a hashtag in its name and a label, you can
manually construct an AssetPath
.
asset_server.load(AssetPath::from_path(Path::new("some/file#path")).with_label("subasset"));
You can check the asset’s load state by reading AssetEvent
events, calling AssetServer::load_state
, or checking
the Assets
storage to see if the Asset
exists yet.
The asset load will fail and an error will be printed to the logs if the asset stored at path
is not of type A
.
sourcepub fn load_acquire<'a, A: Asset, G: Send + Sync + 'static>(
&self,
path: impl Into<AssetPath<'a>>,
guard: G
) -> Handle<A>
pub fn load_acquire<'a, A: Asset, G: Send + Sync + 'static>( &self, path: impl Into<AssetPath<'a>>, guard: G ) -> Handle<A>
Begins loading an Asset
of type A
stored at path
while holding a guard item.
The guard item is dropped when either the asset is loaded or loading has failed.
This function returns a “strong” Handle
. When the Asset
is loaded (and enters LoadState::Loaded
), it will be added to the
associated Assets
resource.
The guard item should notify the caller in its Drop
implementation. See example multi_asset_sync
.
Synchronously this can be a Arc<AtomicU32>
that decrements its counter, asynchronously this can be a Barrier
.
This function only guarantees the asset referenced by the Handle
is loaded. If your asset is separated into
multiple files, sub-assets referenced by the main asset might still be loading, depend on the implementation of the AssetLoader
.
Additionally, you can check the asset’s load state by reading AssetEvent
events, calling AssetServer::load_state
, or checking
the Assets
storage to see if the Asset
exists yet.
The asset load will fail and an error will be printed to the logs if the asset stored at path
is not of type A
.
sourcepub fn load_with_settings<'a, A: Asset, S: Settings>(
&self,
path: impl Into<AssetPath<'a>>,
settings: impl Fn(&mut S) + Send + Sync + 'static
) -> Handle<A>
pub fn load_with_settings<'a, A: Asset, S: Settings>( &self, path: impl Into<AssetPath<'a>>, settings: impl Fn(&mut S) + Send + Sync + 'static ) -> Handle<A>
Begins loading an Asset
of type A
stored at path
. The given settings
function will override the asset’s
AssetLoader
settings. The type S
must match the configured AssetLoader::Settings
or settings
changes
will be ignored and an error will be printed to the log.
sourcepub fn load_acquire_with_settings<'a, A: Asset, S: Settings, G: Send + Sync + 'static>(
&self,
path: impl Into<AssetPath<'a>>,
settings: impl Fn(&mut S) + Send + Sync + 'static,
guard: G
) -> Handle<A>
pub fn load_acquire_with_settings<'a, A: Asset, S: Settings, G: Send + Sync + 'static>( &self, path: impl Into<AssetPath<'a>>, settings: impl Fn(&mut S) + Send + Sync + 'static, guard: G ) -> Handle<A>
Begins loading an Asset
of type A
stored at path
while holding a guard item.
The guard item is dropped when either the asset is loaded or loading has failed.
This function only guarantees the asset referenced by the Handle
is loaded. If your asset is separated into
multiple files, sub-assets referenced by the main asset might still be loading, depend on the implementation of the AssetLoader
.
The given settings
function will override the asset’s
AssetLoader
settings. The type S
must match the configured AssetLoader::Settings
or settings
changes
will be ignored and an error will be printed to the log.
sourcepub async fn load_untyped_async<'a>(
&self,
path: impl Into<AssetPath<'a>>
) -> Result<UntypedHandle, AssetLoadError>
pub async fn load_untyped_async<'a>( &self, path: impl Into<AssetPath<'a>> ) -> Result<UntypedHandle, AssetLoadError>
Asynchronously load an asset that you do not know the type of statically. If you do know the type of the asset,
you should use AssetServer::load
. If you don’t know the type of the asset, but you can’t use an async method,
consider using AssetServer::load_untyped
.
sourcepub fn load_untyped<'a>(
&self,
path: impl Into<AssetPath<'a>>
) -> Handle<LoadedUntypedAsset>
pub fn load_untyped<'a>( &self, path: impl Into<AssetPath<'a>> ) -> Handle<LoadedUntypedAsset>
Load an asset without knowing its type. The method returns a handle to a LoadedUntypedAsset
.
Once the LoadedUntypedAsset
is loaded, an untyped handle for the requested path can be
retrieved from it.
use bevy_asset::{Assets, Handle, LoadedUntypedAsset};
use bevy_ecs::system::{Res, Resource};
#[derive(Resource)]
struct LoadingUntypedHandle(Handle<LoadedUntypedAsset>);
fn resolve_loaded_untyped_handle(loading_handle: Res<LoadingUntypedHandle>, loaded_untyped_assets: Res<Assets<LoadedUntypedAsset>>) {
if let Some(loaded_untyped_asset) = loaded_untyped_assets.get(&loading_handle.0) {
let handle = loaded_untyped_asset.handle.clone();
// continue working with `handle` which points to the asset at the originally requested path
}
}
This indirection enables a non blocking load of an untyped asset, since I/O is required to figure out the asset type before a handle can be created.
sourcepub fn reload<'a>(&self, path: impl Into<AssetPath<'a>>)
pub fn reload<'a>(&self, path: impl Into<AssetPath<'a>>)
Kicks off a reload of the asset stored at the given path. This will only reload the asset if it currently loaded.
sourcepub fn add<A: Asset>(&self, asset: A) -> Handle<A>
pub fn add<A: Asset>(&self, asset: A) -> Handle<A>
Queues a new asset to be tracked by the AssetServer
and returns a Handle
to it. This can be used to track
dependencies of assets created at runtime.
After the asset has been fully loaded by the AssetServer
, it will show up in the relevant Assets
storage.
sourcepub fn add_async<A: Asset, E: Error + Send + Sync + 'static>(
&self,
future: impl Future<Output = Result<A, E>> + Send + 'static
) -> Handle<A>
pub fn add_async<A: Asset, E: Error + Send + Sync + 'static>( &self, future: impl Future<Output = Result<A, E>> + Send + 'static ) -> Handle<A>
Queues a new asset to be tracked by the AssetServer
and returns a Handle
to it. This can be used to track
dependencies of assets created at runtime.
After the asset has been fully loaded, it will show up in the relevant Assets
storage.
sourcepub fn load_folder<'a>(
&self,
path: impl Into<AssetPath<'a>>
) -> Handle<LoadedFolder>
pub fn load_folder<'a>( &self, path: impl Into<AssetPath<'a>> ) -> Handle<LoadedFolder>
Loads all assets from the specified folder recursively. The LoadedFolder
asset (when it loads) will
contain handles to all assets in the folder. You can wait for all assets to load by checking the LoadedFolder
’s
RecursiveDependencyLoadState
.
Loading the same folder multiple times will return the same handle. If the file_watcher
feature is enabled, LoadedFolder
handles will reload when a file in the folder is
removed, added or moved. This includes files in subdirectories and moving, adding,
or removing complete subdirectories.
sourcepub fn get_load_states(
&self,
id: impl Into<UntypedAssetId>
) -> Option<(LoadState, DependencyLoadState, RecursiveDependencyLoadState)>
pub fn get_load_states( &self, id: impl Into<UntypedAssetId> ) -> Option<(LoadState, DependencyLoadState, RecursiveDependencyLoadState)>
Retrieves all loads states for the given asset id.
sourcepub fn get_load_state(&self, id: impl Into<UntypedAssetId>) -> Option<LoadState>
pub fn get_load_state(&self, id: impl Into<UntypedAssetId>) -> Option<LoadState>
Retrieves the main LoadState
of a given asset id
.
Note that this is “just” the root asset load state. To check if an asset and its recursive
dependencies have loaded, see AssetServer::is_loaded_with_dependencies
.
sourcepub fn get_recursive_dependency_load_state(
&self,
id: impl Into<UntypedAssetId>
) -> Option<RecursiveDependencyLoadState>
pub fn get_recursive_dependency_load_state( &self, id: impl Into<UntypedAssetId> ) -> Option<RecursiveDependencyLoadState>
Retrieves the RecursiveDependencyLoadState
of a given asset id
.
sourcepub fn load_state(&self, id: impl Into<UntypedAssetId>) -> LoadState
pub fn load_state(&self, id: impl Into<UntypedAssetId>) -> LoadState
Retrieves the main LoadState
of a given asset id
.
sourcepub fn recursive_dependency_load_state(
&self,
id: impl Into<UntypedAssetId>
) -> RecursiveDependencyLoadState
pub fn recursive_dependency_load_state( &self, id: impl Into<UntypedAssetId> ) -> RecursiveDependencyLoadState
Retrieves the RecursiveDependencyLoadState
of a given asset id
.
sourcepub fn is_loaded_with_dependencies(&self, id: impl Into<UntypedAssetId>) -> bool
pub fn is_loaded_with_dependencies(&self, id: impl Into<UntypedAssetId>) -> bool
Returns true if the asset and all of its dependencies (recursive) have been loaded.
sourcepub fn get_handle<'a, A: Asset>(
&self,
path: impl Into<AssetPath<'a>>
) -> Option<Handle<A>>
pub fn get_handle<'a, A: Asset>( &self, path: impl Into<AssetPath<'a>> ) -> Option<Handle<A>>
Returns an active handle for the given path, if the asset at the given path has already started loading, or is still “alive”.
sourcepub fn get_id_handle<A: Asset>(&self, id: AssetId<A>) -> Option<Handle<A>>
pub fn get_id_handle<A: Asset>(&self, id: AssetId<A>) -> Option<Handle<A>>
Get a Handle
from an AssetId
.
This only returns Some
if id
is derived from a Handle
that was
loaded through an AssetServer
, otherwise it returns None
.
Consider using Assets::get_strong_handle
in the case the Handle
comes from Assets::add
.
sourcepub fn get_id_handle_untyped(&self, id: UntypedAssetId) -> Option<UntypedHandle>
pub fn get_id_handle_untyped(&self, id: UntypedAssetId) -> Option<UntypedHandle>
Get an UntypedHandle
from an UntypedAssetId
.
See AssetServer::get_id_handle
for details.
sourcepub fn is_managed(&self, id: impl Into<UntypedAssetId>) -> bool
pub fn is_managed(&self, id: impl Into<UntypedAssetId>) -> bool
Returns true
if the given id
corresponds to an asset that is managed by this AssetServer
.
Otherwise, returns false
.
sourcepub fn get_path_id<'a>(
&self,
path: impl Into<AssetPath<'a>>
) -> Option<UntypedAssetId>
pub fn get_path_id<'a>( &self, path: impl Into<AssetPath<'a>> ) -> Option<UntypedAssetId>
Returns an active untyped asset id for the given path, if the asset at the given path has already started loading, or is still “alive”. Returns the first ID in the event of multiple assets being registered against a single path.
§See also
get_path_ids
for all handles.
sourcepub fn get_path_ids<'a>(
&self,
path: impl Into<AssetPath<'a>>
) -> Vec<UntypedAssetId>
pub fn get_path_ids<'a>( &self, path: impl Into<AssetPath<'a>> ) -> Vec<UntypedAssetId>
Returns all active untyped asset IDs for the given path, if the assets at the given path have already started loading,
or are still “alive”.
Multiple IDs will be returned in the event that a single path is used by multiple AssetLoader
’s.
sourcepub fn get_handle_untyped<'a>(
&self,
path: impl Into<AssetPath<'a>>
) -> Option<UntypedHandle>
pub fn get_handle_untyped<'a>( &self, path: impl Into<AssetPath<'a>> ) -> Option<UntypedHandle>
Returns an active untyped handle for the given path, if the asset at the given path has already started loading, or is still “alive”. Returns the first handle in the event of multiple assets being registered against a single path.
§See also
get_handles_untyped
for all handles.
sourcepub fn get_handles_untyped<'a>(
&self,
path: impl Into<AssetPath<'a>>
) -> Vec<UntypedHandle>
pub fn get_handles_untyped<'a>( &self, path: impl Into<AssetPath<'a>> ) -> Vec<UntypedHandle>
Returns all active untyped handles for the given path, if the assets at the given path have already started loading,
or are still “alive”.
Multiple handles will be returned in the event that a single path is used by multiple AssetLoader
’s.
sourcepub fn get_path_and_type_id_handle(
&self,
path: &AssetPath<'_>,
type_id: TypeId
) -> Option<UntypedHandle>
pub fn get_path_and_type_id_handle( &self, path: &AssetPath<'_>, type_id: TypeId ) -> Option<UntypedHandle>
Returns an active untyped handle for the given path and TypeId
, if the asset at the given path has already started loading,
or is still “alive”.
sourcepub fn get_path(&self, id: impl Into<UntypedAssetId>) -> Option<AssetPath<'_>>
pub fn get_path(&self, id: impl Into<UntypedAssetId>) -> Option<AssetPath<'_>>
Returns the path for the given id
, if it has one.
sourcepub fn mode(&self) -> AssetServerMode
pub fn mode(&self) -> AssetServerMode
Returns the AssetServerMode
this server is currently in.
sourcepub fn preregister_loader<L: AssetLoader>(&self, extensions: &[&str])
pub fn preregister_loader<L: AssetLoader>(&self, extensions: &[&str])
Pre-register a loader that will later be added.
Assets loaded with matching extensions will be blocked until the real loader is added.
Trait Implementations§
source§impl Clone for AssetServer
impl Clone for AssetServer
source§fn clone(&self) -> AssetServer
fn clone(&self) -> AssetServer
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moresource§impl Debug for AssetServer
impl Debug for AssetServer
impl Resource for AssetServer
Auto Trait Implementations§
impl Freeze for AssetServer
impl !RefUnwindSafe for AssetServer
impl Send for AssetServer
impl Sync for AssetServer
impl Unpin for AssetServer
impl !UnwindSafe for AssetServer
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
source§fn into_any(self: Box<T>) -> Box<dyn Any>
fn into_any(self: Box<T>) -> Box<dyn Any>
Box<dyn Trait>
(where Trait: Downcast
) to Box<dyn Any>
. Box<dyn Any>
can
then be further downcast
into Box<ConcreteType>
where ConcreteType
implements Trait
.source§fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
Rc<Trait>
(where Trait: Downcast
) to Rc<Any>
. Rc<Any>
can then be
further downcast
into Rc<ConcreteType>
where ConcreteType
implements Trait
.source§fn as_any(&self) -> &(dyn Any + 'static)
fn as_any(&self) -> &(dyn Any + 'static)
&Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &Any
’s vtable from &Trait
’s.source§fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &mut Any
’s vtable from &mut Trait
’s.