keket/lib.rs
1//! # Keket - Asset Management for Rust
2//!
3//! [](https://crates.io/keket)
4//! [](https://docs.rs/keket)
5//! [](https://psichix.github.io/Keket)
6//! [](https://github.com/PsichiX/Keket/actions/workflows/rust.yml
7//!
8//! **Database-like Asset management on top of ECS storage.**
9//!
10//! ---
11//!
12//! This crate provides a robust framework for managing assets in Rust, from loading and fetching assets
13//! from various sources (HTTP, local file system, databases, etc.) to advanced features like asset
14//! hot-reloading, deferred loading, and integration with game engines or other large projects.
15//! It leverages dynamic component-based bundles to easily manage and interact with assets on demand.
16//!
17//! ## Key Features
18//!
19//! - **Flexible Asset Fetching**: Fetch assets from a variety of sources such as the local filesystem, HTTP URLs, or databases.
20//! - **Dynamic Bundling**: Combine different pieces of asset data in a flexible way using the `DynamicBundle` container.
21//! - **Hot Reloading**: Supports automatic hot reloading of assets, allowing you to dynamically update content without restarting the application.
22//! - **Deferred Loading**: Perform heavy asset loading tasks asynchronously using background jobs to prevent blocking the main application thread.
23//! - **Multi-Source Support**: Load assets from a range of containers (e.g., file system, in-memory collections, or databases), and even support custom ones with the flexible `ContainerPartialFetch` trait.
24//! - **Error Handling**: Rich error handling mechanism that makes debugging asset loading problems quick and easy.
25//!
26//! ## Example Usage
27//!
28//! ```rust
29//! use keket::{
30//! database::{path::AssetPath, AssetDatabase},
31//! fetch::file::FileAssetFetch,
32//! protocol::{bundle::BundleAssetProtocol, bytes::BytesAssetProtocol, text::TextAssetProtocol},
33//! };
34//! use serde_json::Value;
35//! use std::{error::Error, fs::Metadata, path::PathBuf};
36//!
37//! fn main() -> Result<(), Box<dyn Error>> {
38//! # std::env::set_current_dir("../../"); // change path for tests run.
39//! let mut database = AssetDatabase::default()
40//! .with_protocol(TextAssetProtocol)
41//! .with_protocol(BytesAssetProtocol)
42//! .with_protocol(BundleAssetProtocol::new("json", |bytes: Vec<u8>| {
43//! Ok((serde_json::from_slice::<Value>(&bytes)?,).into())
44//! }))
45//! .with_fetch(FileAssetFetch::default().with_root("resources"));
46//!
47//! let lorem = database.ensure("text://lorem.txt")?;
48//! println!("Lorem Ipsum: {}", lorem.access::<&String>(&database));
49//!
50//! let person = database.ensure("json://person.json")?;
51//! println!("Person: {:#?}", person.access::<&Value>(&database));
52//!
53//! let trash = database.ensure("bytes://trash.bin")?;
54//! println!("Bytes: {:?}", trash.access::<&Vec<u8>>(&database));
55//!
56//! for (asset_path, file_path, metadata) in database
57//! .storage
58//! .query::<true, (&AssetPath, &PathBuf, &Metadata)>()
59//! {
60//! println!(
61//! "Asset: `{}` at location: {:?} has metadata: {:#?}",
62//! asset_path, file_path, metadata
63//! );
64//! }
65//!
66//! Ok(())
67//! }
68//! ```
69//!
70//! More examples:
71//!
72//! - [Hello World!](https://github.com/PsichiX/Keket/tree/master/crates/_/examples/01_hello_world.rs)
73//! - [ZIP archive](https://github.com/PsichiX/Keket/tree/master/crates/_/examples/02_zip.rs)
74//! - [Dependencies](https://github.com/PsichiX/Keket/tree/master/crates/_/examples/03_dependencies.rs)
75//! - [Events](https://github.com/PsichiX/Keket/tree/master/crates/_/examples/04_events.rs)
76//! - [Async loading](https://github.com/PsichiX/Keket/tree/master/crates/_/examples/05_deferred_fetch.rs)
77//! - [Routing](https://github.com/PsichiX/Keket/tree/master/crates/_/examples/06_router_fetch.rs)
78//! - [Fallback assets](https://github.com/PsichiX/Keket/tree/master/crates/_/examples/07_fallback.rs)
79//! - [DLC asset packs](https://github.com/PsichiX/Keket/tree/master/crates/_/examples/08_dlcs_asset_packs.rs)
80//! - [Hot reloading](https://github.com/PsichiX/Keket/tree/master/crates/_/examples/09_hot_reloading.rs)
81//! - [Asset references](https://github.com/PsichiX/Keket/tree/master/crates/_/examples/10_references.rs)
82//! - [Custom simple protocol](https://github.com/PsichiX/Keket/tree/master/crates/_/examples/11_custom_protocol_simple.rs)
83//! - [Custom advanced protocol](https://github.com/PsichiX/Keket/tree/master/crates/_/examples/12_custom_protocol_advanced.rs)
84//! - [Custom fetch engine](https://github.com/PsichiX/Keket/tree/master/crates/_/examples/13_custom_fetch.rs)
85//! - [Assets versioning](https://github.com/PsichiX/Keket/tree/master/crates/_/examples/14_assets_versioning.rs)
86//! - [Localized assets](https://github.com/PsichiX/Keket/tree/master/crates/_/examples/15_localized_assets.rs)
87//! - [Extract from asset](https://github.com/PsichiX/Keket/tree/master/crates/_/examples/16_extract_from_asset.rs)
88//! - [HTTP fetch engine](https://github.com/PsichiX/Keket/tree/master/crates/http/examples/hello_http.rs)
89//! - [REDB fetch engine](https://github.com/PsichiX/Keket/tree/master/crates/redb/examples/hello_redb.rs)
90//! - [Asset server fetch engine](https://github.com/PsichiX/Keket/tree/master/crates/client/examples/hello_client.rs)
91//! - [In-game scenario](https://github.com/PsichiX/Keket/tree/master/crates/_/examples/ingame.rs)
92//!
93//! ## Architecture
94//!
95//! Keket asset management design is built around modularity to allow users to change parts to build their asset pipeline tailored to their needs.
96//!
97//! Key concepts:
98//!
99//! - `AssetDatabase` - central place where assets live. ECS storage allows for ergonomics of access and processing of huge amount of data at once in database-like manner.
100//! - `AssetHandle` - wrapper around asset entity that allows easy direct operations and access to resolved asset. Asset database
101//! - `AssetPath` - specialized path that describes an asset identifier (`<protocol>://<path/to/asset.extension>?<meta-information>`).
102//! Examples:
103//! - `image://grass.png`
104//! - `mesh://teapot.gltf?lod=2`
105//! - `AssetRef` - wrapper around asset path and cached asset handle. Useful for serialization. Allows to resolve asset once and reuse cached handle later.
106//! - `AssetFetch` - an engine telling where from asset bytes are loaded. Basic one is `FileAssetFetch`.
107//! - `AssetProtocol` - an engine telling how fetched asset bytes are decoded into asset components, selected based on asset path protocol part. For example `TextAssetProtocol` or `BytesAssetProtocol`.
108//!
109//! ## Use Cases
110//!
111//! - **Game Development**: Load and manage game assets (e.g., textures, sound files) from different sources and automatically reload them during runtime.
112//! - **Web Applications**: Dynamically fetch and cache static files from HTTP endpoints and the file system.
113//! - **Data-Driven Applications**: Fetch and manage resources such as user-generated content, configuration files, or assets in a multi-environment scenario.
114//! - **Asset-Centric Systems**: Any system that requires efficient asset management with flexible, reactive fetching behaviors.
115//!
116//! Whether you're building games, web apps, or anything else that requires managing and fetching assets, this crate has you covered with ease and flexibility.
117//! Enjoy on-the-fly reloading, asynchronous fetching, and a simple, intuitive API designed with efficiency in mind.
118//!
119//! ## Roadmap
120//!
121//! - Assets versioning
122//! - Localized assets
123//! - Performance tools and usage stats
124
125pub mod database;
126pub mod fetch;
127pub mod protocol;
128pub mod store;
129
130pub mod third_party {
131 pub use anput;
132}