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