Make imported asset fingerprints deterministic

This commit is contained in:
Rbanh committed 2026-07-13 11:23:06 -04:00
1 parent a048233fce
commit e1b2f86a49
27 files changed
+798 -135

No files matched your search

+32 -24
View File
@@ -3,7 +3,6 @@
use std::collections::BTreeSet;
use std::fs;
use std::path::Path;
use std::time::UNIX_EPOCH;
use serde::Deserialize;
use shared::{
@@ -14,6 +13,7 @@ use shared::{
};
use crate::asset_db::AssetRecord;
use crate::assets::fingerprint::write_pretty_ron_if_changed;
pub fn animation_manifest_path(asset_id: &str) -> String {
format!("{ANIMATION_ARTIFACT_DIR}/{asset_id}.animation.ron")
@@ -32,15 +32,9 @@ pub fn refresh_animation_artifact(record: &mut AssetRecord) -> Result<AnimationM
record.dependencies.sort();
record.dependencies.dedup();
let text = ron::ser::to_string_pretty(&manifest, ron::ser::PrettyConfig::default())
.map_err(|error| format!("could not serialize animation manifest: {error}"))?;
if let Some(parent) = Path::new(&path).parent() {
fs::create_dir_all(parent)
.map_err(|error| format!("could not create {}: {error}", parent.display()))?;
}
if fs::read_to_string(&path).ok().as_deref() != Some(text.as_str()) {
fs::write(&path, text)
.map_err(|error| format!("could not write animation manifest {path}: {error}"))?;
if write_pretty_ron_if_changed(&path, &manifest)
.map_err(|error| format!("could not publish animation manifest {path}: {error}"))?
{
bevy::log::info!(
"Animation manifest refreshed: source={} artifact={} skeletons={} clips={} runtime_supported={}",
record.path,
@@ -63,7 +57,7 @@ pub fn load_animation_manifest(path: &str) -> Result<AnimationManifest, String>
pub fn build_animation_manifest(record: &AssetRecord) -> Result<AnimationManifest, String> {
let bytes = fs::read(&record.path)
.map_err(|error| format!("could not read {}: {error}", record.path))?;
let fingerprint = source_fingerprint(&record.path, &bytes)?;
let fingerprint = source_fingerprint(&bytes);
let format = source_format(&record.path)?;
match format.as_str() {
"gltf" | "glb" => build_gltf_manifest(record, format, fingerprint, &bytes),
@@ -582,19 +576,8 @@ fn fbx_matrix_bytes(matrix: &ufbx::Matrix) -> Vec<u8> {
.collect()
}
fn source_fingerprint(path: &str, bytes: &[u8]) -> Result<AnimationSourceFingerprint, String> {
let metadata = fs::metadata(path).map_err(|error| format!("could not stat {path}: {error}"))?;
let modified_unix_secs = metadata
.modified()
.ok()
.and_then(|time| time.duration_since(UNIX_EPOCH).ok())
.map(|duration| duration.as_secs())
.unwrap_or_default();
Ok(AnimationSourceFingerprint {
byte_len: metadata.len(),
modified_unix_secs,
content_hash: blake3::hash(bytes).to_hex().to_string(),
})
fn source_fingerprint(bytes: &[u8]) -> AnimationSourceFingerprint {
AnimationSourceFingerprint::from_bytes(bytes)
}
fn source_format(path: &str) -> Result<String, String> {
@@ -626,6 +609,7 @@ mod tests {
path: path.to_string_lossy().replace('\\', "/"),
label: "Animated Hero".into(),
kind_tag: "Model".into(),
source_fingerprint: None,
import_settings: ImportSettings::default(),
dependencies: Vec::new(),
}
@@ -754,6 +738,30 @@ mod tests {
fs::remove_dir_all(root).unwrap();
}
#[test]
fn legacy_mtime_metadata_does_not_rewrite_equivalent_animation_manifest() {
let root =
std::env::temp_dir().join(format!("blacksite-animation-legacy-{}", Uuid::new_v4()));
let path = write_animated_gltf(&root);
let manifest = build_animation_manifest(&fixture_record(&path)).unwrap();
let canonical =
ron::ser::to_string_pretty(&manifest, ron::ser::PrettyConfig::default()).unwrap();
let marker = format!("byte_len: {},", manifest.source.fingerprint.byte_len);
let legacy = canonical.replacen(
&marker,
&format!("{marker}\n modified_unix_secs: 123456,"),
1,
);
assert_ne!(legacy, canonical);
let artifact = root.join("legacy.animation.ron");
fs::write(&artifact, &legacy).unwrap();
assert!(!write_pretty_ron_if_changed(&artifact, &manifest).unwrap());
assert_eq!(fs::read_to_string(&artifact).unwrap(), legacy);
fs::remove_dir_all(root).unwrap();
}
#[test]
fn explicit_default_clip_is_stable_and_stale_ids_are_diagnostic() {
let root =
+134 -34
View File
@@ -2,9 +2,12 @@
use bevy::prelude::*;
use serde::{Deserialize, Serialize};
use shared::AssetSourceFingerprint;
use std::collections::{HashMap, HashSet};
use uuid::Uuid;
use crate::assets::fingerprint::{fingerprint_file, write_pretty_ron_if_changed};
/// Stable asset identity for dependency tracking and prefab references.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash)]
pub struct AssetId(pub Uuid);
@@ -93,6 +96,8 @@ pub struct AssetRecord {
pub path: String,
pub label: String,
pub kind_tag: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub source_fingerprint: Option<AssetSourceFingerprint>,
#[serde(default)]
pub import_settings: ImportSettings,
#[serde(default)]
@@ -122,9 +127,10 @@ fn sync_registry_from_browser(
return;
}
let mut existing: HashMap<String, AssetRecord> = registry
.records
.drain(..)
let previous_records = std::mem::take(&mut registry.records);
let mut existing: HashMap<String, AssetRecord> = previous_records
.iter()
.cloned()
.map(|record| (record.path.clone(), record))
.collect();
let current_paths = assets
@@ -146,12 +152,30 @@ fn sync_registry_from_browser(
seen_paths.insert(path.clone(), ());
let kind_tag = format!("{:?}", asset.kind);
let source_fingerprint = if imported_source_kind(&kind_tag) {
match fingerprint_file(&path) {
Ok(fingerprint) => Some(fingerprint),
Err(error) => {
warn!("Imported source fingerprint failed for {path}: {error}");
None
}
}
} else {
None
};
let mut record = if let Some(mut prior) = existing.remove(&path).or_else(|| {
take_uniquely_moved_model_record(&mut existing, &current_paths, &path, &kind_tag)
source_fingerprint.as_ref().and_then(|fingerprint| {
take_uniquely_moved_import_record(
&mut existing,
&current_paths,
&kind_tag,
fingerprint,
)
})
}) {
if prior.path != path {
info!(
"Asset registry preserved model identity {} across move {} -> {}",
"Asset registry preserved imported source identity {} across move {} -> {}",
prior.id.as_string(),
prior.path,
path
@@ -159,18 +183,26 @@ fn sync_registry_from_browser(
prior.path = path.clone();
}
prior.label = asset.label.clone();
prior.kind_tag = kind_tag;
prior.kind_tag = kind_tag.clone();
prior
} else {
AssetRecord {
id: AssetId::new(),
path: path.clone(),
label: asset.label.clone(),
kind_tag,
kind_tag: kind_tag.clone(),
source_fingerprint: None,
import_settings: ImportSettings::default(),
dependencies: Vec::new(),
}
};
if imported_source_kind(&kind_tag) {
if let Some(source_fingerprint) = source_fingerprint {
record.source_fingerprint = Some(source_fingerprint);
}
} else {
record.source_fingerprint = None;
}
if record.kind_tag == "Model" {
if let Err(error) = super::refresh_model_artifacts(&mut record) {
warn!(
@@ -183,7 +215,7 @@ fn sync_registry_from_browser(
next_records.push(record);
}
let changed = registry.records != next_records;
let changed = previous_records != next_records;
registry.records = next_records;
if changed {
registry.index_dirty = true;
@@ -198,26 +230,28 @@ fn sync_registry_from_browser(
}
}
fn take_uniquely_moved_model_record(
fn imported_source_kind(kind_tag: &str) -> bool {
matches!(kind_tag, "Model" | "Texture" | "AudioClip")
}
fn take_uniquely_moved_import_record(
existing: &mut HashMap<String, AssetRecord>,
current_paths: &HashSet<String>,
new_path: &str,
kind_tag: &str,
fingerprint: &AssetSourceFingerprint,
) -> Option<AssetRecord> {
if kind_tag != "Model" {
if !imported_source_kind(kind_tag) {
return None;
}
let bytes = std::fs::read(new_path).ok()?;
let content_hash = blake3::hash(&bytes).to_hex().to_string();
let candidates = existing
.iter()
.filter_map(|(old_path, record)| {
if current_paths.contains(old_path) || record.kind_tag != "Model" {
if current_paths.contains(old_path) || record.kind_tag != kind_tag {
return None;
}
let manifest_path = record.import_settings.animation_manifest_path.as_deref()?;
let manifest = super::animation::load_animation_manifest(manifest_path).ok()?;
(manifest.source.fingerprint.content_hash == content_hash).then(|| old_path.clone())
recorded_source_fingerprint(record)
.is_some_and(|prior| prior == *fingerprint)
.then(|| old_path.clone())
})
.collect::<Vec<_>>();
if candidates.len() != 1 {
@@ -226,6 +260,15 @@ fn take_uniquely_moved_model_record(
existing.remove(&candidates[0])
}
fn recorded_source_fingerprint(record: &AssetRecord) -> Option<AssetSourceFingerprint> {
record.source_fingerprint.clone().or_else(|| {
let manifest_path = record.import_settings.animation_manifest_path.as_deref()?;
super::animation::load_animation_manifest(manifest_path)
.ok()
.map(|manifest| manifest.source.fingerprint)
})
}
pub fn find_asset_by_path(registry: &AssetRegistry, path: &str) -> Option<AssetRecord> {
registry
.records
@@ -262,11 +305,16 @@ pub fn ensure_asset_record(
if let Some(record) = find_asset_by_path(registry, &path) {
return Ok(record);
}
let kind_tag = kind_tag.into();
let source_fingerprint = imported_source_kind(&kind_tag)
.then(|| fingerprint_file(&path).ok())
.flatten();
let record = AssetRecord {
id: AssetId::new(),
path,
label: label.into(),
kind_tag: kind_tag.into(),
kind_tag,
source_fingerprint,
import_settings: ImportSettings::default(),
dependencies: Vec::new(),
};
@@ -292,6 +340,9 @@ pub fn update_import_settings(
else {
return false;
};
if record.import_settings == settings {
return false;
}
record.import_settings = settings;
registry.index_dirty = true;
true
@@ -302,13 +353,7 @@ pub fn registry_index_path() -> &'static str {
}
pub fn save_registry(registry: &AssetRegistry) -> Result<(), String> {
let path = registry_index_path();
if let Some(parent) = std::path::Path::new(path).parent() {
std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
}
let text = ron::ser::to_string_pretty(&registry.records, ron::ser::PrettyConfig::default())
.map_err(|e| e.to_string())?;
std::fs::write(path, text).map_err(|e| e.to_string())
write_pretty_ron_if_changed(registry_index_path(), &registry.records).map(|_| ())
}
pub fn load_registry() -> AssetRegistry {
@@ -333,6 +378,63 @@ mod tests {
ANIMATION_MANIFEST_SCHEMA_VERSION,
};
#[test]
fn imported_source_policy_covers_model_texture_and_audio_only() {
for kind in ["Model", "Texture", "AudioClip"] {
assert!(imported_source_kind(kind), "missing imported kind {kind}");
}
for kind in ["Material", "Level", "Prefab", "PostProcessEffect"] {
assert!(
!imported_source_kind(kind),
"authored kind {kind} was hashed"
);
}
}
#[test]
fn legacy_registry_record_loads_without_forcing_a_new_identity() {
let source = r#"(
id: ("00000000-0000-0000-0000-000000000000"),
path: "assets/textures/legacy.png",
label: "Legacy",
kind_tag: "Texture",
)"#;
let record: AssetRecord = ron::from_str(source).unwrap();
assert_eq!(record.id, AssetId(Uuid::nil()));
assert!(record.source_fingerprint.is_none());
assert_eq!(record.import_settings, ImportSettings::default());
}
#[test]
fn content_match_preserves_every_imported_source_kind_across_move() {
let fingerprint = AssetSourceFingerprint::from_bytes(b"stable imported bytes");
for kind in ["Model", "Texture", "AudioClip"] {
let record = AssetRecord {
id: AssetId::new(),
path: format!("assets/old/{kind}"),
label: kind.into(),
kind_tag: kind.into(),
source_fingerprint: Some(fingerprint.clone()),
import_settings: ImportSettings::default(),
dependencies: Vec::new(),
};
let expected_id = record.id.clone();
let mut existing = HashMap::from([(record.path.clone(), record)]);
let moved = take_uniquely_moved_import_record(
&mut existing,
&HashSet::new(),
kind,
&fingerprint,
)
.expect("unique content identity should preserve the record");
assert_eq!(moved.id, expected_id);
assert!(existing.is_empty());
}
}
fn moved_model_fixture(bytes: &[u8]) -> (std::path::PathBuf, std::path::PathBuf, AssetRecord) {
let key = Uuid::new_v4();
let source_path = std::env::temp_dir().join(format!("blacksite-moved-model-{key}.glb"));
@@ -351,7 +453,6 @@ mod tests {
format: "glb".into(),
fingerprint: AnimationSourceFingerprint {
byte_len: bytes.len() as u64,
modified_unix_secs: 0,
content_hash: blake3::hash(bytes).to_hex().to_string(),
},
dependencies: Vec::new(),
@@ -371,6 +472,7 @@ mod tests {
path: old_path,
label: "Moved Model".into(),
kind_tag: "Model".into(),
source_fingerprint: None,
import_settings: ImportSettings {
animation_manifest_path: Some(manifest_path.to_string_lossy().into_owned()),
..Default::default()
@@ -385,12 +487,13 @@ mod tests {
let (source_path, manifest_path, record) = moved_model_fixture(b"stable model bytes");
let expected_id = record.id.clone();
let mut existing = HashMap::from([(record.path.clone(), record)]);
let fingerprint = fingerprint_file(&source_path).unwrap();
let moved = take_uniquely_moved_model_record(
let moved = take_uniquely_moved_import_record(
&mut existing,
&HashSet::new(),
&source_path.to_string_lossy(),
"Model",
&fingerprint,
)
.expect("unique moved model should retain its registry record");
@@ -406,13 +509,10 @@ mod tests {
let old_path = record.path.clone();
let mut existing = HashMap::from([(old_path.clone(), record)]);
let current_paths = HashSet::from([old_path]);
let fingerprint = fingerprint_file(&source_path).unwrap();
let moved = take_uniquely_moved_model_record(
&mut existing,
&current_paths,
&source_path.to_string_lossy(),
"Model",
);
let moved =
take_uniquely_moved_import_record(&mut existing, &current_paths, "Model", &fingerprint);
assert!(moved.is_none());
assert_eq!(existing.len(), 1);
+2 -1
View File
@@ -1548,6 +1548,7 @@ mod tests {
path: asset.path.clone().unwrap(),
label: asset.label.clone(),
kind_tag: "AudioClip".into(),
source_fingerprint: None,
import_settings: Default::default(),
dependencies: Vec::new(),
}],
@@ -1630,7 +1631,6 @@ mod tests {
format: "glb".into(),
fingerprint: shared::AnimationSourceFingerprint {
byte_len: 1,
modified_unix_secs: 0,
content_hash: "fixture".into(),
},
dependencies: Vec::new(),
@@ -1663,6 +1663,7 @@ mod tests {
path: "assets/models/robot.glb".into(),
label: "Robot".into(),
kind_tag: "Model".into(),
source_fingerprint: None,
import_settings: crate::asset_db::ImportSettings {
animation_manifest_path: Some(manifest_path.to_string_lossy().into_owned()),
default_animation_clip_id: Some(clip_id.clone()),
+114
View File
@@ -0,0 +1,114 @@
use std::fs;
use std::path::Path;
use serde::de::DeserializeOwned;
use serde::Serialize;
use shared::AssetSourceFingerprint;
pub(crate) fn fingerprint_file(path: impl AsRef<Path>) -> Result<AssetSourceFingerprint, String> {
let path = path.as_ref();
let bytes = fs::read(path)
.map_err(|error| format!("could not read imported source {}: {error}", path.display()))?;
Ok(AssetSourceFingerprint::from_bytes(&bytes))
}
/// Writes canonical pretty RON only when the parsed document changes semantically.
///
/// Equivalent existing bytes, including custom formatting and final-newline policy, stay intact.
pub(crate) fn write_pretty_ron_if_changed<T>(
path: impl AsRef<Path>,
value: &T,
) -> Result<bool, String>
where
T: DeserializeOwned + PartialEq + Serialize,
{
let path = path.as_ref();
if fs::read_to_string(path)
.ok()
.and_then(|text| ron::from_str::<T>(&text).ok())
.is_some_and(|existing| existing == *value)
{
return Ok(false);
}
let text = ron::ser::to_string_pretty(value, ron::ser::PrettyConfig::default())
.map_err(|error| format!("could not serialize RON: {error}"))?;
if fs::read(path).ok().as_deref() == Some(text.as_bytes()) {
return Ok(false);
}
if let Some(parent) = path.parent() {
fs::create_dir_all(parent)
.map_err(|error| format!("could not create {}: {error}", parent.display()))?;
}
fs::write(path, text)
.map_err(|error| format!("could not write {}: {error}", path.display()))?;
Ok(true)
}
#[cfg(test)]
mod tests {
use super::*;
use serde::Deserialize;
use std::fs::{File, FileTimes};
use std::time::{Duration, SystemTime};
use uuid::Uuid;
#[derive(Debug, Deserialize, PartialEq, Serialize)]
struct Fixture {
count: u32,
label: String,
}
fn fixture_path(name: &str) -> std::path::PathBuf {
std::env::temp_dir().join(format!(
"blacksite-fingerprint-{name}-{}.ron",
Uuid::new_v4()
))
}
#[test]
fn metadata_only_drift_does_not_change_content_identity() {
let path = fixture_path("mtime");
fs::write(&path, b"stable source bytes").unwrap();
let before = fingerprint_file(&path).unwrap();
File::options()
.write(true)
.open(&path)
.unwrap()
.set_times(
FileTimes::new().set_modified(SystemTime::now() + Duration::from_secs(86_400)),
)
.unwrap();
assert_eq!(fingerprint_file(&path).unwrap(), before);
fs::remove_file(path).unwrap();
}
#[test]
fn same_size_byte_change_updates_content_identity() {
let path = fixture_path("same-size");
fs::write(&path, b"source-a").unwrap();
let before = fingerprint_file(&path).unwrap();
fs::write(&path, b"source-b").unwrap();
let after = fingerprint_file(&path).unwrap();
assert_eq!(before.byte_len, after.byte_len);
assert_ne!(before.content_hash, after.content_hash);
fs::remove_file(path).unwrap();
}
#[test]
fn equivalent_ron_preserves_exact_existing_bytes() {
let path = fixture_path("semantic");
let existing = b"( label: \"stable\", count: 7, )\n\n";
fs::write(&path, existing).unwrap();
let value = Fixture {
count: 7,
label: "stable".into(),
};
assert!(!write_pretty_ron_if_changed(&path, &value).unwrap());
assert_eq!(fs::read(&path).unwrap(), existing);
fs::remove_file(path).unwrap();
}
}
+1
View File
@@ -3,6 +3,7 @@
pub mod animation;
pub mod asset_db;
mod catalog;
mod fingerprint;
mod import;
pub mod materials;
pub mod operators;
+3 -1
View File
@@ -228,7 +228,6 @@ mod tests {
format: "glb".into(),
fingerprint: AnimationSourceFingerprint {
byte_len: 1,
modified_unix_secs: 0,
content_hash: "fixture".into(),
},
dependencies: Vec::new(),
@@ -265,6 +264,7 @@ mod tests {
path: model_path.clone(),
label: "Operator Fixture".into(),
kind_tag: "Model".into(),
source_fingerprint: None,
import_settings: ImportSettings {
animation_manifest_path: Some(path.to_string_lossy().into_owned()),
..Default::default()
@@ -352,6 +352,7 @@ mod tests {
path: path.clone(),
label: "Impact".into(),
kind_tag: "AudioClip".into(),
source_fingerprint: None,
import_settings: Default::default(),
dependencies: Vec::new(),
}],
@@ -502,6 +503,7 @@ mod tests {
path: material_path.clone(),
label: "Concrete".into(),
kind_tag: "Material".into(),
source_fingerprint: None,
import_settings: Default::default(),
dependencies: Vec::new(),
}],
+61 -35
View File
@@ -2,7 +2,6 @@
use std::fs;
use std::path::Path;
use std::time::UNIX_EPOCH;
use bevy::gltf::GltfAssetLabel;
use bevy::prelude::*;
@@ -15,11 +14,13 @@ use crate::asset_db::{
AssetRecord, ImportSettings, MaterialImportPolicy, ModelHierarchyMode, ModelPlacementMode,
};
use shared::{
ComponentInstanceId, EditorAssetRef, MaterialRef, RendererMaterialSet, RendererMaterialSlot,
StaticMeshRenderer, StaticMeshRendererEntry,
AssetSourceFingerprint, ComponentInstanceId, EditorAssetRef, MaterialRef, RendererMaterialSet,
RendererMaterialSlot, StaticMeshRenderer, StaticMeshRendererEntry,
};
pub const STATIC_MESH_MANIFEST_SCHEMA: u32 = 3;
use crate::assets::fingerprint::{fingerprint_file, write_pretty_ron_if_changed};
pub const STATIC_MESH_MANIFEST_SCHEMA: u32 = 4;
pub const STATIC_MESH_ARTIFACT_DIR: &str = "assets/meshes/generated";
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
@@ -42,11 +43,7 @@ pub struct StaticMeshSource {
pub dependencies: Vec<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct StaticMeshSourceFingerprint {
pub byte_len: u64,
pub modified_unix_secs: u64,
}
pub type StaticMeshSourceFingerprint = AssetSourceFingerprint;
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct StaticMeshImportSnapshot {
@@ -134,16 +131,9 @@ pub fn refresh_static_mesh_artifact(
manifest.source.dependencies.dedup();
record.dependencies = manifest.source.dependencies.clone();
let text = ron::ser::to_string_pretty(&manifest, ron::ser::PrettyConfig::default())
.map_err(|err| format!("could not serialize static mesh manifest: {err}"))?;
if let Some(parent) = Path::new(&path).parent() {
fs::create_dir_all(parent)
.map_err(|err| format!("could not create {}: {err}", parent.display()))?;
}
let should_write = fs::read_to_string(&path).ok().as_deref() != Some(text.as_str());
if should_write {
fs::write(&path, text)
.map_err(|err| format!("could not write static mesh manifest {path}: {err}"))?;
if write_pretty_ron_if_changed(&path, &manifest)
.map_err(|error| format!("could not publish static mesh manifest {path}: {error}"))?
{
info!(
"Static mesh manifest refreshed: source={} artifact={} parts={}",
record.path,
@@ -287,7 +277,7 @@ fn part_effective_material_id(part: &StaticMeshPart) -> Option<String> {
fn build_static_mesh_manifest(record: &AssetRecord) -> Result<StaticMeshManifest, String> {
let format = source_format(&record.path)?;
let fingerprint = source_fingerprint(&record.path)?;
let fingerprint = fingerprint_file(&record.path)?;
let import = StaticMeshImportSnapshot {
scale: record.import_settings.scale,
generate_collider: record.import_settings.generate_collider,
@@ -631,20 +621,6 @@ fn source_format(path: &str) -> Result<String, String> {
.ok_or_else(|| format!("asset path `{path}` has no extension"))
}
fn source_fingerprint(path: &str) -> Result<StaticMeshSourceFingerprint, String> {
let metadata = fs::metadata(path).map_err(|err| format!("could not stat {path}: {err}"))?;
let modified_unix_secs = metadata
.modified()
.ok()
.and_then(|time| time.duration_since(UNIX_EPOCH).ok())
.map(|duration| duration.as_secs())
.unwrap_or_default();
Ok(StaticMeshSourceFingerprint {
byte_len: metadata.len(),
modified_unix_secs,
})
}
fn resolve_dependency(source_path: &str, uri: &str) -> String {
if uri.starts_with("data:") || uri.contains("://") {
return uri.to_string();
@@ -672,7 +648,7 @@ mod tests {
format: "glb".into(),
fingerprint: StaticMeshSourceFingerprint {
byte_len: 42,
modified_unix_secs: 10,
content_hash: "a".repeat(64),
},
dependencies: Vec::new(),
},
@@ -741,6 +717,55 @@ mod tests {
);
}
#[test]
fn schema_v3_manifest_without_hash_migrates_to_content_fingerprint() {
let root = std::env::temp_dir().join(format!(
"blacksite-static-mesh-legacy-{}",
uuid::Uuid::new_v4()
));
fs::create_dir_all(&root).unwrap();
let path = root.join("legacy.static_mesh.ron");
let expected = test_manifest();
let canonical =
ron::ser::to_string_pretty(&expected, ron::ser::PrettyConfig::default()).unwrap();
let legacy = canonical
.replacen("schema_version: 4", "schema_version: 3", 1)
.lines()
.filter(|line| !line.contains("content_hash:"))
.collect::<Vec<_>>()
.join("\n");
fs::write(&path, legacy).unwrap();
assert!(write_pretty_ron_if_changed(&path, &expected).unwrap());
assert_eq!(
load_static_mesh_manifest(&path.to_string_lossy()).unwrap(),
expected
);
fs::remove_dir_all(root).unwrap();
}
#[test]
fn equivalent_static_manifest_preserves_existing_formatting_and_newline() {
let root = std::env::temp_dir().join(format!(
"blacksite-static-mesh-semantic-{}",
uuid::Uuid::new_v4()
));
fs::create_dir_all(&root).unwrap();
let path = root.join("stable.static_mesh.ron");
let manifest = test_manifest();
let exact = format!(
"{}\n\n",
ron::ser::to_string_pretty(&manifest, ron::ser::PrettyConfig::default()).unwrap()
);
fs::write(&path, &exact).unwrap();
assert!(!write_pretty_ron_if_changed(&path, &manifest).unwrap());
assert_eq!(fs::read_to_string(&path).unwrap(), exact);
fs::remove_dir_all(root).unwrap();
}
#[test]
fn renderer_from_manifest_can_ignore_source_materials() {
let manifest = test_manifest();
@@ -785,6 +810,7 @@ mod tests {
path,
label: "Robot Expressive".into(),
kind_tag: "Model".into(),
source_fingerprint: None,
import_settings: ImportSettings::default(),
dependencies: Vec::new(),
};
@@ -884,7 +884,6 @@ mod tests {
format: "glb".into(),
fingerprint: AnimationSourceFingerprint {
byte_len: 42,
modified_unix_secs: 1,
content_hash: "hash".into(),
},
dependencies: Vec::new(),
-1
View File
@@ -1267,7 +1267,6 @@ mod tests {
format: "glb".into(),
fingerprint: AnimationSourceFingerprint {
byte_len: 1,
modified_unix_secs: 0,
content_hash: "fixture".into(),
},
dependencies: Vec::new(),
+225 -18
View File
@@ -9,12 +9,13 @@ use shared::{
animation_clip_source_index, animation_clip_sub_asset_id, animation_skeleton_source_index,
animation_skeleton_sub_asset_id,
brush_math::{validate_brush, BrushDiagnosticSeverity},
AnimationControllerDesc, AnimationDiagnosticSeverity, AnimationManifest, AudioListenerDesc,
AudioSourceDesc, BrushDesc, ColliderDesc, ColliderShapeDesc, EditorAssetRef, MaterialAsset,
MaterialDesc, MaterialInstanceAsset, MaterialOverride, ModelRef, PostProcessEffectAsset,
PostProcessVolumeDesc, PrefabInstance, PrefabRef, RendererMaterialSet, ShaderSchemaAsset,
SkinnedMeshRenderer, StaticMeshRenderer, TerrainDesc, ANIMATION_MANIFEST_SCHEMA_VERSION,
AUDIO_CLIP_SUB_ASSET_ID, COMPONENT_ANIMATION_CONTROLLER_DESC, COMPONENT_SKINNED_MESH_RENDERER,
AnimationControllerDesc, AnimationDiagnosticSeverity, AnimationManifest,
AssetSourceFingerprint, AudioListenerDesc, AudioSourceDesc, BrushDesc, ColliderDesc,
ColliderShapeDesc, EditorAssetRef, MaterialAsset, MaterialDesc, MaterialInstanceAsset,
MaterialOverride, ModelRef, PostProcessEffectAsset, PostProcessVolumeDesc, PrefabInstance,
PrefabRef, RendererMaterialSet, ShaderSchemaAsset, SkinnedMeshRenderer, StaticMeshRenderer,
TerrainDesc, ANIMATION_MANIFEST_SCHEMA_VERSION, AUDIO_CLIP_SUB_ASSET_ID,
COMPONENT_ANIMATION_CONTROLLER_DESC, COMPONENT_SKINNED_MESH_RENDERER,
NAVIGATION_GENERATED_ARTIFACT_DIRECTORY,
};
@@ -322,6 +323,8 @@ struct RegistryAssetRecord {
path: String,
kind_tag: String,
#[serde(default)]
source_fingerprint: Option<AssetSourceFingerprint>,
#[serde(default)]
import_settings: RegistryImportSettings,
#[serde(default)]
dependencies: Vec<String>,
@@ -482,10 +485,96 @@ fn validate_asset_registry(
repair: "Convert the clip to Ogg Vorbis, WAV, MP3, or FLAC and reimport it.".into(),
});
}
if matches!(record.kind_tag.as_str(), "Model" | "Texture" | "AudioClip") {
validate_content_fingerprint(
project_root,
report,
"assets/.index/registry.ron",
&record.path,
record.source_fingerprint.as_ref(),
"registry.source_fingerprint_missing",
"registry.source_fingerprint_stale",
"registered imported source",
);
}
}
animation_catalog
}
#[allow(clippy::too_many_arguments)]
fn validate_content_fingerprint(
project_root: &Path,
report: &mut ProjectValidationReport,
owner_path: &str,
source_path: &str,
fingerprint: Option<&AssetSourceFingerprint>,
missing_code: &str,
stale_code: &str,
source_label: &str,
) {
let Some(fingerprint) = fingerprint.filter(|fingerprint| fingerprint.is_complete()) else {
report.findings.push(ProjectValidationFinding {
severity: ValidationSeverity::Error,
code: missing_code.into(),
source_path: owner_path.into(),
owner_actor_id: None,
reference: Some(source_path.into()),
message: format!("{source_label} has no complete BLAKE3 content fingerprint"),
repair: "Refresh the asset registry or reimport the source with this editor version."
.into(),
});
return;
};
let Some(path) = resolve_reference(project_root, source_path) else {
return;
};
let Ok(metadata) = std::fs::metadata(&path) else {
return;
};
if metadata.len() != fingerprint.byte_len {
report.findings.push(ProjectValidationFinding {
severity: ValidationSeverity::Error,
code: stale_code.into(),
source_path: owner_path.into(),
owner_actor_id: None,
reference: Some(source_path.into()),
message: format!(
"{source_label} size changed from {} to {} bytes",
fingerprint.byte_len,
metadata.len()
),
repair: "Refresh or reimport the changed source before validation or packaging.".into(),
});
return;
}
match blake3_file_hash(&path) {
Ok(content_hash) if content_hash != fingerprint.content_hash => {
report.findings.push(ProjectValidationFinding {
severity: ValidationSeverity::Error,
code: stale_code.into(),
source_path: owner_path.into(),
owner_actor_id: None,
reference: Some(source_path.into()),
message: format!(
"{source_label} content changed even though its byte length is unchanged"
),
repair: "Refresh or reimport the changed source before validation or packaging."
.into(),
});
}
Ok(_) => {}
Err(error) => report.findings.push(ProjectValidationFinding {
severity: ValidationSeverity::Error,
code: stale_code.into(),
source_path: owner_path.into(),
owner_actor_id: None,
reference: Some(source_path.into()),
message: format!("could not hash {source_label}: {error}"),
repair: "Restore readable source content and rerun validation.".into(),
}),
}
}
fn reference_is_runtime_package_asset(reference: &str) -> bool {
let relative = Path::new(reference.split('#').next().unwrap_or(reference));
if relative.is_absolute()
@@ -709,10 +798,12 @@ struct StaticMeshManifestView {
struct StaticMeshSourceView {
path: String,
#[serde(default)]
fingerprint: AssetSourceFingerprint,
#[serde(default)]
dependencies: Vec<String>,
}
const STATIC_MESH_MANIFEST_SCHEMA_VERSION: u32 = 3;
const STATIC_MESH_MANIFEST_SCHEMA_VERSION: u32 = 4;
fn validate_static_mesh_manifests(project_root: &Path, report: &mut ProjectValidationReport) {
for path in ron_files(
@@ -754,6 +845,16 @@ fn validate_static_mesh_manifests(project_root: &Path, report: &mut ProjectValid
"model",
&manifest.source.path,
);
validate_content_fingerprint(
project_root,
report,
&source,
&manifest.source.path,
Some(&manifest.source.fingerprint),
"static_mesh.manifest_fingerprint_missing",
"static_mesh.manifest_stale",
"static mesh source",
);
for dependency in manifest.source.dependencies {
add_reference(
project_root,
@@ -975,12 +1076,7 @@ fn validate_animation_manifest_contract(
}
let fingerprint = &manifest.source.fingerprint;
let hash_is_present = fingerprint.content_hash.len() == 64
&& fingerprint
.content_hash
.bytes()
.all(|byte| byte.is_ascii_hexdigit());
if fingerprint.byte_len == 0 || fingerprint.modified_unix_secs == 0 || !hash_is_present {
if fingerprint.byte_len == 0 || !fingerprint.is_complete() {
report.findings.push(ProjectValidationFinding {
severity: ValidationSeverity::Error,
code: "animation.manifest_fingerprint_missing".into(),
@@ -3071,7 +3167,7 @@ mod tests {
}
#[test]
fn static_mesh_manifest_schema_v3_is_current() {
fn static_mesh_manifest_schema_v4_is_current() {
let root = fixture_root();
let source_path = "assets/models/static.glb";
std::fs::create_dir_all(root.join("assets/models")).unwrap();
@@ -3081,7 +3177,8 @@ mod tests {
std::fs::write(
artifact_dir.join("static-id.static_mesh.ron"),
format!(
"(schema_version:{STATIC_MESH_MANIFEST_SCHEMA_VERSION},asset_id:\"static-id\",source:(path:\"{source_path}\",dependencies:[]),warnings:[])"
"(schema_version:{STATIC_MESH_MANIFEST_SCHEMA_VERSION},asset_id:\"static-id\",source:(path:\"{source_path}\",fingerprint:(byte_len:5,content_hash:\"{}\"),dependencies:[]),warnings:[])",
blake3::hash(b"model").to_hex()
),
)
.unwrap();
@@ -3095,6 +3192,70 @@ mod tests {
std::fs::remove_dir_all(root).unwrap();
}
#[test]
fn same_size_static_mesh_source_change_invalidates_content_hash() {
let root = fixture_root();
let source_path = "assets/models/static.glb";
std::fs::create_dir_all(root.join("assets/models")).unwrap();
std::fs::write(root.join(source_path), b"model").unwrap();
let fingerprint = AssetSourceFingerprint::from_bytes(b"model");
let artifact = root.join("assets/meshes/generated/static-id.static_mesh.ron");
std::fs::create_dir_all(artifact.parent().unwrap()).unwrap();
std::fs::write(
&artifact,
format!(
"(schema_version:{STATIC_MESH_MANIFEST_SCHEMA_VERSION},asset_id:\"static-id\",source:(path:\"{source_path}\",fingerprint:(byte_len:{},content_hash:\"{}\"),dependencies:[]),warnings:[])",
fingerprint.byte_len, fingerprint.content_hash
),
)
.unwrap();
std::fs::write(root.join(source_path), b"modem").unwrap();
let report = validate_project(&root);
let finding = report
.findings
.iter()
.find(|finding| finding.code == "static_mesh.manifest_stale")
.expect("same-size model edit must stale the static mesh manifest");
assert!(finding.message.contains("byte length is unchanged"));
assert!(finding.repair.contains("Refresh") || finding.repair.contains("reimport"));
std::fs::remove_dir_all(root).unwrap();
}
#[test]
fn registry_detects_same_size_changes_for_all_imported_source_kinds() {
for (kind, relative) in [
("Model", "assets/models/source.glb"),
("Texture", "assets/textures/source.png"),
("AudioClip", "assets/audio/source.ogg"),
] {
let root = fixture_root();
let path = root.join(relative);
std::fs::create_dir_all(path.parent().unwrap()).unwrap();
std::fs::write(&path, b"source-a").unwrap();
let fingerprint = AssetSourceFingerprint::from_bytes(b"source-a");
std::fs::write(
root.join("assets/.index/registry.ron"),
format!(
"[(id:(\"00000000-0000-0000-0000-000000000001\"),path:\"{relative}\",kind_tag:\"{kind}\",source_fingerprint:Some((byte_len:{},content_hash:\"{}\")),dependencies:[])]",
fingerprint.byte_len, fingerprint.content_hash
),
)
.unwrap();
std::fs::write(&path, b"source-b").unwrap();
let report = validate_project(&root);
assert!(report.findings.iter().any(|finding| {
finding.code == "registry.source_fingerprint_stale"
&& finding.reference.as_deref() == Some(relative)
&& finding.message.contains("byte length is unchanged")
}));
std::fs::remove_dir_all(root).unwrap();
}
}
fn write_manifest(root: &Path, version: u32) {
std::fs::write(
root.join("assets/project.ron"),
@@ -3128,7 +3289,6 @@ mod tests {
format: source_format.into(),
fingerprint: AnimationSourceFingerprint {
byte_len: 5,
modified_unix_secs: 1,
content_hash: blake3::hash(b"model").to_hex().to_string(),
},
dependencies: Vec::new(),
@@ -3188,10 +3348,12 @@ mod tests {
let manifest = animation_manifest_path
.map(|path| format!("Some({path:?})"))
.unwrap_or_else(|| "None".into());
let fingerprint = AssetSourceFingerprint::from_bytes(b"model");
std::fs::write(
root.join("assets/.index/registry.ron"),
format!(
"[(id:(\"{ANIMATION_ASSET_ID}\"),path:\"{source_path}\",kind_tag:\"Model\",import_settings:(static_mesh_manifest_path:None,animation_manifest_path:{manifest}),dependencies:[])]"
"[(id:(\"{ANIMATION_ASSET_ID}\"),path:\"{source_path}\",kind_tag:\"Model\",source_fingerprint:Some((byte_len:{},content_hash:\"{}\")),import_settings:(static_mesh_manifest_path:None,animation_manifest_path:{manifest}),dependencies:[])]",
fingerprint.byte_len, fingerprint.content_hash
),
)
.unwrap();
@@ -3205,10 +3367,12 @@ mod tests {
let source = root.join(source_path);
std::fs::create_dir_all(source.parent().unwrap()).unwrap();
std::fs::write(source, b"model").unwrap();
let fingerprint = AssetSourceFingerprint::from_bytes(b"model");
std::fs::write(
root.join("assets/.index/registry.ron"),
format!(
"[(id:(\"{ANIMATION_ASSET_ID}\"),path:\"{source_path}\",kind_tag:\"Model\",import_settings:(static_mesh_manifest_path:None,animation_manifest_path:Some(\"{ANIMATION_MANIFEST_PATH}\"),default_animation_clip_id:Some(\"{default_clip_id}\")),dependencies:[])]"
"[(id:(\"{ANIMATION_ASSET_ID}\"),path:\"{source_path}\",kind_tag:\"Model\",source_fingerprint:Some((byte_len:{},content_hash:\"{}\")),import_settings:(static_mesh_manifest_path:None,animation_manifest_path:Some(\"{ANIMATION_MANIFEST_PATH}\"),default_animation_clip_id:Some(\"{default_clip_id}\")),dependencies:[])]",
fingerprint.byte_len, fingerprint.content_hash
),
)
.unwrap();
@@ -3632,6 +3796,49 @@ mod tests {
std::fs::remove_dir_all(root).unwrap();
}
#[test]
fn project_validation_preserves_registry_and_generated_artifact_bytes() {
let root = fixture_root();
let source_path = "assets/models/hero.glb";
let manifest = animation_fixture_manifest(source_path, "glb", "rig-signature", true);
write_animation_source_and_registry(&root, source_path, Some(ANIMATION_MANIFEST_PATH));
write_animation_manifest(&root, &manifest);
write_animation_scene(&root, &animation_fixture_controller(&manifest));
let static_path = root.join("assets/meshes/generated/model-id.static_mesh.ron");
std::fs::create_dir_all(static_path.parent().unwrap()).unwrap();
std::fs::write(
&static_path,
format!(
"( schema_version: {STATIC_MESH_MANIFEST_SCHEMA_VERSION}, asset_id: \"model-id\", source: ( path: \"{source_path}\", fingerprint: ( byte_len: {}, content_hash: \"{}\", ), dependencies: [], ), warnings: [], )\n\n",
manifest.source.fingerprint.byte_len,
manifest.source.fingerprint.content_hash
),
)
.unwrap();
let paths = [
root.join("assets/.index/registry.ron"),
root.join(ANIMATION_MANIFEST_PATH),
static_path,
];
let before = paths
.iter()
.map(std::fs::read)
.collect::<Result<Vec<_>, _>>()
.unwrap();
let _ = validate_project(&root);
let _ = validate_project(&root);
let after = paths
.iter()
.map(std::fs::read)
.collect::<Result<Vec<_>, _>>()
.unwrap();
assert_eq!(after, before);
std::fs::remove_dir_all(root).unwrap();
}
#[test]
fn missing_animation_manifest_is_reported_globally_and_on_the_actor_property() {
let root = fixture_root();
+2 -7
View File
@@ -266,13 +266,8 @@ pub struct AnimationManifestSource {
pub dependencies: Vec<String>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct AnimationSourceFingerprint {
pub byte_len: u64,
pub modified_unix_secs: u64,
/// BLAKE3 hash of the source file bytes.
pub content_hash: String,
}
/// Backward-compatible name for the shared imported-source fingerprint contract.
pub type AnimationSourceFingerprint = crate::AssetSourceFingerprint;
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct AnimationSkeletonRecord {
+50
View File
@@ -0,0 +1,50 @@
use serde::{Deserialize, Serialize};
/// Stable identity for the exact bytes of an imported project source.
///
/// Filesystem timestamps are deliberately excluded: Git and LFS do not preserve checkout mtimes,
/// so they cannot participate in a portable authored-data contract.
#[derive(Debug, Clone, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct AssetSourceFingerprint {
pub byte_len: u64,
#[serde(default)]
pub content_hash: String,
}
impl AssetSourceFingerprint {
pub fn from_bytes(bytes: &[u8]) -> Self {
Self {
byte_len: bytes.len() as u64,
content_hash: blake3::hash(bytes).to_hex().to_string(),
}
}
pub fn is_complete(&self) -> bool {
self.content_hash.len() == 64
&& self
.content_hash
.bytes()
.all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn exact_bytes_define_source_identity() {
let first = AssetSourceFingerprint::from_bytes(b"asset-a");
let same = AssetSourceFingerprint::from_bytes(b"asset-a");
let same_size_change = AssetSourceFingerprint::from_bytes(b"asset-b");
assert_eq!(first, same);
assert_ne!(first, same_size_change);
assert_eq!(first.byte_len, same_size_change.byte_len);
assert!(first.is_complete());
let mut noncanonical = first;
noncanonical.content_hash.make_ascii_uppercase();
assert!(!noncanonical.is_complete());
}
}
+2
View File
@@ -6,6 +6,7 @@
mod actor;
mod animation;
mod asset_fingerprint;
pub mod brush_math;
mod components;
mod hydration;
@@ -18,6 +19,7 @@ mod rendering_profile_asset;
pub use actor::{infer_actor_kind, validate_actor, ActorValidationError};
pub use animation::*;
pub use asset_fingerprint::AssetSourceFingerprint;
pub use components::*;
pub use hydration::{
cascade_config_from_rendering, flush_level_object_hydration,