Crate assets_manager

Expand description

Conveniently load, store and cache external resources.

This crate aims at providing a filesystem abstraction to easily load external resources. It was originally thought for games, but can, of course, be used in other contexts.

The structure AssetCache is the entry point of the crate. See Asset documentation to see how to define custom asset types.

§Cargo features

hot-reloading: Add hot-reloading.
macros: Add support for deriving Asset trait.

§Additional sources

Enable reading assets from sources other than the filesystem. These sources are defined in the source module:

embedded: Embeds asset files directly in your binary at compile time
zip: Reads assets from ZIP archives
- Optional compression: zip-deflate, zip-zstd
tar: Reads assets from TAR archives

§Additional formats

These features add support for various asset formats:

Serialisation formats (using serde): bincode, json, msgpack, ron, toml, yaml.
Image formats (using image): bmp, jpeg, png webp.
GlTF format (using gltf): gltf.

§External crates support

Support of some other crates is done in external crates:

§Internal features

These features change internal data structures implementations.

parking_lot: Use parking_lot’s synchronization primitives.
faster-hash: Use a faster hashing algorithm (enabled by default).

§Basic example

Given a file assets/common/position.ron which contains this:

Point(
    x: 5,
    y: -6,
)

You can load and use it as follows:

use assets_manager::{BoxedError, AssetCache, FileAsset};
use serde::Deserialize;
use std::borrow::Cow;

// The struct you want to load
#[derive(Deserialize)]
struct Point {
    x: i32,
    y: i32,
}

// Specify how you want the structure to be loaded
impl FileAsset for Point {
    // The extension of the files to look into
    const EXTENSION: &'static str = "ron";

    // The serialization format
    //
    // In this specific case, the derive macro could be used but we use the
    // full version as a demo.
    fn from_bytes(bytes: std::borrow::Cow<[u8]>) -> Result<Self, BoxedError> {
        assets_manager::asset::load_ron(&bytes)
    }
}

// Create a new cache to load assets under the "./assets" folder
let cache = AssetCache::new("assets")?;

// Get a handle on the asset
// This will load the file `./assets/common/position.ron`
let handle = cache.load::<Point>("common.position")?;

// Lock the asset for reading
// Any number of read locks can exist at the same time,
// but none can exist when the asset is reloaded
let point = handle.read();

// The asset is now ready to be used
assert_eq!(point.x, 5);
assert_eq!(point.y, -6);

// Loading the same asset retreives it from the cache
let other_handle = cache.load("common.position")?;
assert!(std::ptr::eq(handle, other_handle));

§Hot-reloading

Hot-reloading is a major feature of assets_manager: when a file is added, modified or deleted, the values of all assets that depend on this file are automatically and transparently updated. It is managed automatically in the background.

See the asset module for a precise description of how assets interact with hot-reloading.

Re-exports§

pub use asset::Asset;
pub use asset::Compound;Deprecated
pub use asset::FileAsset;
pub use asset::Storable;

Modules§

asset: Values loadable from a cache.
hot_reloading: Tools to implement hot-reloading.
source: Bytes sources to load assets from.

Structs§

ArcHandle: A strong pointer to a handle.
AssetCache: The main structure of this crate, used to load and store assets.
AssetReadGuard: RAII guard used to keep a read lock on an asset and release it when dropped.
AtomicReloadId: A ReloadId that can be shared between threads.
Directory: Stores ids in a directory containing assets of type T
Error: The error type which is used when loading an asset.
Handle: A handle on an asset.
OnceInitCellutils: A thread-safe cell which can be written to only once.
RawDirectory: Stores ids in a directory containing assets of type T
RawRecursiveDirectory: Stores ids in a recursive directory containing assets of type T
RecursiveDirectory: Stores ids in a recursive directory containing assets of type T
ReloadId: An id to know when an asset is reloaded.
ReloadWatcher: A watcher that can tell when an asset is reloaded.
SharedBytes: Bytes that can easily be shared.
SharedString: A string that can easily be shared.
WeakHandle: A weak pointer to a handle.

Type Aliases§

ArcUntypedHandle: An untyped version of ArcHandle.
BoxedError: A boxed error
UntypedHandle: A untyped handle on an asset.
WeakUntypedHandle: An untyped version of WeakHandle.

Derive Macros§

Assetmacros: Implements Asset for a type.

Crate assets_managerCopy item path