bevy_asset/
meta.rs

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

bevy_asset/
meta.rs
