bevy_asset/
meta.rs

1//! Handle asset metadata.
2//! Asset metadata informs how an [`Asset`] should be handled by the asset system.
3//!
4//! It is primarily used by [asset processing](crate::processor).
5//!
6//! Asset metadata is generally stored as a `.meta` file next to the asset,
7//! but this may differ per asset storage backend.
8
9use alloc::{
10    boxed::Box,
11    string::{String, ToString},
12    vec::Vec,
13};
14use futures_lite::AsyncReadExt;
15
16use crate::{
17    io::{AssetReaderError, Reader},
18    loader::AssetLoader,
19    processor::Process,
20    Asset, AssetPath, DeserializeMetaError, VisitAssetDependencies,
21};
22use downcast_rs::{impl_downcast, Downcast};
23use ron::ser::PrettyConfig;
24use serde::{Deserialize, Serialize};
25use tracing::error;
26
27/// The version of the metadata format being used.
28/// It is included in every metadata entry.
29///
30/// This constant will be updated whenever a breaking change is made to the format.
31pub const META_FORMAT_VERSION: &str = "1.0";
32pub type MetaTransform = Box<dyn Fn(&mut dyn AssetMetaDyn) + Send + Sync>;
33
34/// Asset metadata that informs how an [`Asset`] should be handled by the asset system.
35///
36/// `L` is the [`AssetLoader`] (if one is configured) for the [`AssetAction`]. This can be `()` if it is not required.
37/// `P` is the [`Process`] processor, if one is configured for the [`AssetAction`]. This can be `()` if it is not required.
38#[derive(Serialize, Deserialize)]
39pub struct AssetMeta<L: AssetLoader, P: Process> {
40    /// The version of the meta format being used. This will change whenever a breaking change is made to
41    /// the meta format.
42    pub meta_format_version: String,
43    /// Information produced by the [`AssetProcessor`] _after_ processing this asset.
44    /// This will only exist alongside processed versions of assets. You should not manually set it in your asset source files.
45    ///
46    /// [`AssetProcessor`]: crate::processor::AssetProcessor
47    #[serde(skip_serializing_if = "Option::is_none")]
48    pub processed_info: Option<ProcessedInfo>,
49    /// How to handle this asset in the asset system. See [`AssetAction`].
50    pub asset: AssetAction<L::Settings, P::Settings>,
51}
52
53impl<L: AssetLoader, P: Process> AssetMeta<L, P> {
54    pub fn new(asset: AssetAction<L::Settings, P::Settings>) -> Self {
55        Self {
56            meta_format_version: META_FORMAT_VERSION.to_string(),
57            processed_info: None,
58            asset,
59        }
60    }
61
62    /// Deserializes the given serialized byte representation of the asset meta.
63    pub fn deserialize(bytes: &[u8]) -> Result<Self, DeserializeMetaError> {
64        Ok(ron::de::from_bytes(bytes)?)
65    }
66}
67
68/// Configures how an asset source file should be handled by the asset system.
69#[derive(Serialize, Deserialize)]
70pub enum AssetAction<LoaderSettings, ProcessSettings> {
71    /// Load the asset with the given loader and settings
72    /// See [`AssetLoader`].
73    Load {
74        loader: String,
75        settings: LoaderSettings,
76    },
77    /// Process the asset with the given processor and settings.
78    /// See [`Process`] and [`AssetProcessor`].
79    ///
80    /// [`AssetProcessor`]: crate::processor::AssetProcessor
81    Process {
82        processor: String,
83        settings: ProcessSettings,
84    },
85    /// Do nothing with the asset
86    Ignore,
87}
88
89/// Info produced by the [`AssetProcessor`] for a given processed asset. This is used to determine if an
90/// asset source file (or its dependencies) has changed.
91///
92/// [`AssetProcessor`]: crate::processor::AssetProcessor
93#[derive(Serialize, Deserialize, Default, Debug, Clone)]
94pub struct ProcessedInfo {
95    /// A hash of the asset bytes and the asset `.meta` data
96    pub hash: AssetHash,
97    /// A hash of the asset bytes, the asset .meta data, and the `full_hash` of every `process_dependency`
98    pub full_hash: AssetHash,
99    /// Information about the "process dependencies" used to process this asset.
100    pub process_dependencies: Vec<ProcessDependencyInfo>,
101}
102
103/// Information about a dependency used to process an asset. This is used to determine whether an asset's "process dependency"
104/// has changed.
105#[derive(Serialize, Deserialize, Debug, Clone)]
106pub struct ProcessDependencyInfo {
107    /// A hash of the dependency's `.meta` data and [`ProcessedInfo`] information.
108    pub full_hash: AssetHash,
109    pub path: AssetPath<'static>,
110}
111
112/// This is a minimal counterpart to [`AssetMeta`] that exists to speed up (or enable) serialization in cases where the whole [`AssetMeta`] isn't
113/// necessary.
114// PERF:
115// Currently, this is used when retrieving asset loader and processor information (when the actual type is not known yet). This could probably
116// be replaced (and made more efficient) by a custom deserializer that reads the loader/processor information _first_, then deserializes the contents
117// using a type registry.
118#[derive(Serialize, Deserialize)]
119pub struct AssetMetaMinimal {
120    pub asset: AssetActionMinimal,
121}
122
123/// This is a minimal counterpart to [`AssetAction`] that exists to speed up (or enable) serialization in cases where the whole [`AssetAction`]
124/// isn't necessary.
125#[derive(Serialize, Deserialize)]
126pub enum AssetActionMinimal {
127    /// Load the asset with the given loader.
128    /// See [`AssetLoader`].
129    Load { loader: String },
130    /// Process the asset with the given processor.
131    /// See [`Process`] and [`AssetProcessor`].
132    ///
133    /// [`AssetProcessor`]: crate::processor::AssetProcessor
134    Process { processor: String },
135    /// Do nothing with the asset
136    Ignore,
137}
138
139/// This is a minimal counterpart to [`ProcessedInfo`] that exists to speed up serialization in cases where the whole [`ProcessedInfo`] isn't
140/// necessary.
141#[derive(Serialize, Deserialize)]
142pub struct ProcessedInfoMinimal {
143    /// Info produced by the [`AssetProcessor`] for a given processed asset.
144    ///
145    /// [`AssetProcessor`]: crate::processor::AssetProcessor
146    pub processed_info: Option<ProcessedInfo>,
147}
148
149/// A dynamic type-erased counterpart to [`AssetMeta`] that enables passing around and interacting with [`AssetMeta`] without knowing
150/// its type.
151pub trait AssetMetaDyn: Downcast + Send + Sync {
152    /// Returns a reference to the [`AssetLoader`] settings, if they exist.
153    fn loader_settings(&self) -> Option<&dyn Settings>;
154    /// Returns a mutable reference to the [`AssetLoader`] settings, if they exist.
155    fn loader_settings_mut(&mut self) -> Option<&mut dyn Settings>;
156    /// Returns a reference to the [`Process`] settings, if they exist.
157    fn process_settings(&self) -> Option<&dyn Settings>;
158    /// Serializes the internal [`AssetMeta`].
159    fn serialize(&self) -> Vec<u8>;
160    /// Returns a reference to the [`ProcessedInfo`] if it exists.
161    fn processed_info(&self) -> &Option<ProcessedInfo>;
162    /// Returns a mutable reference to the [`ProcessedInfo`] if it exists.
163    fn processed_info_mut(&mut self) -> &mut Option<ProcessedInfo>;
164}
165
166impl<L: AssetLoader, P: Process> AssetMetaDyn for AssetMeta<L, P> {
167    fn loader_settings(&self) -> Option<&dyn Settings> {
168        if let AssetAction::Load { settings, .. } = &self.asset {
169            Some(settings)
170        } else {
171            None
172        }
173    }
174    fn loader_settings_mut(&mut self) -> Option<&mut dyn Settings> {
175        if let AssetAction::Load { settings, .. } = &mut self.asset {
176            Some(settings)
177        } else {
178            None
179        }
180    }
181    fn process_settings(&self) -> Option<&dyn Settings> {
182        if let AssetAction::Process { settings, .. } = &self.asset {
183            Some(settings)
184        } else {
185            None
186        }
187    }
188    fn serialize(&self) -> Vec<u8> {
189        ron::ser::to_string_pretty(
190            &self,
191            // This defaults to \r\n on Windows, so hard-code it to \n so it's consistent for
192            // testing.
193            PrettyConfig::default().new_line("\n"),
194        )
195        .expect("type is convertible to ron")
196        .into_bytes()
197    }
198    fn processed_info(&self) -> &Option<ProcessedInfo> {
199        &self.processed_info
200    }
201    fn processed_info_mut(&mut self) -> &mut Option<ProcessedInfo> {
202        &mut self.processed_info
203    }
204}
205
206impl_downcast!(AssetMetaDyn);
207
208/// Settings used by the asset system, such as by [`AssetLoader`], [`Process`], and [`AssetSaver`]
209///
210/// [`AssetSaver`]: crate::saver::AssetSaver
211pub trait Settings: Downcast + Send + Sync + 'static {}
212
213impl<T: 'static> Settings for T where T: Send + Sync {}
214
215impl_downcast!(Settings);
216
217/// The () processor should never be called. This implementation exists to make the meta format nicer to work with.
218impl Process for () {
219    type Settings = ();
220    type OutputLoader = ();
221
222    async fn process(
223        &self,
224        _context: &mut bevy_asset::processor::ProcessContext<'_>,
225        _settings: &Self::Settings,
226        _writer: &mut bevy_asset::io::Writer,
227    ) -> Result<(), bevy_asset::processor::ProcessError> {
228        unreachable!()
229    }
230}
231
232impl Asset for () {}
233
234impl VisitAssetDependencies for () {
235    fn visit_dependencies(&self, _visit: &mut impl FnMut(bevy_asset::UntypedAssetId)) {
236        unreachable!()
237    }
238}
239
240/// The () loader should never be called. This implementation exists to make the meta format nicer to work with.
241impl AssetLoader for () {
242    type Asset = ();
243    type Settings = ();
244    type Error = std::io::Error;
245    async fn load(
246        &self,
247        _reader: &mut dyn Reader,
248        _settings: &Self::Settings,
249        _load_context: &mut crate::LoadContext<'_>,
250    ) -> Result<Self::Asset, Self::Error> {
251        unreachable!();
252    }
253
254    fn extensions(&self) -> &[&str] {
255        unreachable!();
256    }
257}
258
259pub(crate) fn meta_transform_settings<S: Settings>(
260    meta: &mut dyn AssetMetaDyn,
261    settings: &(impl Fn(&mut S) + Send + Sync + 'static),
262) {
263    if let Some(loader_settings) = meta.loader_settings_mut() {
264        if let Some(loader_settings) = loader_settings.downcast_mut::<S>() {
265            settings(loader_settings);
266        } else {
267            error!(
268                "Configured settings type {} does not match AssetLoader settings type",
269                core::any::type_name::<S>(),
270            );
271        }
272    }
273}
274
275pub(crate) fn loader_settings_meta_transform<S: Settings>(
276    settings: impl Fn(&mut S) + Send + Sync + 'static,
277) -> MetaTransform {
278    Box::new(move |meta| meta_transform_settings(meta, &settings))
279}
280
281/// This type alias records the size of an asset hash.
282pub type AssetHash = [u8; 32];
283
284/// NOTE: changing the hashing logic here is a _breaking change_ that requires a [`META_FORMAT_VERSION`] bump.
285pub(crate) async fn get_asset_hash(
286    meta_bytes: &[u8],
287    asset_reader: &mut impl Reader,
288) -> Result<AssetHash, AssetReaderError> {
289    let mut hasher = blake3::Hasher::new();
290    hasher.update(meta_bytes);
291    let mut buffer = [0; blake3::CHUNK_LEN];
292    loop {
293        let bytes_read = asset_reader.read(&mut buffer).await?;
294        hasher.update(&buffer[..bytes_read]);
295        if bytes_read == 0 {
296            // This means we've reached EOF, so we're done consuming asset bytes.
297            break;
298        }
299    }
300    Ok(*hasher.finalize().as_bytes())
301}
302
303/// NOTE: changing the hashing logic here is a _breaking change_ that requires a [`META_FORMAT_VERSION`] bump.
304pub(crate) fn get_full_asset_hash(
305    asset_hash: AssetHash,
306    dependency_hashes: impl Iterator<Item = AssetHash>,
307) -> AssetHash {
308    let mut hasher = blake3::Hasher::new();
309    hasher.update(&asset_hash);
310    for hash in dependency_hashes {
311        hasher.update(&hash);
312    }
313    *hasher.finalize().as_bytes()
314}
bevy_asset/meta.rs

bevy_asset/
meta.rs
