khora_core/asset/
metadata.rs

1// Copyright 2025 eraflo
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15use super::uuid::AssetUUID;
16use serde::{Deserialize, Serialize};
17use std::{collections::HashMap, path::PathBuf};
18
19/// Represents the physical source of an asset's data.
20///
21/// This enum allows the asset system to transparently handle assets from two
22/// different contexts:
23/// - In editor/development mode, assets are loaded directly from loose files on disk (`Path`).
24/// - In release/standalone mode, assets are loaded from an optimized packfile (`Packed`).
25#[derive(Debug, Clone, Serialize, Deserialize)]
26pub enum AssetSource {
27    /// The asset is a loose file on disk. The `PathBuf` points to the file.
28    Path(PathBuf),
29    /// The asset is located within a packfile.
30    Packed {
31        /// The byte offset from the beginning of the packfile where the data starts.
32        offset: u64,
33        /// The total size of the asset's data in bytes.
34        size: u64,
35    },
36}
37
38/// Serializable metadata that describes an asset and its relationships.
39///
40/// This structure serves as the "identity card" for each asset within the engine's
41/// Virtual File System (VFS). It contains all the information needed by the
42/// `AssetAgent` to make intelligent loading and management decisions *without*
43/// having to load the actual asset data from disk.
44///
45/// A collection of these metadata entries forms the VFS "Index".
46#[derive(Debug, Clone, Serialize, Deserialize)]
47pub struct AssetMetadata {
48    /// The unique, stable identifier for this asset. This is the primary key.
49    pub uuid: AssetUUID,
50
51    /// The canonical path to the original source file (e.g., a `.blend` or `.png`).
52    /// This is primarily used by the asset importer and editor tooling.
53    pub source_path: PathBuf,
54
55    /// A string identifier for the asset's type (e.g., "texture", "mesh", "material").
56    /// This is used by the loading system to select the correct `AssetLoader` trait object.
57    pub asset_type_name: String,
58
59    /// A list of other assets that this asset directly depends on.
60    /// For example, a material asset would list its required texture assets here.
61    /// This information is crucial for tracking dependencies and ensuring all
62    /// necessary assets are loaded.
63    pub dependencies: Vec<AssetUUID>,
64
65    /// A map of available, pre-processed asset variants ready for runtime use.
66    ///
67    /// The key is a variant identifier (e.g., "LOD0", "4K", "low_quality"),
68    /// and the value is the source of the compiled, engine-ready file for that variant. (Which contains the necessary metadata for loading the asset.)
69    /// This map allows the `AssetAgent` to make strategic choices, such as loading
70    /// a lower-quality texture to stay within a VRAM budget.
71    pub variants: HashMap<String, AssetSource>,
72
73    /// A collection of semantic tags for advanced querying and organization.
74    /// Tags can be used to group assets for collective operations, such as
75    /// loading all assets for a specific game level or character.
76    pub tags: Vec<String>,
77}
khora_core/asset/metadata.rs

khora_core/asset/
metadata.rs
