Struct ResourceManager 

pub struct ResourceManager { /* private fields */ }

Resource manager controls loading and lifetime of resource in the engine. Resource manager can hold resources of arbitrary types via type erasure mechanism.

Built-in Resources

Built-in resources are special kinds of resources, whose data is packed in the executable (i.e. via include_bytes macro). Such resources reference the data that cannot be “loaded” from external source. To support such kind of resource the manager provides built_in_resources hash map where you can register your own built-in resource and access existing ones.

Internals

It is a simple wrapper over ResourceManagerState that can be shared (cloned). In other words, it is just a strong reference to the inner state.

Implementations

impl ResourceManager

pub fn new(io: Arc<dyn ResourceIo>, task_pool: Arc<TaskPool>) -> ResourceManager

Creates a resource manager with default settings and loaders.

pub fn state(&self) -> MutexGuard<'_, RawMutex, ResourceManagerState>

Returns a guarded reference to the internal state of resource manager. This is blocking method and it may deadlock if used incorrectly (trying to get the state lock one more time when there’s an existing lock in the same thread, multi-threading-related deadlock and so on).

pub fn try_get_state( &self, timeout: Duration, ) -> Option<MutexGuard<'_, RawMutex, ResourceManagerState>>

Returns a guarded reference to the internal state of resource manager. This method will try to acquire the state lock for the given time and if it fails, returns None.

pub async fn registry_is_loaded(&self) -> bool

The resource manager keeps a registry of available resources, and this registry must be loaded before any resources may be requested. This async method returns once the registry loading is complete and it returns true if the loading was successful. It returns false if loading failed.

pub fn resource_io(&self) -> Arc<dyn ResourceIo>

Returns the ResourceIo used by this resource manager

pub fn task_pool(&self) -> Arc<TaskPool>

Returns the task pool used by this resource manager.

pub fn registry_folder(&self) -> PathBuf

Returns an absolute path to the registry folder (absolute version of ./data by default).

pub fn register_built_in_resource<T>( &self, resource: BuiltInResource<T>, ) -> Option<UntypedBuiltInResource>

where T: TypedResourceData,

Registers a new built-in resource, so it becomes accessible via Self::request.

pub fn try_find<T>(&self, path: impl AsRef<Path>) -> Option<Resource<T>>

where T: TypedResourceData,

The same as Self::find, but returns None if type UUID of T does not match the actual type UUID of the resource.

Panic

This method does not panic.

pub fn find<T>(&self, path: impl AsRef<Path>) -> Resource<T>

where T: TypedResourceData,

Find the resource for the given path without loading the resource. A new unloaded resource is created if one does not already exist. If the path is not in the registry then a new UUID is generated and the path is added to the registry. If the resource is not already loading, then it will be returned in the ResourceState::Unloaded state, and Self::request_resource may be used to begin the loading process.

Panic

This method will panic if type UUID of T does not match the actual type UUID of the resource. If this is undesirable, use Self::try_find instead.

pub fn find_uuid<T>(&self, uuid: Uuid) -> Resource<T>

where T: TypedResourceData,

Find the resource for the given UUID without loading the resource. If the resource is not already loading, then it will be returned in the ResourceState::Unloaded state, and Self::request_resource may be used to begin the loading process.

Panic

This method will panic if type UUID of T does not match the actual type UUID of the resource. If this is undesirable, use Self::try_find instead.

pub fn request<T>(&self, path: impl AsRef<Path>) -> Resource<T>

where T: TypedResourceData,

Requests a resource of the given type located at the given path. This method is non-blocking, instead it immediately returns the typed resource wrapper. Loading of the resource is managed automatically in a separate thread (or thread pool) on PC, and JS micro-task (the same thread) on WebAssembly.

Type Guarantees

There’s no strict guarantees that the requested resource will be of the requested type. This is because the resource system is fully async and does not have access to type information in most cases. Initial type checking is not very reliable and can be “fooled” pretty easily, simply because it just checks if there’s a registered loader for a specific extension.

Sharing

If the resource at the given path is already was requested (no matter in which state the actual resource is), this method will return the existing instance. This way the resource manager guarantees that the actual resource data will be loaded once, and it can be shared.

Waiting

If you need to wait until the resource is loaded, use .await on the result of the method. Every resource implements Future trait and can be used in async contexts.

Resource state

Keep in mind, that the resource itself is a small state machine. It could be in three main states:

• ResourceState::Pending - a resource is in the queue to load or still loading.
• ResourceState::LoadError - a resource is failed to load.
• ResourceState::Ok - a resource is successfully loaded.

Actual resource state can be fetched by Resource::state method. If you know for sure that the resource is already loaded, then you can use Resource::data_ref to obtain a reference to the actual resource data. Keep in mind, that this method will panic if the resource non in Ok state.

Panic

This method will panic, if type UUID of T does not match the actual type UUID of the resource. If this is undesirable, use Self::try_request instead.

pub fn request_resource<T>(&self, resource: &mut Resource<T>)

where T: TypedResourceData,

Requests that given resource should begin loading, if not already loading or loaded. This method is non-blocking, instead it modifies the given resource and returns. Loading of the resource is managed automatically in a separate thread (or thread pool) on PC, and JS micro-task (the same thread) on WebAssembly.

Type Guarantees

There’s no strict guarantees that the requested resource will be of the requested type. This is because the resource system is fully async and does not have access to type information in most cases. Initial type checking is not very reliable and can be “fooled” pretty easily, simply because it just checks if there’s a registered loader for a specific extension.

Sharing

If a resource with given resource’s UUID was already requested (no matter in which state the actual resource is), this method will modify the given resource to be a shared reference to the already loading resource. This way the resource manager guarantees that the actual resource data will be loaded once, and it can be shared.

Resource state

Keep in mind, that the resource itself is a small state machine. It could be in these states:

• ResourceState::Unloaded - a resource that has not started loading. Calling this method updates the resource into the Pending state.
• ResourceState::Pending - a resource is in the queue to load or still loading.
• ResourceState::LoadError - a resource is failed to load.
• ResourceState::Ok - a resource is successfully loaded.

Actual resource state can be fetched by Resource::state method. If you know for sure that the resource is already loaded, then you can use Resource::data_ref to obtain a reference to the actual resource data. Keep in mind, that this method will panic if the resource non in Ok state.

Panic

This method will panic, if type UUID of T does not match the actual type UUID of the resource. If this is undesirable, use Self::try_request instead.

pub fn add_resource<T>(&self, resource: &mut Resource<T>)

where T: TypedResourceData,

Add the given resource to the resource manager, based on the resource’s UUID, without initiating the loading of the resource. The given resource is modified to be a reference to the shared data of an existing resource with the same UUID.

pub fn try_request<T>(&self, path: impl AsRef<Path>) -> Option<Resource<T>>

where T: TypedResourceData,

The same as Self::request, but returns None if type UUID of T does not match the actual type UUID of the resource.

Panic

This method does not panic.

pub fn resource_path( &self, resource: impl AsRef<UntypedResource>, ) -> Option<PathBuf>

Tries to fetch a path of the given untyped resource. The path may be missing in a few cases:

1. The resource is in invalid state (not in ResourceState::Ok).
2. The resource wasn’t registered in the resource registry.
3. The resource registry wasn’t loaded.

pub fn uuid_to_resource_path(&self, resource_uuid: Uuid) -> Option<PathBuf>

Tries to fetch a resource path associated with the given UUID. Returns None if there’s no resource with the given UUID.

pub fn request_untyped<P>(&self, path: P) -> UntypedResource

where P: AsRef<Path>,

Same as Self::request, but returns untyped resource.

pub fn update_or_load_registry(&self)

Tries to update the registry if possible on the current platform, and if not - try to load an existing one. Some platforms do not have a file system, so the registry must be prepared on a platform that does have it and then saved to be loaded later on. For example, WebAssembly platform does not have a file system and the resource manager will try to load an existing registry instead of updating it.

pub fn add_loader<T>(&self, loader: T) -> Option<T>

where T: ResourceLoader,

Adds a new resource loader of the given type.

pub fn register( &self, resource: UntypedResource, path: impl AsRef<Path>, ) -> Result<(), ResourceRegistrationError>

Add the given resource to the manager and registers the resource as an external resource with the given path, updating the metadata file with the resource’s UUID and updating the registry file with the resource’s path. Calling this should only be necessary after newly creating the file in the given path by saving the resource to the file, otherwise the resource’s path should already have been discovered by ResourceManager::update_or_load_registry. If the manager already has a resource with this resource’s UUID, return ResourceRegistrationError::AlreadyRegistered.

pub fn is_built_in_resource_path(&self, resource: impl AsRef<Path>) -> bool

Checks whether the given resource path corresponds to a built-in resource or not.

pub fn is_built_in_resource( &self, resource: impl AsRef<UntypedResource>, ) -> bool

Checks whether the given resource is a built-in resource instance or not.

pub async fn make_resource_move_context( &self, src_path: impl AsRef<Path>, dest_path: impl AsRef<Path>, overwrite_existing: bool, ) -> Result<ResourceMoveContext, ResourceMovementError>

Creates a resource movement context.

pub async fn can_resource_be_moved( &self, src_path: impl AsRef<Path>, dest_path: impl AsRef<Path>, overwrite_existing: bool, ) -> bool

Returns true if a resource at the src_path can be moved to the dest_path, false - otherwise. Source path must be a valid resource path, and the dest path must have a valid new directory part of the path.

pub async fn move_resource_by_path( &self, src_path: impl AsRef<Path>, dest_path: impl AsRef<Path>, overwrite_existing: bool, ) -> Result<(), ResourceMovementError>

Tries to move a resource at the given path to the new path. The path of the resource must be registered in the resource registry for the resource to be moveable. This method can also be used to rename the source file of a resource.

pub async fn move_resource( &self, resource: impl AsRef<UntypedResource>, new_path: impl AsRef<Path>, overwrite_existing: bool, ) -> Result<(), ResourceMovementError>

Attempts to move a resource from its current location to the new path. The resource must be registered in the resource registry to be moveable. This method can also be used to rename the source file of a resource.

pub async fn reload_resources(&self)

Reloads all loaded resources. Normally it should never be called, because it is very heavy method! This method is asynchronous, it uses all available CPU power to reload resources as fast as possible.

pub fn is_supported_resource(&self, path: &Path) -> bool

Checks if there’s a loader for the given resource path.

pub fn is_path_in_registry(&self, path: &Path) -> bool

Checks if the given path is located inside the folder tracked by the resource registry.

pub async fn try_move_folder( &self, src_dir: &Path, dest_dir: &Path, overwrite_existing: bool, ) -> Result<(), FolderMovementError>

Tries to move a folder to some other folder.

pub async fn resave_native_resources(&self)

Tries to resave all the native resources registered in the resource registry. This method could be useful for assets migration to a newer version.

Platform-specific

Does nothing on WebAssembly.

Trait Implementations

impl Clone for ResourceManager

fn clone(&self) -> ResourceManager

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ResourceManager

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

Formats the value using the given formatter.