feat: complete M2 content workspace and inspector

This commit is contained in:
Rbanh committed 2026-07-17 23:40:49 -04:00
1 parent 931f561e7f
commit cf6eaba534
438 files changed
+59749 -19043

No files matched your search

+12
View File
@@ -0,0 +1,12 @@
# Content pipeline subtree rules
- This crate owns UI-independent asset, import, catalog, transaction, watcher, and processing
behavior.
- Preserve transaction atomicity, byte-identical rollback, stable identity, reference repair,
derived-artifact ownership, managed-path protection, watcher suppression, and deterministic
restart behavior.
- Prefer focused tests here over heavy editor tests.
- Never depend on the editor crate.
- Keep GPU and rendering requirements out of headless paths.
- A defect in one content operation may justify one bounded sibling-operation invariant audit, not
an unlimited repository audit.
+24
View File
@@ -0,0 +1,24 @@
[package]
name = "content_pipeline"
version.workspace = true
edition.workspace = true
license.workspace = true
description = "UI-independent Blacksite content discovery, registry, and transaction pipeline"
[dependencies]
blake3 = "1"
bevy.workspace = true
bevy_ufbx.workspace = true
basis-universal = "0.3.1"
gltf = { version = "1.4", features = ["extras"] }
image = "0.25.10"
notify = "6.1"
ron = "0.8"
serde.workspace = true
serde_json = "1"
shared.workspace = true
walkdir = "2.5"
uuid = { version = "1", features = ["v4"] }
ufbx = "0.9"
[dev-dependencies]
+912
View File
@@ -0,0 +1,912 @@
//! Generated animation artifacts for imported model sources.
use std::collections::BTreeSet;
use std::fs;
use std::path::Path;
use serde::Deserialize;
use shared::{
animation_clip_sub_asset_id, animation_skeleton_sub_asset_id, AnimationClipRecord,
AnimationDiagnosticSeverity, AnimationEventDesc, AnimationImportDiagnostic, AnimationManifest,
AnimationManifestSource, AnimationSkeletonRecord, AnimationSkeletonSignature,
AnimationSourceFingerprint, ANIMATION_ARTIFACT_DIR, ANIMATION_MANIFEST_SCHEMA_VERSION,
};
use crate::fingerprint::write_pretty_ron_if_changed;
use shared::AssetRecord;
pub fn animation_manifest_path(asset_id: &str) -> String {
format!("{ANIMATION_ARTIFACT_DIR}/{asset_id}.animation.ron")
}
pub fn refresh_animation_artifact(record: &mut AssetRecord) -> Result<AnimationManifest, String> {
let (manifest, path) = plan_animation_artifact(record)?;
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,
path,
manifest.skeletons.len(),
manifest.clips.len(),
manifest.runtime_supported
);
}
Ok(manifest)
}
pub fn plan_animation_artifact(
record: &mut AssetRecord,
) -> Result<(AnimationManifest, String), String> {
let mut manifest = build_animation_manifest(record)?;
manifest.source.dependencies.sort();
manifest.source.dependencies.dedup();
let path = animation_manifest_path(&record.id.as_string());
record.model_import_mut().animation_manifest_path = Some(path.clone());
record
.dependencies
.extend(manifest.source.dependencies.iter().cloned());
record.dependencies.sort();
record.dependencies.dedup();
Ok((manifest, path))
}
pub fn load_animation_manifest(path: &str) -> Result<AnimationManifest, String> {
let text =
fs::read_to_string(path).map_err(|error| format!("could not read {path}: {error}"))?;
ron::from_str(&text).map_err(|error| format!("could not parse {path}: {error}"))
}
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(&bytes);
let format = source_format(&record.path)?;
match format.as_str() {
"gltf" | "glb" => build_gltf_manifest(record, format, fingerprint, &bytes),
"fbx" => build_fbx_manifest(record, format, fingerprint, &bytes),
_ => Err(format!("unsupported animation source format `{format}`")),
}
}
#[derive(Debug, Clone)]
struct SkeletonCandidate {
compatible_nodes: BTreeSet<usize>,
signature: AnimationSkeletonSignature,
}
fn build_gltf_manifest(
record: &AssetRecord,
format: String,
fingerprint: AnimationSourceFingerprint,
bytes: &[u8],
) -> Result<AnimationManifest, String> {
let gltf = gltf::Gltf::from_slice(bytes)
.map_err(|error| format!("could not parse glTF {}: {error}", record.path))?;
let base = Path::new(&record.path).parent();
let buffers = gltf::import_buffers(&gltf.document, base, gltf.blob.clone())
.map_err(|error| format!("could not load glTF buffers for {}: {error}", record.path))?;
let mut dependencies = gltf
.document
.buffers()
.filter_map(|buffer| match buffer.source() {
gltf::buffer::Source::Uri(uri) if !uri.starts_with("data:") => {
Some(resolve_dependency(&record.path, uri))
}
_ => None,
})
.collect::<Vec<_>>();
dependencies.sort();
dependencies.dedup();
let node_identity_names = gltf
.document
.nodes()
.map(|node| bevy_node_segment(node.name(), node.index()))
.collect::<Vec<_>>();
let readable_node_names = gltf
.document
.nodes()
.map(|node| normalized_node_segment(node.name(), node.index()))
.collect::<Vec<_>>();
let mut parents = vec![None; node_identity_names.len()];
for node in gltf.document.nodes() {
for child in node.children() {
parents[child.index()] = Some(node.index());
}
}
let mut skeletons = Vec::new();
let mut candidates = Vec::new();
for skin in gltf.document.skins() {
let source_index = skin.index();
let label = skin
.name()
.filter(|name| !name.trim().is_empty())
.map(str::to_string)
.unwrap_or_else(|| format!("Skeleton {source_index}"));
let joint_indices = skin.joints().map(|joint| joint.index()).collect::<Vec<_>>();
let joint_identity_paths = joint_indices
.iter()
.map(|index| node_path_segments(*index, &node_identity_names, &parents))
.collect::<Vec<_>>();
let joint_paths = joint_indices
.iter()
.map(|index| node_path(*index, &readable_node_names, &parents))
.collect::<Vec<_>>();
let bind_poses = skin
.reader(|buffer| Some(buffers[buffer.index()].0.as_slice()))
.read_inverse_bind_matrices()
.map(|matrices| matrices.map(gltf_matrix_bytes).collect::<Vec<_>>())
.unwrap_or_else(|| vec![identity_matrix_bytes(); joint_paths.len()]);
let signature = skeleton_signature(&joint_identity_paths, &bind_poses);
let mut compatible_nodes = joint_indices.into_iter().collect::<BTreeSet<_>>();
if let Some(root) = skin.skeleton() {
compatible_nodes.insert(root.index());
}
candidates.push(SkeletonCandidate {
compatible_nodes,
signature: signature.clone(),
});
skeletons.push(AnimationSkeletonRecord {
id: animation_skeleton_sub_asset_id(source_index, &label),
label,
source_index,
signature,
joint_paths,
});
}
let mut diagnostics = Vec::new();
let mut clips = Vec::new();
let mut animation_roots = BTreeSet::new();
for animation in gltf.document.animations() {
let source_index = animation.index();
let label = animation
.name()
.filter(|name| !name.trim().is_empty())
.map(str::to_string)
.unwrap_or_else(|| format!("Animation {source_index}"));
let mut duration_seconds = 0.0_f32;
let mut target_nodes = BTreeSet::new();
for channel in animation.channels() {
let target_index = channel.target().node().index();
target_nodes.insert(target_index);
animation_roots.insert(top_level_node(target_index, &parents));
if let Some(inputs) = channel
.reader(|buffer| Some(buffers[buffer.index()].0.as_slice()))
.read_inputs()
{
for input in inputs {
if input.is_finite() {
duration_seconds = duration_seconds.max(input);
}
}
}
}
let target_skeleton_signature = matching_skeleton_signature(&target_nodes, &candidates);
if !candidates.is_empty() && target_skeleton_signature.is_none() {
diagnostics.push(AnimationImportDiagnostic {
severity: AnimationDiagnosticSeverity::Warning,
code: "animation.clip_skeleton_unresolved".into(),
message: format!(
"clip `{label}` does not target a uniquely identifiable imported skeleton"
),
repair: "Export the clip with channels targeting one skeleton, or split unrelated rigs into separate glTF assets.".into(),
});
}
let events = gltf_animation_events(&animation, duration_seconds, &label, &mut diagnostics);
clips.push(AnimationClipRecord {
id: animation_clip_sub_asset_id(source_index, &label),
label,
source_index,
duration_seconds,
target_skeleton_signature,
events,
});
}
let default_animation_clip_id = record.model_import().default_animation_clip_id.clone();
validate_default_animation_clip(
default_animation_clip_id.as_deref(),
&clips,
&mut diagnostics,
);
let runtime_supported = animation_roots.len() <= 1;
if !runtime_supported {
let roots = animation_roots
.iter()
.map(|index| format!("`{}` (node {index})", node_identity_names[*index]))
.collect::<Vec<_>>()
.join(", ");
diagnostics.push(AnimationImportDiagnostic {
severity: AnimationDiagnosticSeverity::Error,
code: "animation.multiple_roots_unsupported".into(),
message: format!(
"animation channels target {} distinct top-level roots ({roots}); Bevy requires a separate AnimationPlayer for each root",
animation_roots.len()
),
repair: "Split the source into one animated rig per glTF asset, or export every clip under one common top-level root, then reimport.".into(),
});
}
Ok(AnimationManifest {
schema_version: ANIMATION_MANIFEST_SCHEMA_VERSION,
asset_id: record.id.as_string(),
label: record.label.clone(),
default_animation_clip_id,
source: AnimationManifestSource {
path: record.path.clone(),
format,
fingerprint,
dependencies,
},
runtime_supported,
skeletons,
clips,
diagnostics,
})
}
fn build_fbx_manifest(
record: &AssetRecord,
format: String,
fingerprint: AnimationSourceFingerprint,
bytes: &[u8],
) -> Result<AnimationManifest, String> {
let scene = ufbx::load_memory(
bytes,
ufbx::LoadOpts {
target_unit_meters: 1.0,
target_axes: ufbx::CoordinateAxes::right_handed_y_up(),
..Default::default()
},
)
.map_err(|error| format!("could not parse FBX {}: {error:?}", record.path))?;
let mut skeletons = Vec::new();
for (source_index, skin) in scene.skin_deformers.as_ref().iter().enumerate() {
let label = if skin.element.name.is_empty() {
format!("Skeleton {source_index}")
} else {
skin.element.name.to_string()
};
let mut joint_identity_paths = Vec::new();
let mut joint_paths = Vec::new();
let mut bind_poses = Vec::new();
for cluster in skin.clusters.as_ref() {
let Some(bone) = cluster.bone_node.as_ref() else {
continue;
};
let segments = fbx_node_path_segments(bone.as_ref());
joint_paths.push(segments.join("/"));
joint_identity_paths.push(segments);
bind_poses.push(fbx_matrix_bytes(&cluster.bind_to_world));
}
let signature = skeleton_signature(&joint_identity_paths, &bind_poses);
skeletons.push(AnimationSkeletonRecord {
id: animation_skeleton_sub_asset_id(source_index, &label),
label,
source_index,
signature,
joint_paths,
});
}
let fallback_signature = (skeletons.len() == 1).then(|| skeletons[0].signature.clone());
let clips = scene
.anim_stacks
.as_ref()
.iter()
.enumerate()
.map(|(source_index, stack)| {
let label = if stack.element.name.is_empty() {
format!("Animation {source_index}")
} else {
stack.element.name.to_string()
};
AnimationClipRecord {
id: animation_clip_sub_asset_id(source_index, &label),
label,
source_index,
duration_seconds: (stack.time_end - stack.time_begin).max(0.0) as f32,
target_skeleton_signature: fallback_signature.clone(),
events: Vec::new(),
}
})
.collect::<Vec<_>>();
let (runtime_supported, mut diagnostics) = fbx_runtime_support(
scene.anim_stacks.as_ref().len(),
scene.skin_deformers.as_ref().len(),
);
let default_animation_clip_id = record.model_import().default_animation_clip_id.clone();
validate_default_animation_clip(
default_animation_clip_id.as_deref(),
&clips,
&mut diagnostics,
);
Ok(AnimationManifest {
schema_version: ANIMATION_MANIFEST_SCHEMA_VERSION,
asset_id: record.id.as_string(),
label: record.label.clone(),
default_animation_clip_id,
source: AnimationManifestSource {
path: record.path.clone(),
format,
fingerprint,
dependencies: Vec::new(),
},
runtime_supported,
skeletons,
clips,
diagnostics,
})
}
fn validate_default_animation_clip(
default_clip_id: Option<&str>,
clips: &[AnimationClipRecord],
diagnostics: &mut Vec<AnimationImportDiagnostic>,
) {
let Some(default_clip_id) = default_clip_id.filter(|id| !id.trim().is_empty()) else {
return;
};
if clips.iter().any(|clip| clip.id == default_clip_id) {
return;
}
diagnostics.push(AnimationImportDiagnostic {
severity: AnimationDiagnosticSeverity::Error,
code: "animation.default_clip_missing".into(),
message: format!(
"configured default animation clip `{default_clip_id}` no longer exists in the imported source"
),
repair: "Choose an existing Default animation in Model Import Settings, or select Imported rest pose, then reimport.".into(),
});
}
fn fbx_runtime_support(
animation_count: usize,
skin_count: usize,
) -> (bool, Vec<AnimationImportDiagnostic>) {
let mut diagnostics = Vec::new();
if animation_count > 0 || skin_count > 0 {
diagnostics.push(AnimationImportDiagnostic {
severity: AnimationDiagnosticSeverity::Error,
code: "animation.fbx_runtime_unsupported".into(),
message: format!(
"FBX contains {animation_count} animation stack(s) and {skin_count} skin deformer(s), but Blacksite's current FBX loader cannot build a runtime skeleton or clips"
),
repair: "Export the animated source as glTF 2.0 (.glb or .gltf). Keep FBX only for static mesh import until hierarchy, SkinnedMesh, and AnimationClip conversion are implemented.".into(),
});
}
(false, diagnostics)
}
#[derive(Debug, Default, Deserialize)]
struct GltfAnimationExtras {
#[serde(default)]
blacksite_events: Vec<GltfAnimationEvent>,
}
#[derive(Debug, Deserialize)]
struct GltfAnimationEvent {
id: String,
time_seconds: f32,
#[serde(default)]
payload: Option<String>,
}
fn gltf_animation_events(
animation: &gltf::Animation<'_>,
duration_seconds: f32,
clip_label: &str,
diagnostics: &mut Vec<AnimationImportDiagnostic>,
) -> Vec<AnimationEventDesc> {
let Some(raw) = animation.extras().as_ref() else {
return Vec::new();
};
let extras = match serde_json::from_str::<GltfAnimationExtras>(raw.get()) {
Ok(extras) => extras,
Err(error) => {
diagnostics.push(AnimationImportDiagnostic {
severity: AnimationDiagnosticSeverity::Warning,
code: "animation.events_invalid".into(),
message: format!("clip `{clip_label}` has invalid animation event metadata: {error}"),
repair: "Use an animation extras object with `blacksite_events` entries containing `id`, `time_seconds`, and optional string `payload`.".into(),
});
return Vec::new();
}
};
let mut events = Vec::new();
for event in extras.blacksite_events {
let valid_time = event.time_seconds.is_finite()
&& event.time_seconds >= 0.0
&& event.time_seconds <= duration_seconds;
if event.id.trim().is_empty() || !valid_time {
diagnostics.push(AnimationImportDiagnostic {
severity: AnimationDiagnosticSeverity::Warning,
code: "animation.event_out_of_range".into(),
message: format!(
"clip `{clip_label}` contains an event with an empty ID or time outside 0..={duration_seconds:.3}s"
),
repair: "Give every event a stable non-empty ID and place it within the imported clip duration.".into(),
});
continue;
}
events.push(AnimationEventDesc {
id: event.id,
time_seconds: event.time_seconds,
payload: event.payload,
});
}
events.sort_by(|left, right| {
left.time_seconds
.total_cmp(&right.time_seconds)
.then(left.id.cmp(&right.id))
.then(left.payload.cmp(&right.payload))
});
events
}
fn matching_skeleton_signature(
target_nodes: &BTreeSet<usize>,
candidates: &[SkeletonCandidate],
) -> Option<AnimationSkeletonSignature> {
let scored = candidates
.iter()
.map(|candidate| {
(
candidate
.compatible_nodes
.intersection(target_nodes)
.count(),
candidate,
)
})
.filter(|(score, _)| *score > 0)
.collect::<Vec<_>>();
let best_score = scored.iter().map(|(score, _)| *score).max()?;
let mut best = scored
.into_iter()
.filter(|(score, _)| *score == best_score)
.map(|(_, candidate)| candidate);
let candidate = best.next()?;
best.all(|other| other.signature == candidate.signature)
.then(|| candidate.signature.clone())
}
fn node_path(index: usize, names: &[String], parents: &[Option<usize>]) -> String {
node_path_segments(index, names, parents).join("/")
}
fn node_path_segments(index: usize, names: &[String], parents: &[Option<usize>]) -> Vec<String> {
let mut segments = Vec::new();
let mut current = Some(index);
while let Some(node_index) = current {
segments.push(names[node_index].clone());
current = parents[node_index];
}
segments.reverse();
segments
}
fn top_level_node(index: usize, parents: &[Option<usize>]) -> usize {
let mut current = index;
while let Some(parent) = parents[current] {
current = parent;
}
current
}
fn bevy_node_segment(name: Option<&str>, index: usize) -> String {
name.map(str::to_string)
.unwrap_or_else(|| format!("GltfNode{index}"))
}
fn normalized_node_segment(name: Option<&str>, index: usize) -> String {
name.map(str::trim)
.filter(|name| !name.is_empty())
.map(|name| name.replace(['/', '\\'], "_"))
.unwrap_or_else(|| format!("Node{index}"))
}
fn fbx_node_path_segments(node: &ufbx::Node) -> Vec<String> {
let mut segments = Vec::new();
let mut current = Some(node);
while let Some(node) = current {
segments.push(normalized_node_segment(
(!node.element.name.is_empty()).then(|| node.element.name.as_ref()),
node.element.element_id as usize,
));
current = node.parent.as_ref().map(|parent| parent.as_ref());
}
segments.reverse();
segments
}
fn skeleton_signature(
joint_path_segments: &[Vec<String>],
bind_pose_bytes: &[Vec<u8>],
) -> AnimationSkeletonSignature {
let mut hasher = blake3::Hasher::new();
hasher.update(b"blacksite-animation-skeleton-v2\0");
hasher.update(&(joint_path_segments.len() as u64).to_le_bytes());
for path in joint_path_segments {
hasher.update(&(path.len() as u64).to_le_bytes());
for segment in path {
let bytes = segment.as_bytes();
hasher.update(&(bytes.len() as u64).to_le_bytes());
hasher.update(bytes);
}
}
hasher.update(&(bind_pose_bytes.len() as u64).to_le_bytes());
for bytes in bind_pose_bytes {
hasher.update(&(bytes.len() as u64).to_le_bytes());
hasher.update(bytes);
}
AnimationSkeletonSignature::new(hasher.finalize().to_hex().to_string())
}
fn gltf_matrix_bytes(matrix: [[f32; 4]; 4]) -> Vec<u8> {
matrix
.into_iter()
.flatten()
.flat_map(f32::to_le_bytes)
.collect()
}
fn identity_matrix_bytes() -> Vec<u8> {
gltf_matrix_bytes([
[1.0, 0.0, 0.0, 0.0],
[0.0, 1.0, 0.0, 0.0],
[0.0, 0.0, 1.0, 0.0],
[0.0, 0.0, 0.0, 1.0],
])
}
fn fbx_matrix_bytes(matrix: &ufbx::Matrix) -> Vec<u8> {
[
matrix.m00, matrix.m10, matrix.m20, matrix.m01, matrix.m11, matrix.m21, matrix.m02,
matrix.m12, matrix.m22, matrix.m03, matrix.m13, matrix.m23,
]
.into_iter()
.flat_map(f64::to_le_bytes)
.collect()
}
fn source_fingerprint(bytes: &[u8]) -> AnimationSourceFingerprint {
AnimationSourceFingerprint::from_bytes(bytes)
}
fn source_format(path: &str) -> Result<String, String> {
Path::new(path)
.extension()
.and_then(|extension| extension.to_str())
.map(|extension| extension.to_ascii_lowercase())
.ok_or_else(|| format!("asset path `{path}` has no extension"))
}
fn resolve_dependency(source_path: &str, uri: &str) -> String {
Path::new(source_path)
.parent()
.unwrap_or_else(|| Path::new(""))
.join(uri)
.to_string_lossy()
.replace('\\', "/")
}
#[cfg(test)]
mod tests {
use super::*;
use shared::{AssetId, AssetImportSettings, ImportSettings};
use uuid::Uuid;
fn fixture_record(path: &Path) -> AssetRecord {
AssetRecord {
id: AssetId(Uuid::nil()),
path: path.to_string_lossy().replace('\\', "/"),
label: "Animated Hero".into(),
kind: shared::AssetKind::Model,
source_fingerprint: None,
import_settings: AssetImportSettings::Model(ImportSettings::default()),
dependencies: Vec::new(),
}
}
fn write_animated_gltf(root: &Path) -> std::path::PathBuf {
fs::create_dir_all(root).unwrap();
let mut buffer = Vec::new();
for value in [0.0_f32, 1.25] {
buffer.extend_from_slice(&value.to_le_bytes());
}
for value in [0.0_f32, 0.0, 0.0, 1.0, 0.0, 0.38268343, 0.0, 0.9238795] {
buffer.extend_from_slice(&value.to_le_bytes());
}
fs::write(root.join("animated.bin"), buffer).unwrap();
let gltf = r#"{
"asset":{"version":"2.0"},
"scene":0,
"scenes":[{"nodes":[0]}],
"nodes":[{"name":"Armature","children":[1]},{"name":"Hip"}],
"skins":[{"name":"Hero Rig","skeleton":0,"joints":[1]}],
"buffers":[{"uri":"animated.bin","byteLength":40}],
"bufferViews":[
{"buffer":0,"byteOffset":0,"byteLength":8},
{"buffer":0,"byteOffset":8,"byteLength":32}
],
"accessors":[
{"bufferView":0,"componentType":5126,"count":2,"type":"SCALAR","min":[0.0],"max":[1.25]},
{"bufferView":1,"componentType":5126,"count":2,"type":"VEC4"}
],
"animations":[{
"name":"Idle Loop",
"samplers":[{"input":0,"output":1,"interpolation":"LINEAR"}],
"channels":[{"sampler":0,"target":{"node":1,"path":"rotation"}}],
"extras":{"blacksite_events":[{"id":"footstep.left","time_seconds":0.5,"payload":"stone"}]}
}]
}"#;
let path = root.join("animated.gltf");
fs::write(&path, gltf).unwrap();
path
}
fn write_multi_root_animated_gltf(root: &Path) -> std::path::PathBuf {
fs::create_dir_all(root).unwrap();
let mut buffer = Vec::new();
for value in [0.0_f32, 1.0] {
buffer.extend_from_slice(&value.to_le_bytes());
}
for value in [0.0_f32, 0.0, 0.0, 1.0, 0.0, 0.38268343, 0.0, 0.9238795] {
buffer.extend_from_slice(&value.to_le_bytes());
}
fs::write(root.join("multi-root.bin"), buffer).unwrap();
let gltf = r#"{
"asset":{"version":"2.0"},
"scene":0,
"scenes":[{"nodes":[0,2]}],
"nodes":[
{"name":"Character A","children":[1]},
{"name":"Joint A"},
{"name":"Character B","children":[3]},
{"name":"Joint B"}
],
"buffers":[{"uri":"multi-root.bin","byteLength":40}],
"bufferViews":[
{"buffer":0,"byteOffset":0,"byteLength":8},
{"buffer":0,"byteOffset":8,"byteLength":32}
],
"accessors":[
{"bufferView":0,"componentType":5126,"count":2,"type":"SCALAR","min":[0.0],"max":[1.0]},
{"bufferView":1,"componentType":5126,"count":2,"type":"VEC4"}
],
"animations":[{
"name":"Two Players Required",
"samplers":[
{"input":0,"output":1,"interpolation":"LINEAR"},
{"input":0,"output":1,"interpolation":"LINEAR"}
],
"channels":[
{"sampler":0,"target":{"node":1,"path":"rotation"}},
{"sampler":1,"target":{"node":3,"path":"rotation"}}
]
}]
}"#;
let path = root.join("multi-root.gltf");
fs::write(&path, gltf).unwrap();
path
}
#[test]
fn animation_manifest_path_uses_registry_uuid() {
assert_eq!(
animation_manifest_path("abc"),
"assets/animations/generated/abc.animation.ron"
);
}
#[test]
fn gltf_extraction_is_deterministic_and_preserves_duration_events_and_signature() {
let root = std::env::temp_dir().join(format!("blacksite-animation-{}", Uuid::new_v4()));
let path = write_animated_gltf(&root);
let record = fixture_record(&path);
let first = build_animation_manifest(&record).unwrap();
let second = build_animation_manifest(&record).unwrap();
assert_eq!(first, second);
assert_eq!(first.schema_version, ANIMATION_MANIFEST_SCHEMA_VERSION);
assert!(first.default_animation_clip_id.is_none());
assert!(first.runtime_supported);
assert_eq!(first.source.dependencies.len(), 1);
assert_eq!(first.skeletons.len(), 1);
assert_eq!(first.clips.len(), 1);
assert_eq!(first.skeletons[0].id, "animation:skeleton:0:hero_rig");
assert!(!first.skeletons[0].signature.is_empty());
assert_eq!(first.clips[0].id, "animation:clip:0:idle_loop");
assert_eq!(first.clips[0].duration_seconds, 1.25);
assert_eq!(
first.clips[0].target_skeleton_signature,
Some(first.skeletons[0].signature.clone())
);
assert_eq!(first.clips[0].events.len(), 1);
assert_eq!(first.clips[0].events[0].id, "footstep.left");
assert_eq!(first.clips[0].events[0].time_seconds, 0.5);
assert_eq!(first.diagnostics, Vec::new());
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 =
std::env::temp_dir().join(format!("blacksite-animation-default-{}", Uuid::new_v4()));
let path = write_animated_gltf(&root);
let mut record = fixture_record(&path);
record.model_import_mut().default_animation_clip_id =
Some("animation:clip:0:idle_loop".into());
let manifest = build_animation_manifest(&record).unwrap();
assert_eq!(
manifest.default_animation_clip_id.as_deref(),
Some("animation:clip:0:idle_loop")
);
assert!(manifest.diagnostics.is_empty());
record.model_import_mut().default_animation_clip_id =
Some("animation:clip:99:removed".into());
let stale = build_animation_manifest(&record).unwrap();
assert!(stale.diagnostics.iter().any(|diagnostic| {
diagnostic.code == "animation.default_clip_missing"
&& diagnostic.severity == AnimationDiagnosticSeverity::Error
}));
fs::remove_dir_all(root).unwrap();
}
#[test]
fn exact_signature_changes_with_joint_path_or_bind_pose() {
let identity = identity_matrix_bytes();
let first = skeleton_signature(
&[vec!["Armature".into(), "Hip".into()]],
std::slice::from_ref(&identity),
);
let renamed = skeleton_signature(
&[vec!["Armature".into(), "Pelvis".into()]],
std::slice::from_ref(&identity),
);
let mut changed_pose = identity;
changed_pose[0] ^= 1;
let rebound = skeleton_signature(&[vec!["Armature".into(), "Hip".into()]], &[changed_pose]);
assert_ne!(first, renamed);
assert_ne!(first, rebound);
}
#[test]
fn exact_signature_preserves_bevy_node_bytes_and_segment_boundaries() {
let identity = identity_matrix_bytes();
let slash_in_name = vec![vec!["Armature".into(), "Hip/Joint".into()]];
let slash_as_boundary = vec![vec!["Armature/Hip".into(), "Joint".into()]];
assert_eq!(slash_in_name[0].join("/"), slash_as_boundary[0].join("/"));
assert_ne!(
skeleton_signature(&slash_in_name, std::slice::from_ref(&identity)),
skeleton_signature(&slash_as_boundary, std::slice::from_ref(&identity))
);
let backslash = vec![vec!["Armature".into(), "Hip\\Joint".into()]];
assert_eq!(
normalized_node_segment(Some("Hip/Joint"), 1),
normalized_node_segment(Some("Hip\\Joint"), 1)
);
assert_ne!(
skeleton_signature(&slash_in_name, std::slice::from_ref(&identity)),
skeleton_signature(&backslash, std::slice::from_ref(&identity))
);
assert_eq!(bevy_node_segment(Some(" /Joint "), 7), " /Joint ");
assert_eq!(bevy_node_segment(None, 7), "GltfNode7");
}
#[test]
fn gltf_with_multiple_animation_roots_is_runtime_unsupported() {
let root =
std::env::temp_dir().join(format!("blacksite-animation-multi-root-{}", Uuid::new_v4()));
let path = write_multi_root_animated_gltf(&root);
let manifest = build_animation_manifest(&fixture_record(&path)).unwrap();
assert!(!manifest.runtime_supported);
let diagnostic = manifest
.diagnostics
.iter()
.find(|diagnostic| diagnostic.code == "animation.multiple_roots_unsupported")
.expect("multi-root glTF should include an actionable blocking diagnostic");
assert_eq!(diagnostic.severity, AnimationDiagnosticSeverity::Error);
assert!(diagnostic.message.contains("2 distinct top-level roots"));
assert!(diagnostic.repair.contains("one common top-level root"));
fs::remove_dir_all(root).unwrap();
}
#[test]
fn animated_or_skinned_fbx_is_runtime_unsupported_with_repair_guidance() {
let (supported, diagnostics) = fbx_runtime_support(2, 1);
assert!(!supported);
assert_eq!(diagnostics.len(), 1);
assert_eq!(diagnostics[0].severity, AnimationDiagnosticSeverity::Error);
assert_eq!(diagnostics[0].code, "animation.fbx_runtime_unsupported");
assert!(diagnostics[0].repair.contains("glTF 2.0"));
let (supported, diagnostics) = fbx_runtime_support(0, 0);
assert!(!supported);
assert!(diagnostics.is_empty());
}
#[test]
fn committed_robot_fixture_exposes_a_skin_and_multiple_named_states() {
let path =
Path::new(env!("CARGO_MANIFEST_DIR")).join("../../assets/models/robot_expressive.glb");
let manifest = build_animation_manifest(&fixture_record(&path)).unwrap();
assert!(manifest.runtime_supported);
assert_eq!(manifest.skeletons.len(), 2);
assert_eq!(manifest.skeletons[0].id, "animation:skeleton:0:skeleton_0");
assert_eq!(manifest.skeletons[1].id, "animation:skeleton:1:skeleton_1");
assert!(manifest
.skeletons
.iter()
.all(|skeleton| skeleton.joint_paths.len() == 43));
let signature = &manifest.skeletons[0].signature;
assert!(manifest
.skeletons
.iter()
.all(|skeleton| &skeleton.signature == signature));
assert_eq!(manifest.clips.len(), 14);
for expected in ["Idle", "Walking", "Running", "Jump", "Wave"] {
assert!(
manifest.clips.iter().any(|clip| clip.label == expected),
"missing expected fixture clip {expected}"
);
}
assert!(manifest
.clips
.iter()
.all(|clip| clip.duration_seconds.is_finite() && clip.duration_seconds > 0.0));
assert!(manifest
.clips
.iter()
.all(|clip| { clip.target_skeleton_signature.as_ref() == Some(signature) }));
assert!(manifest.diagnostics.is_empty());
}
}
+111
View File
@@ -0,0 +1,111 @@
use std::fs;
use std::path::Path;
use serde::de::DeserializeOwned;
use serde::Serialize;
use shared::AssetSourceFingerprint;
pub 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 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();
}
}
File diff suppressed because it is too large. Load diff
+868
View File
@@ -0,0 +1,868 @@
//! UI-independent project content discovery and publication.
use serde::{Deserialize, Serialize};
use shared::{
AssetKind, AssetRecord, AssetRegistryDocument, AssetSourceFingerprint, ComponentInstanceId,
MaterialImportPolicy, ModelMaterialSelection, ModelMaterialSlotSelection,
RuntimeContentCatalog,
};
use std::collections::{HashMap, HashSet};
use std::ffi::OsStr;
use std::fs;
use std::path::{Component, Path, PathBuf};
use walkdir::{DirEntry, WalkDir};
pub mod animation;
mod fingerprint;
mod import;
mod pbr_grouping;
pub mod static_mesh;
mod texture;
mod transaction;
mod trash;
mod watcher;
pub use fingerprint::*;
pub use import::*;
pub use pbr_grouping::*;
pub use texture::*;
pub use transaction::*;
pub use trash::*;
pub use watcher::*;
pub const ASSETS_DIRECTORY: &str = "assets";
pub const REGISTRY_PATH: &str = "assets/.index/registry.ron";
pub const RUNTIME_CATALOG_PATH: &str = "assets/content.catalog.ron";
const MANAGED_DIRECTORIES: &[&str] = &[".index", ".thumbnails", ".trash", ".import-cache"];
const MANAGED_PATH_PREFIXES: &[&str] = &[
"meshes/generated",
"animations/generated",
"navigation/generated",
];
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ContentDiagnostic {
pub path: String,
pub message: String,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
pub struct ProcessingReport {
pub discovered: usize,
pub added: usize,
pub moved: usize,
pub removed: usize,
pub changed: bool,
pub diagnostics: Vec<ContentDiagnostic>,
}
#[derive(Debug, Clone)]
pub struct ProcessedContent {
pub registry: AssetRegistryDocument,
pub runtime_catalog: RuntimeContentCatalog,
pub report: ProcessingReport,
}
/// One imported file whose current bytes match more than one missing registry record. Automatic
/// reconciliation must stop so the editor can ask which stable identity actually moved.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ExternalMoveConflict {
pub new_path: String,
pub candidate_paths: Vec<String>,
pub kind: AssetKind,
pub fingerprint: AssetSourceFingerprint,
}
pub fn find_ambiguous_external_moves(
project_root: &Path,
previous: &AssetRegistryDocument,
) -> Result<Vec<ExternalMoveConflict>, String> {
let assets_root = project_root.join(ASSETS_DIRECTORY);
if !assets_root.is_dir() {
return Err(format!(
"project has no assets directory: {}",
assets_root.display()
));
}
let mut discovered = Vec::new();
for entry in WalkDir::new(&assets_root)
.follow_links(false)
.into_iter()
.filter_entry(|entry| should_descend(entry, &assets_root))
{
let entry = entry.map_err(|error| format!("content scan failed: {error}"))?;
if !entry.file_type().is_file() {
continue;
}
let kind = classify_asset_file(entry.path());
if !kind.is_imported_source() {
continue;
}
let relative = entry
.path()
.strip_prefix(project_root)
.map_err(|error| format!("content path escaped project: {error}"))?;
let path = relative.to_string_lossy().replace('\\', "/");
let bytes = fs::read(entry.path())
.map_err(|error| format!("could not fingerprint {path}: {error}"))?;
discovered.push((path, kind, AssetSourceFingerprint::from_bytes(&bytes)));
}
let current_paths = discovered
.iter()
.map(|(path, _, _)| path.clone())
.collect::<HashSet<_>>();
let previous_paths = previous
.records
.iter()
.map(|record| record.path.as_str())
.collect::<HashSet<_>>();
let mut conflicts = Vec::new();
for (new_path, kind, fingerprint) in discovered {
if previous_paths.contains(new_path.as_str()) {
continue;
}
let mut candidate_paths = previous
.records
.iter()
.filter(|record| {
!current_paths.contains(record.path.as_str())
&& record.kind == kind
&& record.source_fingerprint.as_ref() == Some(&fingerprint)
})
.map(|record| record.path.clone())
.collect::<Vec<_>>();
candidate_paths.sort();
candidate_paths.dedup();
if candidate_paths.len() > 1 {
conflicts.push(ExternalMoveConflict {
new_path,
candidate_paths,
kind,
fingerprint,
});
}
}
conflicts.sort_by(|left, right| left.new_path.cmp(&right.new_path));
Ok(conflicts)
}
pub fn is_managed_path(relative_to_assets: &Path) -> bool {
let managed_directory = relative_to_assets
.components()
.next()
.is_some_and(|component| {
let Component::Normal(name) = component else {
return false;
};
MANAGED_DIRECTORIES
.iter()
.any(|managed| name == OsStr::new(managed))
});
let normalized = relative_to_assets.to_string_lossy().replace('\\', "/");
managed_directory
|| MANAGED_PATH_PREFIXES.iter().any(|prefix| {
normalized == *prefix
|| normalized
.strip_prefix(prefix)
.is_some_and(|suffix| suffix.starts_with('/'))
})
}
/// Validates a user-selected project content path without consulting the filesystem.
pub fn validate_asset_path(path: &Path) -> Result<(), String> {
if path.is_absolute() {
return Err("content paths must be project-relative".into());
}
let mut components = path.components();
if components.next() != Some(Component::Normal(OsStr::new(ASSETS_DIRECTORY))) {
return Err("content paths must be located under `assets/`".into());
}
let remainder = components.collect::<PathBuf>();
if remainder.as_os_str().is_empty() {
return Ok(());
}
if remainder.components().any(|component| {
matches!(
component,
Component::ParentDir | Component::RootDir | Component::Prefix(_)
)
}) {
return Err("content paths cannot escape `assets/`".into());
}
if is_managed_path(&remainder) {
return Err("engine-managed content directories cannot be edited".into());
}
Ok(())
}
/// Classifies an asset by its filename/schema suffix rather than its containing folder.
pub fn classify_asset(path: &Path) -> AssetKind {
let name = path
.file_name()
.and_then(OsStr::to_str)
.unwrap_or_default()
.to_ascii_lowercase();
if name.ends_with(".material-instance.ron") {
return AssetKind::MaterialInstance;
}
if name.ends_with(".material.ron") {
return AssetKind::Material;
}
if name.ends_with(".scn.ron") {
return AssetKind::Level;
}
if name.ends_with(".prefab.ron") {
return AssetKind::Prefab;
}
if name.ends_with(".post-process.ron") {
return AssetKind::PostProcessEffect;
}
if name.ends_with(".rendering-profile.ron") {
return AssetKind::RenderingProfile;
}
if name.ends_with(".shader-schema.ron") {
return AssetKind::ShaderSchema;
}
match path
.extension()
.and_then(OsStr::to_str)
.unwrap_or_default()
.to_ascii_lowercase()
.as_str()
{
"gltf" | "glb" | "fbx" => AssetKind::Model,
"png" | "jpg" | "jpeg" | "webp" | "ktx2" | "dds" | "tga" | "exr" | "hdr" => {
AssetKind::Texture
}
"ogg" | "oga" | "spx" | "wav" | "mp3" | "flac" => AssetKind::AudioClip,
"mat" | "material" => AssetKind::Material,
_ => AssetKind::Unknown,
}
}
/// Adds schema-based classification for authored RON assets whose filename is user-controlled.
pub fn classify_asset_file(path: &Path) -> AssetKind {
let path_kind = classify_asset(path);
if path_kind != AssetKind::Unknown && !path.to_string_lossy().ends_with(".scn.ron") {
return path_kind;
}
if path.extension().and_then(OsStr::to_str) != Some("ron") {
return path_kind;
}
let Ok(source) = fs::read_to_string(path) else {
return path_kind;
};
if ron::from_str::<shared::MaterialInstanceAsset>(&source).is_ok() {
return AssetKind::MaterialInstance;
}
if ron::from_str::<shared::MaterialAsset>(&source).is_ok() {
return AssetKind::Material;
}
if ron::from_str::<shared::ShaderSchemaAsset>(&source).is_ok() {
return AssetKind::ShaderSchema;
}
if ron::from_str::<shared::RenderingProfileAsset>(&source).is_ok() {
return AssetKind::RenderingProfile;
}
if ron::from_str::<shared::PostProcessEffectAsset>(&source).is_ok() {
return AssetKind::PostProcessEffect;
}
path_kind
}
fn should_descend(entry: &DirEntry, assets_root: &Path) -> bool {
if entry.file_type().is_symlink() {
return false;
}
entry
.path()
.strip_prefix(assets_root)
.ok()
.is_none_or(|relative| !is_managed_path(relative))
}
pub fn scan_project(
project_root: &Path,
previous: &AssetRegistryDocument,
) -> Result<ProcessedContent, String> {
let assets_root = project_root.join(ASSETS_DIRECTORY);
if !assets_root.is_dir() {
return Err(format!(
"project has no assets directory: {}",
assets_root.display()
));
}
let mut discovered = Vec::new();
let mut diagnostics = Vec::new();
let previous_kinds = previous
.records
.iter()
.map(|record| (record.path.as_str(), record.kind))
.collect::<HashMap<_, _>>();
for entry in WalkDir::new(&assets_root)
.follow_links(false)
.into_iter()
.filter_entry(|entry| should_descend(entry, &assets_root))
{
let entry = entry.map_err(|error| format!("content scan failed: {error}"))?;
if !entry.file_type().is_file() {
continue;
}
let relative = entry
.path()
.strip_prefix(project_root)
.map_err(|error| format!("content path escaped project: {error}"))?;
let path = relative.to_string_lossy().replace('\\', "/");
let mut kind = classify_asset_file(entry.path());
if matches!(kind, AssetKind::Level | AssetKind::Unknown) {
kind = previous_kinds.get(path.as_str()).copied().unwrap_or(kind);
}
if kind == AssetKind::Unknown {
continue;
}
let fingerprint = if kind.is_imported_source() {
match fs::read(entry.path()) {
Ok(bytes) => Some(AssetSourceFingerprint::from_bytes(&bytes)),
Err(error) => {
diagnostics.push(ContentDiagnostic {
path: path.clone(),
message: format!("could not fingerprint imported source: {error}"),
});
None
}
}
} else {
None
};
discovered.push((path, kind, fingerprint));
}
let mut by_path = previous
.records
.iter()
.cloned()
.map(|record| (record.path.clone(), record))
.collect::<HashMap<_, _>>();
let current_paths = discovered
.iter()
.map(|(path, _, _)| path.clone())
.collect::<HashSet<_>>();
let mut records = Vec::with_capacity(discovered.len());
let mut report = ProcessingReport {
discovered: discovered.len(),
diagnostics,
..Default::default()
};
for (path, kind, fingerprint) in discovered {
let label = Path::new(&path)
.file_stem()
.and_then(OsStr::to_str)
.unwrap_or("Asset")
.to_string();
let mut record = by_path.remove(&path);
if record.is_none() {
if let Some(fingerprint) = fingerprint.as_ref() {
let mut candidates = by_path
.iter()
.filter(|(old_path, record)| {
!current_paths.contains(*old_path)
&& record.kind == kind
&& record.source_fingerprint.as_ref() == Some(fingerprint)
})
.map(|(old_path, _)| old_path.clone())
.collect::<Vec<_>>();
candidates.sort();
match candidates.as_slice() {
[candidate] => record = by_path.remove(candidate),
[] => {}
_ => {
return Err(format!(
"ambiguous external move for {path}: source fingerprint matches {}; resolve the stable identity in the editor Content Browser before refreshing or running headless processing",
candidates.join(", ")
));
}
}
}
}
if let Some(existing) = record.as_mut() {
if existing.path != path {
report.moved += 1;
}
existing.path = path;
existing.label = label;
existing.kind = kind;
existing.source_fingerprint = fingerprint;
} else {
report.added += 1;
record = Some(AssetRecord {
id: shared::AssetId::new(),
path,
label,
kind,
source_fingerprint: fingerprint,
import_settings: shared::AssetImportSettings::for_kind(kind),
dependencies: Vec::new(),
});
}
let mut record = record.expect("record is initialized");
migrate_legacy_model_material_policy(project_root, &mut record, &mut report.diagnostics);
records.push(record);
}
report.removed = by_path.len();
records.sort_by(|left, right| left.path.cmp(&right.path));
let registry = AssetRegistryDocument {
schema_version: shared::ASSET_REGISTRY_SCHEMA_VERSION,
defaults: previous.defaults.clone(),
records,
};
report.changed = &registry != previous;
let runtime_catalog = RuntimeContentCatalog::from(&registry);
Ok(ProcessedContent {
registry,
runtime_catalog,
report,
})
}
#[derive(Deserialize)]
struct ModelManifestSlotView {
#[serde(default)]
parts: Vec<ModelManifestPartView>,
}
#[derive(Deserialize)]
struct ModelManifestPartView {
#[serde(default)]
id: String,
#[serde(default)]
material_id: Option<String>,
#[serde(default)]
material_label: Option<String>,
}
fn migrate_legacy_model_material_policy(
project_root: &Path,
record: &mut AssetRecord,
diagnostics: &mut Vec<ContentDiagnostic>,
) {
if record.kind != AssetKind::Model {
return;
}
if record.model_import().material_policy != MaterialImportPolicy::AuthoringOverride {
return;
}
let Some(manifest_path) = record.model_import().static_mesh_manifest_path.as_deref() else {
diagnostics.push(ContentDiagnostic {
path: record.path.clone(),
message: "legacy Authoring Override needs a regenerated model manifest before per-slot migration"
.into(),
});
return;
};
let path = project_root.join(manifest_path);
let manifest = fs::read_to_string(&path)
.map_err(|error| format!("could not read {}: {error}", path.display()))
.and_then(|source| {
ron::from_str::<ModelManifestSlotView>(&source)
.map_err(|error| format!("could not parse {}: {error}", path.display()))
});
let manifest = match manifest {
Ok(manifest) => manifest,
Err(message) => {
diagnostics.push(ContentDiagnostic {
path: record.path.clone(),
message,
});
return;
}
};
let mut migrated = record.model_import().material_slots.clone();
for part in manifest.parts {
if part.material_id.is_none() && part.material_label.is_none() {
continue;
}
if part.id.trim().is_empty() {
diagnostics.push(ContentDiagnostic {
path: record.path.clone(),
message: "legacy material policy cannot migrate a model part with no stable ID; regenerate its manifest in the editor"
.into(),
});
return;
}
let slot_id = ComponentInstanceId::new(format!("slot:{}", part.id));
if !migrated
.iter()
.any(|selection| selection.slot_id == slot_id)
{
migrated.push(ModelMaterialSlotSelection {
slot_id,
selection: ModelMaterialSelection::Default,
});
}
}
migrated.sort_by(|left, right| left.slot_id.0.cmp(&right.slot_id.0));
record.model_import_mut().material_slots = migrated;
record.model_import_mut().material_policy = MaterialImportPolicy::SourceMaterials;
}
pub fn serialize_registry(document: &AssetRegistryDocument) -> Result<Vec<u8>, String> {
ron::ser::to_string_pretty(document, ron::ser::PrettyConfig::default())
.map(|source| source.into_bytes())
.map_err(|error| format!("could not serialize asset registry: {error}"))
}
pub fn serialize_runtime_catalog(catalog: &RuntimeContentCatalog) -> Result<Vec<u8>, String> {
ron::ser::to_string_pretty(catalog, ron::ser::PrettyConfig::default())
.map(|source| source.into_bytes())
.map_err(|error| format!("could not serialize runtime catalog: {error}"))
}
/// Publishes the editor registry and stripped runtime catalog as one rollback-capable pair.
pub fn publish_content_documents(
project_root: &Path,
document: &AssetRegistryDocument,
) -> Result<(), String> {
let runtime = RuntimeContentCatalog::from(document);
publish_content_documents_with_catalog(project_root, document, &runtime)
}
pub fn publish_content_documents_with_catalog(
project_root: &Path,
document: &AssetRegistryDocument,
runtime: &RuntimeContentCatalog,
) -> Result<(), String> {
let registry_path = project_root.join(REGISTRY_PATH);
let runtime_path = project_root.join(RUNTIME_CATALOG_PATH);
let original_registry = fs::read(&registry_path).ok();
let original_runtime = fs::read(&runtime_path).ok();
let registry_bytes = serialize_registry(document)?;
let runtime_bytes = serialize_runtime_catalog(runtime)?;
if let Err(error) = write_if_changed(&registry_path, &registry_bytes)
.and_then(|_| write_if_changed(&runtime_path, &runtime_bytes))
{
restore_published_file(&registry_path, original_registry.as_deref());
restore_published_file(&runtime_path, original_runtime.as_deref());
return Err(format!("content catalog publication rolled back: {error}"));
}
Ok(())
}
fn restore_published_file(path: &Path, bytes: Option<&[u8]>) {
if let Some(bytes) = bytes {
let _ = fs::write(path, bytes);
} else {
let _ = fs::remove_file(path);
}
}
pub fn write_if_changed(path: &Path, bytes: &[u8]) -> Result<bool, String> {
if fs::read(path).ok().as_deref() == Some(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()))?;
}
let temporary = path.with_extension("tmp");
fs::write(&temporary, bytes)
.map_err(|error| format!("could not stage {}: {error}", path.display()))?;
fs::rename(&temporary, path)
.map_err(|error| format!("could not publish {}: {error}", path.display()))?;
Ok(true)
}
#[derive(Debug, Clone)]
pub struct PlannedModelArtifacts {
pub record: shared::AssetRecord,
pub static_manifest: static_mesh::StaticMeshManifest,
pub static_path: std::path::PathBuf,
pub static_bytes: Vec<u8>,
pub animation_path: std::path::PathBuf,
pub animation_bytes: Vec<u8>,
}
pub fn plan_model_artifacts(record: &shared::AssetRecord) -> Result<PlannedModelArtifacts, String> {
plan_model_artifacts_at(std::path::Path::new("."), record)
}
pub fn plan_model_artifacts_at(
project_root: &std::path::Path,
record: &shared::AssetRecord,
) -> Result<PlannedModelArtifacts, String> {
let source_path = record.path.clone();
let mut planned_record = record.clone();
planned_record.path = project_root
.join(&source_path)
.to_string_lossy()
.into_owned();
let (static_manifest, static_path) =
static_mesh::plan_static_mesh_artifact(&mut planned_record)
.map_err(|error| format!("static mesh processor failed: {error}"))?;
let (mut animation_manifest, animation_path) =
animation::plan_animation_artifact(&mut planned_record)
.map_err(|error| format!("animation processor failed: {error}"))?;
let mut static_manifest = static_manifest;
static_manifest.source.path.clone_from(&source_path);
animation_manifest.source.path.clone_from(&source_path);
for dependency in &mut static_manifest.source.dependencies {
*dependency = project_catalog_path(project_root, dependency);
}
for dependency in &mut animation_manifest.source.dependencies {
*dependency = project_catalog_path(project_root, dependency);
}
planned_record.path = source_path;
planned_record.dependencies = static_manifest.source.dependencies.clone();
planned_record
.dependencies
.extend(animation_manifest.source.dependencies.iter().cloned());
planned_record.dependencies.sort();
planned_record.dependencies.dedup();
let pretty = ron::ser::PrettyConfig::default();
let static_bytes = ron::ser::to_string_pretty(&static_manifest, pretty.clone())
.map(|source| format!("{source}\n").into_bytes())
.map_err(|error| format!("could not serialize static mesh artifact: {error}"))?;
let animation_bytes = ron::ser::to_string_pretty(&animation_manifest, pretty)
.map(|source| format!("{source}\n").into_bytes())
.map_err(|error| format!("could not serialize animation artifact: {error}"))?;
Ok(PlannedModelArtifacts {
record: planned_record,
static_manifest,
static_path: project_root.join(static_path),
static_bytes,
animation_path: project_root.join(animation_path),
animation_bytes,
})
}
fn project_catalog_path(project_root: &std::path::Path, path: &str) -> String {
let path = std::path::Path::new(path);
let relative = path.strip_prefix(project_root).unwrap_or(path);
relative.to_string_lossy().replace('\\', "/")
}
pub fn publish_model_artifacts(plan: &PlannedModelArtifacts) -> Result<(), String> {
let original_static = std::fs::read(&plan.static_path).ok();
let original_animation = std::fs::read(&plan.animation_path).ok();
let result = write_if_changed(&plan.static_path, &plan.static_bytes)
.and_then(|_| write_if_changed(&plan.animation_path, &plan.animation_bytes));
if let Err(error) = result {
restore_artifact(&plan.static_path, original_static.as_deref());
restore_artifact(&plan.animation_path, original_animation.as_deref());
return Err(format!("model artifact publication rolled back: {error}"));
}
Ok(())
}
fn restore_artifact(path: &std::path::Path, bytes: Option<&[u8]>) {
if let Some(bytes) = bytes {
let _ = std::fs::write(path, bytes);
} else {
let _ = std::fs::remove_file(path);
}
}
/// Refreshes both generated contracts derived from one imported model source.
pub fn refresh_model_artifacts(
record: &mut shared::AssetRecord,
) -> Result<static_mesh::StaticMeshManifest, String> {
let plan = plan_model_artifacts(record)?;
publish_model_artifacts(&plan)?;
*record = plan.record.clone();
Ok(plan.static_manifest)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn classification_is_folder_independent() {
assert_eq!(
classify_asset(Path::new("assets/Anything/hero.glb")),
AssetKind::Model
);
assert_eq!(
classify_asset(Path::new("assets/Props/Office/wall.material.ron")),
AssetKind::Material
);
}
#[test]
fn managed_and_escaping_paths_are_rejected() {
assert!(validate_asset_path(Path::new("assets/Props/Office")).is_ok());
assert!(validate_asset_path(Path::new("assets/.index/registry.ron")).is_err());
assert!(validate_asset_path(Path::new("assets/meshes/generated/a.ron")).is_err());
assert!(validate_asset_path(Path::new("../outside")).is_err());
}
#[test]
fn registry_publication_always_updates_the_runtime_catalog() {
let root = std::env::temp_dir().join(format!(
"blacksite-content-publish-{}",
shared::AssetId::new().as_string()
));
let document = AssetRegistryDocument {
records: vec![AssetRecord {
id: shared::AssetId::new(),
path: "assets/Props/a.png".into(),
label: "A".into(),
kind: AssetKind::Texture,
source_fingerprint: None,
import_settings: shared::AssetImportSettings::for_kind(AssetKind::Texture),
dependencies: Vec::new(),
}],
..Default::default()
};
publish_content_documents(&root, &document).unwrap();
let runtime: RuntimeContentCatalog =
ron::from_str(&fs::read_to_string(root.join(RUNTIME_CATALOG_PATH)).unwrap()).unwrap();
assert_eq!(runtime.records[0].path, "assets/Props/a.png");
fs::remove_dir_all(root).unwrap();
}
#[test]
fn headless_scan_migrates_legacy_authoring_override_to_stable_slots() {
let root = std::env::temp_dir().join(format!(
"blacksite-content-policy-migration-{}",
shared::AssetId::new().as_string()
));
fs::create_dir_all(root.join("assets/meshes/generated")).unwrap();
fs::write(root.join("assets/chair.fbx"), b"chair").unwrap();
fs::write(
root.join("assets/meshes/generated/chair.ron"),
"(parts:[(id:\"draw:0\",material_id:Some(\"material:0\"))])",
)
.unwrap();
let previous = AssetRegistryDocument {
records: vec![AssetRecord {
id: shared::AssetId::new(),
path: "assets/chair.fbx".into(),
label: "Chair".into(),
kind: AssetKind::Model,
source_fingerprint: Some(AssetSourceFingerprint::from_bytes(b"chair")),
import_settings: shared::AssetImportSettings::Model(shared::ImportSettings {
material_policy: MaterialImportPolicy::AuthoringOverride,
static_mesh_manifest_path: Some("assets/meshes/generated/chair.ron".into()),
..Default::default()
}),
dependencies: Vec::new(),
}],
..Default::default()
};
let processed = scan_project(&root, &previous).unwrap();
let settings = processed.registry.records[0].model_import();
assert_eq!(
settings.material_policy,
MaterialImportPolicy::SourceMaterials
);
assert_eq!(settings.material_slots.len(), 1);
assert_eq!(settings.material_slots[0].slot_id.0, "slot:draw:0");
assert!(matches!(
settings.material_slots[0].selection,
ModelMaterialSelection::Default
));
fs::remove_dir_all(root).unwrap();
}
#[test]
fn scan_refuses_ambiguous_external_moves_instead_of_replacing_stable_identity() {
let root = std::env::temp_dir().join(format!(
"blacksite-content-ambiguous-move-{}",
shared::AssetId::new().as_string()
));
fs::create_dir_all(root.join("assets/New")).unwrap();
fs::write(root.join("assets/New/desk.png"), b"duplicate pixels").unwrap();
let fingerprint = AssetSourceFingerprint::from_bytes(b"duplicate pixels");
let previous = AssetRegistryDocument {
records: ["assets/OldA/desk.png", "assets/OldB/desk.png"]
.into_iter()
.map(|path| AssetRecord {
id: shared::AssetId::new(),
path: path.into(),
label: "Desk".into(),
kind: AssetKind::Texture,
source_fingerprint: Some(fingerprint.clone()),
import_settings: shared::AssetImportSettings::for_kind(AssetKind::Texture),
dependencies: Vec::new(),
})
.collect(),
..Default::default()
};
let conflicts = find_ambiguous_external_moves(&root, &previous).unwrap();
assert_eq!(conflicts.len(), 1);
assert_eq!(conflicts[0].new_path, "assets/New/desk.png");
assert_eq!(
conflicts[0].candidate_paths,
["assets/OldA/desk.png", "assets/OldB/desk.png"]
);
let error = scan_project(&root, &previous).unwrap_err();
assert!(error.contains("ambiguous external move"));
assert!(error.contains("assets/OldA/desk.png"));
assert!(error.contains("assets/OldB/desk.png"));
assert!(error.contains("Content Browser"));
fs::remove_dir_all(root).unwrap();
}
#[test]
fn scan_preserves_unique_imported_source_ids_across_external_moves() {
let root = std::env::temp_dir().join(format!(
"blacksite-content-unique-moves-{}",
shared::AssetId::new().as_string()
));
fs::create_dir_all(root.join("assets/New")).unwrap();
let fixtures = [
("model.glb", AssetKind::Model, b"model bytes".as_slice()),
(
"texture.png",
AssetKind::Texture,
b"texture bytes".as_slice(),
),
("audio.ogg", AssetKind::AudioClip, b"audio bytes".as_slice()),
];
let mut expected = Vec::new();
let mut records = Vec::new();
for (name, kind, bytes) in fixtures {
fs::write(root.join("assets/New").join(name), bytes).unwrap();
let id = shared::AssetId::new();
expected.push((format!("assets/New/{name}"), id.clone()));
records.push(AssetRecord {
id,
path: format!("assets/Old/{name}"),
label: name.into(),
kind,
source_fingerprint: Some(AssetSourceFingerprint::from_bytes(bytes)),
import_settings: shared::AssetImportSettings::for_kind(kind),
dependencies: Vec::new(),
});
}
let previous = AssetRegistryDocument {
records,
..Default::default()
};
let processed = scan_project(&root, &previous).unwrap();
assert_eq!(processed.report.moved, 3);
for (path, id) in expected {
assert_eq!(
processed
.registry
.records
.iter()
.find(|record| record.path == path)
.map(|record| &record.id),
Some(&id)
);
}
fs::remove_dir_all(root).unwrap();
}
}
+302
View File
@@ -0,0 +1,302 @@
use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;
use std::path::{Path, PathBuf};
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Hash)]
pub enum PbrTextureRole {
BaseColor,
Normal,
Roughness,
Metallic,
Occlusion,
PackedOrm,
Height,
Unknown,
}
impl PbrTextureRole {
pub const ALL: [Self; 8] = [
Self::BaseColor,
Self::Normal,
Self::Roughness,
Self::Metallic,
Self::Occlusion,
Self::PackedOrm,
Self::Height,
Self::Unknown,
];
pub const fn label(self) -> &'static str {
match self {
Self::BaseColor => "Base color",
Self::Normal => "Normal",
Self::Roughness => "Roughness",
Self::Metallic => "Metallic",
Self::Occlusion => "Occlusion",
Self::PackedOrm => "Packed ORM/ARM",
Self::Height => "Height",
Self::Unknown => "Unresolved",
}
}
}
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
pub enum PbrMatchConfidence {
High,
Medium,
Low,
Unresolved,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct DetectedPbrTexture {
pub path: PathBuf,
pub group_key: String,
pub role: PbrTextureRole,
pub confidence: PbrMatchConfidence,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct DetectedPbrGroup {
pub key: String,
pub textures: Vec<DetectedPbrTexture>,
}
pub fn detect_pbr_texture_groups(
paths: impl IntoIterator<Item = PathBuf>,
) -> Vec<DetectedPbrGroup> {
let mut groups: BTreeMap<String, Vec<DetectedPbrTexture>> = BTreeMap::new();
for path in paths {
if !is_texture_path(&path) {
continue;
}
let (group_key, role, confidence) = classify_texture_name(&path);
groups
.entry(group_key.clone())
.or_default()
.push(DetectedPbrTexture {
path,
group_key,
role,
confidence,
});
}
groups
.into_iter()
.map(|(key, mut textures)| {
textures.sort_by(|left, right| left.path.cmp(&right.path));
DetectedPbrGroup { key, textures }
})
.collect()
}
fn classify_texture_name(path: &Path) -> (String, PbrTextureRole, PbrMatchConfidence) {
let stem = path
.file_stem()
.and_then(|stem| stem.to_str())
.unwrap_or("texture")
.to_ascii_lowercase();
let mut tokens: Vec<&str> = stem
.split(|character: char| !character.is_ascii_alphanumeric())
.filter(|token| !token.is_empty())
.collect();
while tokens
.last()
.is_some_and(|token| is_resolution_token(token))
{
tokens.pop();
}
let joined = tokens.join("_");
let aliases: &[(&[&str], PbrTextureRole, PbrMatchConfidence)] = &[
(
&["occlusion", "roughness", "metallic"],
PbrTextureRole::PackedOrm,
PbrMatchConfidence::High,
),
(
&["base", "color"],
PbrTextureRole::BaseColor,
PbrMatchConfidence::High,
),
(
&["ambient", "occlusion"],
PbrTextureRole::Occlusion,
PbrMatchConfidence::High,
),
(
&["metallic", "roughness"],
PbrTextureRole::PackedOrm,
PbrMatchConfidence::Medium,
),
(
&["basecolor"],
PbrTextureRole::BaseColor,
PbrMatchConfidence::High,
),
(
&["albedo"],
PbrTextureRole::BaseColor,
PbrMatchConfidence::High,
),
(
&["diffuse"],
PbrTextureRole::BaseColor,
PbrMatchConfidence::High,
),
(
&["diff"],
PbrTextureRole::BaseColor,
PbrMatchConfidence::Medium,
),
(
&["normal"],
PbrTextureRole::Normal,
PbrMatchConfidence::High,
),
(
&["nor", "gl"],
PbrTextureRole::Normal,
PbrMatchConfidence::High,
),
(
&["nor", "dx"],
PbrTextureRole::Normal,
PbrMatchConfidence::High,
),
(&["nrm"], PbrTextureRole::Normal, PbrMatchConfidence::Medium),
(
&["roughness"],
PbrTextureRole::Roughness,
PbrMatchConfidence::High,
),
(
&["rough"],
PbrTextureRole::Roughness,
PbrMatchConfidence::Medium,
),
(
&["metallic"],
PbrTextureRole::Metallic,
PbrMatchConfidence::High,
),
(
&["metalness"],
PbrTextureRole::Metallic,
PbrMatchConfidence::High,
),
(
&["metal"],
PbrTextureRole::Metallic,
PbrMatchConfidence::Medium,
),
(
&["occlusion"],
PbrTextureRole::Occlusion,
PbrMatchConfidence::High,
),
(&["ao"], PbrTextureRole::Occlusion, PbrMatchConfidence::High),
(
&["orm"],
PbrTextureRole::PackedOrm,
PbrMatchConfidence::High,
),
(
&["arm"],
PbrTextureRole::PackedOrm,
PbrMatchConfidence::High,
),
(
&["height"],
PbrTextureRole::Height,
PbrMatchConfidence::High,
),
(
&["displacement"],
PbrTextureRole::Height,
PbrMatchConfidence::High,
),
(
&["disp"],
PbrTextureRole::Height,
PbrMatchConfidence::Medium,
),
(&["n"], PbrTextureRole::Normal, PbrMatchConfidence::Low),
(&["r"], PbrTextureRole::Roughness, PbrMatchConfidence::Low),
(&["m"], PbrTextureRole::Metallic, PbrMatchConfidence::Low),
];
for (suffix, role, confidence) in aliases {
if tokens.ends_with(suffix) {
let base_len = tokens.len().saturating_sub(suffix.len());
let group = tokens[..base_len].join("_");
return (
if group.is_empty() {
joined.clone()
} else {
group
},
*role,
*confidence,
);
}
}
(
joined,
PbrTextureRole::Unknown,
PbrMatchConfidence::Unresolved,
)
}
fn is_resolution_token(token: &str) -> bool {
token
.strip_suffix('k')
.is_some_and(|number| matches!(number, "1" | "2" | "4" | "8" | "16"))
}
fn is_texture_path(path: &Path) -> bool {
matches!(
path.extension()
.and_then(|extension| extension.to_str())
.unwrap_or_default()
.to_ascii_lowercase()
.as_str(),
"png" | "jpg" | "jpeg" | "webp" | "ktx2" | "dds" | "tga" | "exr" | "hdr"
)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn poly_haven_suffixes_form_one_high_confidence_group() {
let groups = detect_pbr_texture_groups([
"assets/metal_office_desk_diff_2k.jpg".into(),
"assets/metal_office_desk_nor_gl_2k.jpg".into(),
"assets/metal_office_desk_arm_2k.jpg".into(),
]);
assert_eq!(groups.len(), 1);
assert_eq!(groups[0].key, "metal_office_desk");
assert!(groups[0]
.textures
.iter()
.any(|texture| texture.role == PbrTextureRole::BaseColor));
assert!(groups[0]
.textures
.iter()
.any(|texture| texture.role == PbrTextureRole::Normal));
assert!(groups[0]
.textures
.iter()
.any(|texture| texture.role == PbrTextureRole::PackedOrm));
}
#[test]
fn unknown_images_remain_visible_for_manual_resolution() {
let groups = detect_pbr_texture_groups(["assets/wood_preview.png".into()]);
assert_eq!(groups[0].textures[0].role, PbrTextureRole::Unknown);
assert_eq!(
groups[0].textures[0].confidence,
PbrMatchConfidence::Unresolved
);
}
}
+963
View File
@@ -0,0 +1,963 @@
//! Normalized static mesh artifacts generated from model source files.
use std::fs;
use std::path::Path;
use bevy::gltf::GltfAssetLabel;
use bevy::prelude::*;
use bevy_ufbx::label::FbxAssetLabel;
use bevy_ufbx::mesh::group_faces_by_material;
use bevy_ufbx::texture::external_texture_paths;
use bevy_ufbx::utils::convert_matrix;
use serde::{Deserialize, Serialize};
use shared::{
AssetRecord, ImportSettings, MaterialImportPolicy, ModelHierarchyMode, ModelMaterialSelection,
ModelPlacementMode,
};
use shared::{
AssetSourceFingerprint, ComponentInstanceId, EditorAssetRef, MaterialSlot, MaterialSlotSet,
ModelMaterialSlotSelection, OrphanedModelMaterialSelection, StaticMeshRenderer,
StaticMeshRendererEntry,
};
use crate::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)]
pub struct StaticMeshManifest {
pub schema_version: u32,
pub asset_id: String,
pub label: String,
pub source: StaticMeshSource,
pub import: StaticMeshImportSnapshot,
pub metadata: StaticMeshMetadata,
pub parts: Vec<StaticMeshPart>,
pub warnings: Vec<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct StaticMeshSource {
pub path: String,
pub format: String,
pub fingerprint: StaticMeshSourceFingerprint,
pub dependencies: Vec<String>,
}
pub type StaticMeshSourceFingerprint = AssetSourceFingerprint;
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct StaticMeshImportSnapshot {
pub scale: f32,
pub generate_collider: bool,
pub lod0_only: bool,
pub placement_mode: ModelPlacementMode,
pub hierarchy_mode: ModelHierarchyMode,
#[serde(default, skip_serializing_if = "material_policy_is_default")]
pub material_policy: MaterialImportPolicy,
#[serde(default)]
pub material_slots: Vec<shared::ModelMaterialSlotSelection>,
#[serde(default)]
pub orphaned_material_slots: Vec<shared::OrphanedModelMaterialSelection>,
}
fn material_policy_is_default(policy: &MaterialImportPolicy) -> bool {
*policy == MaterialImportPolicy::SourceMaterials
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct StaticMeshMetadata {
pub mesh_count: usize,
pub material_count: usize,
pub node_count: usize,
pub animation_count: usize,
pub skin_count: usize,
pub light_count: usize,
pub camera_count: usize,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct StaticMeshPart {
#[serde(default)]
pub id: String,
pub name: String,
pub mesh_label: String,
#[serde(default)]
pub material_id: Option<String>,
pub material_slot_name: String,
pub material_label: Option<String>,
pub local_transform: Transform,
pub source_node: Option<String>,
pub source_mesh: Option<String>,
pub source_material: Option<String>,
/// Whether the source primitive is bound to a skin and therefore must never become a static
/// renderer slot.
#[serde(default)]
pub skinned: bool,
}
pub fn static_mesh_manifest_path(asset_id: &str) -> String {
format!("{STATIC_MESH_ARTIFACT_DIR}/{asset_id}.static_mesh.ron")
}
pub fn part_id_from_label(label: &str) -> String {
format!("mesh:{}", stable_sub_asset_slug(label))
}
pub fn material_id_from_label(label: &str) -> String {
format!("material:{}", stable_sub_asset_slug(label))
}
fn gltf_draw_id(node_index: Option<usize>, mesh_index: usize, primitive_index: usize) -> String {
let node = node_index
.map(|index| index.to_string())
.unwrap_or_else(|| "unbound".into());
format!("draw:scene0:node{node}:mesh{mesh_index}:primitive{primitive_index}")
}
fn fbx_draw_id(node_index: usize, material_index: usize) -> String {
format!("draw:scene0:node{node_index}:material{material_index}")
}
fn stable_sub_asset_slug(label: &str) -> String {
let mut slug = String::new();
for ch in label.chars() {
if ch.is_ascii_alphanumeric() {
slug.push(ch.to_ascii_lowercase());
} else if !slug.ends_with('_') {
slug.push('_');
}
}
slug.trim_matches('_').to_string()
}
pub fn refresh_static_mesh_artifact(
record: &mut AssetRecord,
) -> Result<StaticMeshManifest, String> {
let (manifest, path) = plan_static_mesh_artifact(record)?;
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,
path,
manifest.parts.len()
);
}
Ok(manifest)
}
pub fn plan_static_mesh_artifact(
record: &mut AssetRecord,
) -> Result<(StaticMeshManifest, String), String> {
let mut manifest = build_static_mesh_manifest(record)?;
reconcile_model_material_slots(&manifest, record.model_import_mut());
manifest.import.material_policy = MaterialImportPolicy::SourceMaterials;
manifest.import.material_slots = record.model_import().material_slots.clone();
manifest.import.orphaned_material_slots = record.model_import().orphaned_material_slots.clone();
let path = static_mesh_manifest_path(&record.id.as_string());
record.model_import_mut().static_mesh_manifest_path = Some(path.clone());
manifest.source.dependencies.sort();
manifest.source.dependencies.dedup();
record.dependencies = manifest.source.dependencies.clone();
Ok((manifest, path))
}
pub fn load_static_mesh_manifest(path: &str) -> Result<StaticMeshManifest, String> {
let text = fs::read_to_string(path).map_err(|err| format!("could not read {path}: {err}"))?;
ron::from_str(&text).map_err(|err| format!("could not parse {path}: {err}"))
}
pub fn renderer_from_manifest(
manifest: &StaticMeshManifest,
_settings: &ImportSettings,
) -> StaticMeshRenderer {
let parts: Vec<_> = manifest
.parts
.iter()
.filter(|part| !part.skinned && manifest.metadata.animation_count == 0)
.map(|part| StaticMeshRendererEntry {
id: ComponentInstanceId::new(part_effective_id(part)),
name: part.name.clone(),
mesh: EditorAssetRef::new(
manifest.asset_id.clone(),
part_effective_id(part),
part.name.clone(),
),
material_slot_id: ComponentInstanceId::new(material_slot_id(part)),
local_transform: part.local_transform,
visible: true,
cast_shadows: true,
receive_shadows: true,
})
.collect();
let materials = MaterialSlotSet {
slots: manifest
.parts
.iter()
.filter(|part| !part.skinned && manifest.metadata.animation_count == 0)
.map(|part| MaterialSlot {
id: ComponentInstanceId::new(material_slot_id(part)),
name: part.material_slot_name.clone(),
material: None,
})
.collect(),
orphaned_assignments: Vec::new(),
};
StaticMeshRenderer {
slots: parts,
materials,
}
}
/// Builds the shared material slots for a full imported hierarchy. Unlike static renderer
/// construction this intentionally includes skin-bound and rigid animated draw bindings.
pub fn renderer_materials_from_manifest(
manifest: &StaticMeshManifest,
_settings: &ImportSettings,
) -> MaterialSlotSet {
MaterialSlotSet {
slots: manifest
.parts
.iter()
.map(|part| MaterialSlot {
id: ComponentInstanceId::new(material_slot_id(part)),
name: part.material_slot_name.clone(),
material: None,
})
.collect(),
orphaned_assignments: Vec::new(),
}
}
pub fn material_selection<'a>(
settings: &'a ImportSettings,
slot_id: &str,
) -> &'a ModelMaterialSelection {
settings
.material_slots
.iter()
.find(|entry| entry.slot_id.0 == slot_id)
.map(|entry| &entry.selection)
.unwrap_or(&ModelMaterialSelection::Source)
}
fn reconcile_model_material_slots(manifest: &StaticMeshManifest, settings: &mut ImportSettings) {
let names = manifest
.parts
.iter()
.map(|part| (material_slot_id(part), part.material_slot_name.clone()))
.collect::<std::collections::BTreeMap<_, _>>();
if settings.material_policy == MaterialImportPolicy::AuthoringOverride {
for slot_id in names.keys() {
if !settings
.material_slots
.iter()
.any(|selection| selection.slot_id.0 == *slot_id)
{
settings.material_slots.push(ModelMaterialSlotSelection {
slot_id: ComponentInstanceId::new(slot_id.clone()),
selection: ModelMaterialSelection::Default,
});
}
}
}
settings.material_policy = MaterialImportPolicy::SourceMaterials;
let mut retained = Vec::with_capacity(settings.material_slots.len());
for selection in settings.material_slots.drain(..) {
if names.contains_key(&selection.slot_id.0) {
retained.push(selection);
} else if let ModelMaterialSelection::Project(material) = selection.selection {
settings
.orphaned_material_slots
.push(OrphanedModelMaterialSelection {
slot_id: selection.slot_id,
last_known_name: "Removed imported material slot".into(),
material,
});
}
}
retained.sort_by(|left, right| left.slot_id.0.cmp(&right.slot_id.0));
settings.material_slots = retained;
settings
.orphaned_material_slots
.retain(|orphan| !names.contains_key(&orphan.slot_id.0));
settings
.orphaned_material_slots
.sort_by(|left, right| left.slot_id.0.cmp(&right.slot_id.0));
}
fn material_slot_id(part: &StaticMeshPart) -> String {
format!("slot:{}", part_effective_id(part))
}
fn part_effective_id(part: &StaticMeshPart) -> String {
if part.id.trim().is_empty() {
part_id_from_label(&part.mesh_label)
} else {
part.id.clone()
}
}
fn build_static_mesh_manifest(record: &AssetRecord) -> Result<StaticMeshManifest, String> {
let format = source_format(&record.path)?;
let fingerprint = fingerprint_file(&record.path)?;
let import = StaticMeshImportSnapshot {
scale: record.model_import().scale,
generate_collider: record.model_import().generate_collider,
lod0_only: record.model_import().lod0_only,
placement_mode: record.model_import().placement_mode,
hierarchy_mode: record.model_import().hierarchy_mode,
material_policy: MaterialImportPolicy::SourceMaterials,
material_slots: record.model_import().material_slots.clone(),
orphaned_material_slots: record.model_import().orphaned_material_slots.clone(),
};
let mut manifest = match format.as_str() {
"gltf" | "glb" => build_gltf_manifest(record, format, fingerprint, import)?,
"fbx" => build_fbx_manifest(record, format, fingerprint, import)?,
_ => return Err(format!("unsupported static mesh source format `{format}`")),
};
if manifest.parts.is_empty() {
manifest
.warnings
.push("No renderable static mesh parts were found.".into());
}
Ok(manifest)
}
fn build_gltf_manifest(
record: &AssetRecord,
format: String,
fingerprint: StaticMeshSourceFingerprint,
import: StaticMeshImportSnapshot,
) -> Result<StaticMeshManifest, String> {
let gltf = gltf::Gltf::open(&record.path)
.map_err(|err| format!("could not parse glTF {}: {err}", record.path))?;
let mut parts = Vec::new();
let mut dependencies = Vec::new();
let mut warnings = Vec::new();
for buffer in gltf.document.buffers() {
if let gltf::buffer::Source::Uri(uri) = buffer.source() {
dependencies.push(resolve_dependency(&record.path, uri));
}
}
for image in gltf.document.images() {
if let gltf::image::Source::Uri { uri, .. } = image.source() {
dependencies.push(resolve_dependency(&record.path, uri));
}
}
if let Some(scene) = gltf
.document
.default_scene()
.or_else(|| gltf.document.scenes().next())
{
for node in scene.nodes() {
collect_gltf_node_parts(node, Mat4::IDENTITY, "", &mut parts);
}
} else {
for mesh in gltf.document.meshes() {
collect_gltf_mesh_parts(None, None, None, mesh, Mat4::IDENTITY, false, &mut parts);
}
}
if gltf.document.animations().count() > 0 {
warnings.push(
"Animations are recorded as metadata; animated placement uses SkinnedMeshRenderer."
.into(),
);
}
if gltf.document.skins().count() > 0 {
warnings.push(
"Skinned primitives are excluded from StaticMeshRenderer and use SkinnedMeshRenderer."
.into(),
);
}
parts.sort_by(|a, b| a.mesh_label.cmp(&b.mesh_label).then(a.name.cmp(&b.name)));
Ok(StaticMeshManifest {
schema_version: STATIC_MESH_MANIFEST_SCHEMA,
asset_id: record.id.as_string(),
label: record.label.clone(),
source: StaticMeshSource {
path: record.path.clone(),
format,
fingerprint,
dependencies,
},
import,
metadata: StaticMeshMetadata {
mesh_count: gltf.document.meshes().count(),
material_count: gltf.document.materials().count(),
node_count: gltf.document.nodes().count(),
animation_count: gltf.document.animations().count(),
skin_count: gltf.document.skins().count(),
light_count: 0,
camera_count: gltf.document.cameras().count(),
},
parts,
warnings,
})
}
fn collect_gltf_node_parts(
node: gltf::Node<'_>,
parent_transform: Mat4,
parent_path: &str,
parts: &mut Vec<StaticMeshPart>,
) {
let local = Mat4::from_cols_array_2d(&node.transform().matrix());
let world_transform = parent_transform * local;
let segment = node
.name()
.map(str::to_string)
.unwrap_or_else(|| format!("Node{}", node.index()));
let node_path = if parent_path.is_empty() {
segment
} else {
format!("{parent_path}/{segment}")
};
let skinned = node.skin().is_some();
if let Some(mesh) = node.mesh() {
collect_gltf_mesh_parts(
node.name().map(str::to_string),
Some(node.index()),
Some(node_path.clone()),
mesh,
world_transform,
skinned,
parts,
);
}
for child in node.children() {
collect_gltf_node_parts(child, world_transform, &node_path, parts);
}
}
fn collect_gltf_mesh_parts(
node_name: Option<String>,
node_index: Option<usize>,
node_path: Option<String>,
mesh: gltf::Mesh<'_>,
transform: Mat4,
skinned: bool,
parts: &mut Vec<StaticMeshPart>,
) {
let mesh_index = mesh.index();
let mesh_name = mesh.name().map(str::to_string);
for primitive in mesh.primitives() {
let primitive_index = primitive.index();
let mesh_label = GltfAssetLabel::Primitive {
mesh: mesh_index,
primitive: primitive_index,
}
.to_string();
let material = primitive.material();
let material_label = material
.index()
.map(|index| {
GltfAssetLabel::Material {
index,
is_scale_inverted: false,
}
.to_string()
})
.or_else(|| Some(GltfAssetLabel::DefaultMaterial.to_string()));
let material_name = material
.name()
.map(str::to_string)
.unwrap_or_else(|| "Default Material".into());
let name = node_name
.clone()
.or_else(|| mesh_name.clone())
.unwrap_or_else(|| format!("Mesh {mesh_index}"));
let source_node = node_path
.clone()
.or_else(|| node_index.map(|index| format!("Node{index}")));
parts.push(StaticMeshPart {
id: gltf_draw_id(node_index, mesh_index, primitive_index),
name: format!("{name} / Primitive {primitive_index}"),
material_id: material_label
.as_ref()
.map(|label| material_id_from_label(label)),
mesh_label,
material_slot_name: material_name.clone(),
material_label,
local_transform: Transform::from_matrix(transform),
source_node,
source_mesh: Some(format!("Mesh{mesh_index}")),
source_material: Some(material_name),
skinned,
});
}
}
fn build_fbx_manifest(
record: &AssetRecord,
format: String,
fingerprint: StaticMeshSourceFingerprint,
import: StaticMeshImportSnapshot,
) -> Result<StaticMeshManifest, String> {
let bytes =
fs::read(&record.path).map_err(|err| format!("could not read {}: {err}", record.path))?;
let scene = ufbx::load_memory(
&bytes,
ufbx::LoadOpts {
target_unit_meters: 1.0,
target_axes: ufbx::CoordinateAxes::right_handed_y_up(),
filename: ufbx::StringOpt::Ref(&record.path),
..Default::default()
},
)
.map_err(|err| format!("could not parse FBX {}: {err:?}", record.path))?;
let mut parts = Vec::new();
let mut warnings = Vec::new();
for (node_index, node) in scene.nodes.as_ref().iter().enumerate() {
let Some(mesh_ref) = node.mesh.as_ref() else {
continue;
};
let mesh = mesh_ref.as_ref();
if mesh.num_vertices == 0 || mesh.faces.as_ref().is_empty() {
continue;
}
let skinned = !mesh.skin_deformers.as_ref().is_empty();
let mut groups: Vec<(usize, Vec<u32>)> =
group_faces_by_material(mesh).into_iter().collect();
groups.sort_by_key(|(material_index, _)| *material_index);
for (material_index, indices) in groups {
if indices.is_empty() {
continue;
}
let material = mesh.materials.get(material_index).map(|mat| mat.as_ref());
let material_label = material
.and_then(|mat| fbx_material_label(&scene, mat.element.element_id))
.or_else(|| Some(FbxAssetLabel::DefaultMaterial.to_string()));
let material_name = material
.map(|mat| mat.element.name.to_string())
.filter(|name| !name.is_empty())
.unwrap_or_else(|| "Default Material".into());
let node_name = if node.element.name.is_empty() {
format!("Node {node_index}")
} else {
node.element.name.to_string()
};
let mesh_label = FbxAssetLabel::Mesh(node_index * 1000 + material_index).to_string();
parts.push(StaticMeshPart {
id: fbx_draw_id(node_index, material_index),
name: format!("{node_name} / Material {material_index}"),
material_id: material_label
.as_ref()
.map(|label| material_id_from_label(label)),
mesh_label,
material_slot_name: material_name.clone(),
material_label,
local_transform: Transform::from_matrix(convert_matrix(&node.geometry_to_world)),
source_node: Some(format!("Node{node_index}")),
source_mesh: Some(format!("Mesh{node_index}")),
source_material: Some(material_name),
skinned,
});
}
}
if !scene.anim_stacks.as_ref().is_empty() {
warnings.push(
"Animations are recorded as metadata; animated placement uses SkinnedMeshRenderer."
.into(),
);
}
if !scene.skin_deformers.as_ref().is_empty() {
warnings.push(
"Skinned primitives are excluded from StaticMeshRenderer and use SkinnedMeshRenderer."
.into(),
);
}
parts.sort_by(|a, b| a.mesh_label.cmp(&b.mesh_label).then(a.name.cmp(&b.name)));
Ok(StaticMeshManifest {
schema_version: STATIC_MESH_MANIFEST_SCHEMA,
asset_id: record.id.as_string(),
label: record.label.clone(),
source: StaticMeshSource {
path: record.path.clone(),
format,
fingerprint,
dependencies: fbx_dependencies(&record.path, &scene)?,
},
import,
metadata: StaticMeshMetadata {
mesh_count: scene.meshes.as_ref().len(),
material_count: scene.materials.as_ref().len(),
node_count: scene.nodes.as_ref().len(),
animation_count: scene.anim_stacks.as_ref().len(),
skin_count: scene.skin_deformers.as_ref().len(),
light_count: scene.lights.as_ref().len(),
camera_count: scene.cameras.as_ref().len(),
},
parts,
warnings,
})
}
fn fbx_material_label(scene: &ufbx::Scene, element_id: u32) -> Option<String> {
if element_id == 0 {
return None;
}
scene
.materials
.as_ref()
.iter()
.position(|material| material.element.element_id == element_id)
.map(|index| FbxAssetLabel::Material(index).to_string())
}
fn fbx_dependencies(source_path: &str, scene: &ufbx::Scene) -> Result<Vec<String>, String> {
let path = Path::new(source_path);
let parent = path.parent().unwrap_or_else(|| Path::new(""));
external_texture_paths(scene)
.map_err(|errors| {
format!(
"unsafe FBX texture reference(s) in {source_path}: {}",
errors
.into_iter()
.map(|error| error.to_string())
.collect::<Vec<_>>()
.join("; ")
)
})
.map(|paths| {
paths
.into_iter()
.map(|relative| parent.join(relative).to_string_lossy().replace('\\', "/"))
.collect()
})
}
fn source_format(path: &str) -> Result<String, String> {
Path::new(path)
.extension()
.and_then(|ext| ext.to_str())
.map(|ext| ext.to_ascii_lowercase())
.ok_or_else(|| format!("asset path `{path}` has no extension"))
}
fn resolve_dependency(source_path: &str, uri: &str) -> String {
if uri.starts_with("data:") || uri.contains("://") {
return uri.to_string();
}
Path::new(source_path)
.parent()
.unwrap_or_else(|| Path::new(""))
.join(uri)
.to_string_lossy()
.replace('\\', "/")
}
#[cfg(test)]
mod tests {
use super::*;
use shared::{AssetId, MaterialRef};
fn test_manifest() -> StaticMeshManifest {
StaticMeshManifest {
schema_version: STATIC_MESH_MANIFEST_SCHEMA,
asset_id: "asset-1".into(),
label: "Crate".into(),
source: StaticMeshSource {
path: "assets/models/crate.glb".into(),
format: "glb".into(),
fingerprint: StaticMeshSourceFingerprint {
byte_len: 42,
content_hash: "a".repeat(64),
},
dependencies: Vec::new(),
},
import: StaticMeshImportSnapshot {
scale: 1.0,
generate_collider: true,
lod0_only: true,
placement_mode: ModelPlacementMode::StaticAsset,
hierarchy_mode: ModelHierarchyMode::SingleActor,
material_policy: MaterialImportPolicy::SourceMaterials,
material_slots: Vec::new(),
orphaned_material_slots: Vec::new(),
},
metadata: StaticMeshMetadata {
mesh_count: 1,
material_count: 1,
node_count: 1,
animation_count: 0,
skin_count: 0,
light_count: 0,
camera_count: 0,
},
parts: vec![StaticMeshPart {
id: "mesh:mesh0_primitive0".into(),
name: "Crate / Primitive 0".into(),
mesh_label: "Mesh0/Primitive0".into(),
material_id: Some("material:material0".into()),
material_slot_name: "Wood".into(),
material_label: Some("Material0".into()),
local_transform: Transform::from_xyz(1.0, 2.0, 3.0),
source_node: Some("Node0".into()),
source_mesh: Some("Mesh0".into()),
source_material: Some("Wood".into()),
skinned: false,
}],
warnings: Vec::new(),
}
}
#[test]
fn static_mesh_manifest_path_uses_asset_id() {
assert_eq!(
static_mesh_manifest_path("abc"),
"assets/meshes/generated/abc.static_mesh.ron"
);
}
#[test]
fn renderer_from_manifest_preserves_labels_and_collider_policy() {
let manifest = test_manifest();
let settings = ImportSettings {
generate_collider: true,
..Default::default()
};
let renderer = renderer_from_manifest(&manifest, &settings);
assert_eq!(renderer.slots.len(), 1);
let entry = &renderer.slots[0];
assert_eq!(entry.mesh.asset_id, manifest.asset_id);
assert_eq!(entry.mesh.sub_asset_id, "mesh:mesh0_primitive0");
assert!(renderer.materials.slots[0].material.is_none());
}
#[test]
fn model_slot_selection_remains_asset_owned() {
let manifest = test_manifest();
let project = MaterialRef::new(
EditorAssetRef::new("project-material", "", "Paint")
.with_source_path("assets/Props/paint.material.ron"),
);
let mut settings = ImportSettings::default();
settings
.material_slots
.push(shared::ModelMaterialSlotSelection {
slot_id: ComponentInstanceId::new("slot:mesh:mesh0_primitive0"),
selection: ModelMaterialSelection::Project(project.clone()),
});
let renderer = renderer_from_manifest(&manifest, &settings);
assert!(renderer.materials.slots[0].material.is_none());
assert_eq!(
material_selection(&settings, "slot:mesh:mesh0_primitive0"),
&ModelMaterialSelection::Project(project)
);
settings.material_slots[0].selection = ModelMaterialSelection::Default;
let renderer = renderer_from_manifest(&manifest, &settings);
assert!(renderer.materials.slots[0].material.is_none());
assert_eq!(
material_selection(&settings, "slot:mesh:mesh0_primitive0"),
&ModelMaterialSelection::Default
);
}
#[test]
fn removed_project_selection_becomes_an_orphan() {
let manifest = test_manifest();
let material = MaterialRef::new(EditorAssetRef::new("paint", "", "Paint"));
let mut settings = ImportSettings::default();
settings
.material_slots
.push(shared::ModelMaterialSlotSelection {
slot_id: ComponentInstanceId::new("slot:removed"),
selection: ModelMaterialSelection::Project(material.clone()),
});
reconcile_model_material_slots(&manifest, &mut settings);
assert!(settings.material_slots.is_empty());
assert_eq!(settings.orphaned_material_slots.len(), 1);
assert_eq!(settings.orphaned_material_slots[0].material, material);
}
#[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_select_default_per_slot() {
let manifest = test_manifest();
let settings = ImportSettings {
material_slots: vec![ModelMaterialSlotSelection {
slot_id: ComponentInstanceId::new(format!(
"slot:{}",
part_effective_id(&manifest.parts[0])
)),
selection: ModelMaterialSelection::Default,
}],
..Default::default()
};
let renderer = renderer_from_manifest(&manifest, &settings);
assert!(renderer.materials.slots[0].material.is_none());
assert_eq!(
material_selection(&settings, &renderer.materials.slots[0].id.0),
&ModelMaterialSelection::Default
);
}
#[test]
fn legacy_whole_model_policy_migrates_to_explicit_default_slots() {
let manifest = test_manifest();
let mut settings = ImportSettings {
material_policy: MaterialImportPolicy::AuthoringOverride,
..Default::default()
};
reconcile_model_material_slots(&manifest, &mut settings);
assert_eq!(
settings.material_policy,
MaterialImportPolicy::SourceMaterials
);
assert_eq!(settings.material_slots.len(), 1);
assert!(matches!(
settings.material_slots[0].selection,
ModelMaterialSelection::Default
));
}
#[test]
fn renderer_from_manifest_excludes_skinned_primitives() {
let mut manifest = test_manifest();
manifest.parts[0].skinned = true;
let renderer = renderer_from_manifest(&manifest, &ImportSettings::default());
assert!(renderer.slots.is_empty());
}
#[test]
fn renderer_from_manifest_excludes_node_animated_geometry() {
let mut manifest = test_manifest();
manifest.metadata.animation_count = 1;
let renderer = renderer_from_manifest(&manifest, &ImportSettings::default());
assert!(renderer.slots.is_empty());
}
#[test]
fn committed_rigged_fixture_never_builds_static_renderer_slots() {
let path = Path::new(env!("CARGO_MANIFEST_DIR"))
.join("../../assets/models/robot_expressive.glb")
.to_string_lossy()
.into_owned();
let record = AssetRecord {
id: AssetId::new(),
path,
label: "Robot Expressive".into(),
kind: shared::AssetKind::Model,
source_fingerprint: None,
import_settings: shared::AssetImportSettings::Model(ImportSettings::default()),
dependencies: Vec::new(),
};
let manifest = build_static_mesh_manifest(&record).unwrap();
let renderer = renderer_from_manifest(&manifest, record.model_import());
assert!(manifest.metadata.skin_count > 0);
assert!(manifest.metadata.animation_count > 0);
assert!(manifest.parts.iter().any(|part| part.skinned));
assert!(renderer.slots.is_empty());
}
#[test]
fn committed_fbx_records_sibling_texture_dependencies() {
let path = Path::new(env!("CARGO_MANIFEST_DIR"))
.join("../../assets/models/painted_wooden_chair_02_2k.fbx")
.to_string_lossy()
.into_owned();
let record = AssetRecord {
id: AssetId::new(),
path,
label: "Painted Chair".into(),
kind: shared::AssetKind::Model,
source_fingerprint: None,
import_settings: shared::AssetImportSettings::Model(ImportSettings::default()),
dependencies: Vec::new(),
};
let manifest = build_static_mesh_manifest(&record).unwrap();
assert_eq!(manifest.source.dependencies.len(), 3);
assert!(manifest
.source
.dependencies
.iter()
.all(|path| path.contains("assets/models/textures/painted_wooden_chair_02_")));
}
}
+978
View File
@@ -0,0 +1,978 @@
//! Deterministic, GPU-free texture processing for editor, watcher, CI, and packaging.
use image::{imageops::FilterType, Rgba, RgbaImage};
use shared::{
resolves_srgb, AssetKind, AssetRecord, AssetRegistryDocument, MaterialAsset, MaterialInputSet,
MaterialInstanceAsset, MaterialRuntimeData, MaterialTextureBinding, NormalMapConvention,
TextureAssetSemantic, TextureChannel, TextureColorSpace, TextureCompression,
TextureImportSettings, TextureMipmapMode, TextureRuntimeData,
};
use std::path::{Path, PathBuf};
pub const TEXTURE_PROCESSOR_VERSION: u32 = 1;
#[derive(Debug, Clone)]
pub struct TextureArtifactPlan {
pub output_path: PathBuf,
pub output_bytes: Vec<u8>,
pub runtime: TextureRuntimeData,
pub reused: bool,
}
#[derive(Debug, Clone)]
pub struct MaterialArtifactPlan {
pub output_path: PathBuf,
pub output_bytes: Vec<u8>,
pub runtime: MaterialRuntimeData,
pub reused: bool,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct MaterialPackingSignature(pub String);
pub fn plan_texture_artifact(
project_root: &Path,
record: &AssetRecord,
) -> Result<TextureArtifactPlan, String> {
if record.kind != AssetKind::Texture {
return Err(format!("{} is not a Texture asset", record.path));
}
let source_path = project_root.join(&record.path);
let source_bytes = std::fs::read(&source_path)
.map_err(|error| format!("could not read texture {}: {error}", source_path.display()))?;
let mut settings = record
.texture_import()
.cloned()
.ok_or_else(|| format!("{} has no Texture import settings", record.path))?;
normalize_texture_settings(&record.path, &mut settings);
let settings_bytes = ron::ser::to_string(&settings)
.map_err(|error| format!("could not hash Texture import settings: {error}"))?;
let mut hasher = blake3::Hasher::new();
hasher.update(&source_bytes);
hasher.update(settings_bytes.as_bytes());
hasher.update(&TEXTURE_PROCESSOR_VERSION.to_le_bytes());
let processing_key = hasher.finalize().to_hex()[..24].to_string();
let is_srgb = resolves_srgb(&settings);
let extension = match settings.compression {
TextureCompression::Uastc | TextureCompression::Auto => "basis",
TextureCompression::Uncompressed => "ktx2",
};
let relative_output = PathBuf::from(format!(
"assets/.import-cache/runtime/textures/{}/{processing_key}/texture.{extension}",
record.id.as_string()
));
let output_path = project_root.join(&relative_output);
let runtime = TextureRuntimeData {
source_path: record.path.clone(),
processed_path: Some(normalize_path(&relative_output)),
processing_key: Some(processing_key),
settings,
is_srgb,
};
if output_path.is_file() {
return Ok(TextureArtifactPlan {
output_path,
output_bytes: Vec::new(),
runtime,
reused: true,
});
}
let mut image = image::load_from_memory(&source_bytes)
.map_err(|error| format!("could not decode texture {}: {error}", record.path))?
.to_rgba8();
image = resize_to_limit(image, runtime.settings.max_dimension);
if runtime.settings.semantic == TextureAssetSemantic::Normal
&& runtime.settings.normal_map_convention == NormalMapConvention::DirectX
{
flip_normal_green(&mut image);
}
let output_bytes = match runtime.settings.compression {
TextureCompression::Uastc | TextureCompression::Auto => {
let mip_count =
requested_mip_count(image.width(), image.height(), runtime.settings.mipmaps);
encode_uastc(&image, is_srgb, mip_count > 1)?
}
TextureCompression::Uncompressed => {
let mips = generate_mips(&image, runtime.settings.mipmaps);
encode_uncompressed_ktx2(&mips, is_srgb)?
}
};
Ok(TextureArtifactPlan {
output_path,
output_bytes,
runtime,
reused: false,
})
}
pub fn publish_texture_artifact(plan: &TextureArtifactPlan) -> Result<bool, String> {
if plan.reused {
return Ok(false);
}
crate::write_if_changed(&plan.output_path, &plan.output_bytes)
}
pub fn plan_material_artifact(
project_root: &Path,
record: &AssetRecord,
registry: &AssetRegistryDocument,
) -> Result<Option<MaterialArtifactPlan>, String> {
if !matches!(
record.kind,
AssetKind::Material | AssetKind::MaterialInstance
) {
return Ok(None);
}
let inputs = load_resolved_material_inputs(project_root, record)?;
let scalar_bindings = [
assigned_texture(&inputs, "occlusion"),
assigned_texture(&inputs, "roughness"),
assigned_texture(&inputs, "metallic"),
];
if scalar_bindings.iter().all(|binding| binding.is_none()) {
return Ok(None);
}
let signature = material_packing_signature_from_inputs(project_root, registry, &inputs)?;
let processing_key = signature.0;
let relative_output = PathBuf::from(format!(
"assets/.import-cache/runtime/materials/{}/{}-arm.basis",
record.id.as_string(),
processing_key
));
let output_path = project_root.join(&relative_output);
if output_path.is_file() {
return Ok(Some(MaterialArtifactPlan {
output_path,
output_bytes: Vec::new(),
runtime: MaterialRuntimeData {
packed_arm_path: Some(normalize_path(&relative_output)),
processing_key: Some(processing_key),
},
reused: true,
}));
}
let loaded = scalar_bindings
.iter()
.map(|binding| {
(*binding)
.map(|binding| load_binding_image(project_root, registry, binding))
.transpose()
})
.collect::<Result<Vec<_>, _>>()?;
let (width, height) = loaded
.iter()
.flatten()
.map(|(_, image)| (image.width(), image.height()))
.next()
.ok_or_else(|| format!("{} has packed inputs but no readable Texture", record.path))?;
let loaded = loaded
.into_iter()
.map(|entry| {
entry.map(|(bytes, image)| {
let image = if image.width() == width && image.height() == height {
image
} else {
image::imageops::resize(&image, width, height, FilterType::Lanczos3)
};
(bytes, image)
})
})
.collect::<Vec<_>>();
let mut packed = RgbaImage::new(width, height);
for y in 0..height {
for x in 0..width {
let ao = sample_scalar(loaded[0].as_ref(), scalar_bindings[0], x, y, 255);
let roughness = sample_scalar(loaded[1].as_ref(), scalar_bindings[1], x, y, 255);
let metallic = sample_scalar(loaded[2].as_ref(), scalar_bindings[2], x, y, 0);
packed.put_pixel(x, y, Rgba([ao, roughness, metallic, 255]));
}
}
Ok(Some(MaterialArtifactPlan {
output_path,
output_bytes: encode_uastc(&packed, false, true)?,
runtime: MaterialRuntimeData {
packed_arm_path: Some(normalize_path(&relative_output)),
processing_key: Some(processing_key),
},
reused: false,
}))
}
pub fn publish_material_artifact(plan: &MaterialArtifactPlan) -> Result<bool, String> {
if plan.reused {
return Ok(false);
}
crate::write_if_changed(&plan.output_path, &plan.output_bytes)
}
pub fn material_packing_signature(
project_root: &Path,
record: &AssetRecord,
registry: &AssetRegistryDocument,
) -> Result<Option<MaterialPackingSignature>, String> {
if !matches!(
record.kind,
AssetKind::Material | AssetKind::MaterialInstance
) {
return Ok(None);
}
let inputs = load_resolved_material_inputs(project_root, record)?;
if ["occlusion", "roughness", "metallic"]
.into_iter()
.all(|name| assigned_texture(&inputs, name).is_none())
{
return Ok(None);
}
material_packing_signature_from_inputs(project_root, registry, &inputs).map(Some)
}
fn material_packing_signature_from_inputs(
project_root: &Path,
registry: &AssetRegistryDocument,
inputs: &MaterialInputSet,
) -> Result<MaterialPackingSignature, String> {
let mut hasher = blake3::Hasher::new();
hasher.update(&TEXTURE_PROCESSOR_VERSION.to_le_bytes());
for name in ["occlusion", "roughness", "metallic"] {
hasher.update(name.as_bytes());
let Some(binding) = assigned_texture(inputs, name) else {
hasher.update(b"unassigned");
continue;
};
hasher.update(format!("{:?}", binding.channel).as_bytes());
let (path, bytes, settings) = binding_source(project_root, registry, binding)?;
hasher.update(path.as_bytes());
hasher.update(blake3::hash(&bytes).as_bytes());
let settings = ron::ser::to_string(&settings)
.map_err(|error| format!("could not hash Texture import settings: {error}"))?;
hasher.update(settings.as_bytes());
}
Ok(MaterialPackingSignature(
hasher.finalize().to_hex()[..24].to_string(),
))
}
fn assigned_texture<'a>(
inputs: &'a MaterialInputSet,
name: &str,
) -> Option<&'a MaterialTextureBinding> {
inputs
.texture(name)
.filter(|binding| binding.texture.is_some())
}
pub fn apply_material_plan_to_catalog(
catalog: &mut shared::RuntimeContentCatalog,
asset_id: &shared::AssetId,
plan: &MaterialArtifactPlan,
) -> Result<(), String> {
let record = catalog
.records
.iter_mut()
.find(|record| &record.id == asset_id)
.ok_or_else(|| format!("runtime catalog is missing Material asset {asset_id:?}"))?;
record.material = Some(plan.runtime.clone());
Ok(())
}
pub fn apply_texture_plan_to_catalog(
catalog: &mut shared::RuntimeContentCatalog,
asset_id: &shared::AssetId,
plan: &TextureArtifactPlan,
) -> Result<(), String> {
let record = catalog
.records
.iter_mut()
.find(|record| &record.id == asset_id)
.ok_or_else(|| format!("runtime catalog is missing Texture asset {asset_id:?}"))?;
record.texture = Some(plan.runtime.clone());
Ok(())
}
pub fn normalize_texture_settings(path: &str, settings: &mut TextureImportSettings) {
if settings.semantic == TextureAssetSemantic::Auto {
settings.semantic = infer_texture_semantic(path);
}
if settings.color_space == TextureColorSpace::Auto {
settings.color_space = match settings.semantic {
TextureAssetSemantic::Color | TextureAssetSemantic::Ui => TextureColorSpace::Srgb,
TextureAssetSemantic::Auto
| TextureAssetSemantic::Normal
| TextureAssetSemantic::MaskData
| TextureAssetSemantic::Hdr => TextureColorSpace::Linear,
};
}
if settings.compression == TextureCompression::Auto {
settings.compression = if settings.semantic == TextureAssetSemantic::Hdr {
TextureCompression::Uncompressed
} else {
TextureCompression::Uastc
};
}
settings.anisotropy = settings.anisotropy.clamp(1, 16);
settings.max_dimension = settings.max_dimension.filter(|dimension| *dimension > 0);
}
pub fn infer_texture_semantic(path: &str) -> TextureAssetSemantic {
let lowercase = path.to_ascii_lowercase();
if lowercase.ends_with(".hdr") || lowercase.ends_with(".exr") {
TextureAssetSemantic::Hdr
} else if ["_normal", "_nor", "_nrm", "normal.", "nor_gl", "nor_dx"]
.iter()
.any(|marker| lowercase.contains(marker))
{
TextureAssetSemantic::Normal
} else if [
"_arm",
"_orm",
"_rma",
"_mask",
"_rough",
"_metal",
"_ao",
"occlusion",
"height",
]
.iter()
.any(|marker| lowercase.contains(marker))
{
TextureAssetSemantic::MaskData
} else {
TextureAssetSemantic::Color
}
}
fn resize_to_limit(image: RgbaImage, max_dimension: Option<u32>) -> RgbaImage {
let Some(limit) = max_dimension else {
return image;
};
let largest = image.width().max(image.height());
if largest <= limit {
return image;
}
let scale = limit as f64 / largest as f64;
let width = ((image.width() as f64 * scale).round() as u32).max(1);
let height = ((image.height() as f64 * scale).round() as u32).max(1);
image::imageops::resize(&image, width, height, FilterType::Lanczos3)
}
pub fn load_resolved_material_inputs(
project_root: &Path,
record: &AssetRecord,
) -> Result<MaterialInputSet, String> {
let path = project_root.join(&record.path);
match record.kind {
AssetKind::Material => Ok(load_ron::<MaterialAsset>(&path)?.inputs),
AssetKind::MaterialInstance => {
let instance = load_ron::<MaterialInstanceAsset>(&path)?;
let base_path = instance
.base
.0
.source_path
.as_deref()
.ok_or_else(|| format!("{} has no loadable base Material path", record.path))?;
let mut inputs = load_ron::<MaterialAsset>(&project_root.join(base_path))?.inputs;
merge_input_sets(&mut inputs, &instance.overrides);
Ok(inputs)
}
_ => Err(format!("{} is not a Material asset", record.path)),
}
}
/// Returns direct Material Instance consumers of one base Material.
///
/// Blacksite currently supports direct-base instances only, so this is the complete dependency
/// closure for a base Material packing change.
pub fn direct_material_instance_dependents(
project_root: &Path,
registry: &AssetRegistryDocument,
base: &AssetRecord,
) -> Vec<AssetRecord> {
registry
.records
.iter()
.filter(|record| record.kind == AssetKind::MaterialInstance)
.filter_map(|record| {
let instance =
load_ron::<MaterialInstanceAsset>(&project_root.join(&record.path)).ok()?;
reference_targets_record(&instance.base.0, base).then(|| record.clone())
})
.collect()
}
/// Returns project Materials and direct Material Instances whose effective inputs reference a
/// Texture through its stable registry identity (with source path as a guarded legacy fallback).
pub fn material_dependents_of_texture(
project_root: &Path,
registry: &AssetRegistryDocument,
texture: &AssetRecord,
) -> Vec<AssetRecord> {
registry
.records
.iter()
.filter(|record| {
matches!(
record.kind,
AssetKind::Material | AssetKind::MaterialInstance
)
})
.filter_map(|record| {
let inputs = load_resolved_material_inputs(project_root, record).ok()?;
inputs
.textures
.iter()
.filter_map(|binding| binding.texture.as_ref())
.any(|reference| reference_targets_record(reference, texture))
.then(|| record.clone())
})
.collect()
}
fn reference_targets_record(reference: &shared::EditorAssetRef, record: &AssetRecord) -> bool {
(!reference.asset_id.is_empty() && reference.asset_id == record.id.as_string())
|| reference.source_path.as_deref() == Some(record.path.as_str())
}
fn load_ron<T: serde::de::DeserializeOwned>(path: &Path) -> Result<T, String> {
let source = std::fs::read_to_string(path)
.map_err(|error| format!("could not read {}: {error}", path.display()))?;
ron::from_str(&source).map_err(|error| format!("invalid RON in {}: {error}", path.display()))
}
fn merge_input_sets(base: &mut MaterialInputSet, overrides: &MaterialInputSet) {
for value in &overrides.values {
if let Some(existing) = base
.values
.iter_mut()
.find(|entry| entry.name == value.name)
{
*existing = value.clone();
} else {
base.values.push(value.clone());
}
}
for texture in &overrides.textures {
if let Some(existing) = base
.textures
.iter_mut()
.find(|entry| entry.name == texture.name)
{
*existing = texture.clone();
} else {
base.textures.push(texture.clone());
}
}
}
fn load_binding_image(
project_root: &Path,
registry: &AssetRegistryDocument,
binding: &MaterialTextureBinding,
) -> Result<(Vec<u8>, RgbaImage), String> {
let (_, bytes, _) = binding_source(project_root, registry, binding)?;
let image = image::load_from_memory(&bytes)
.map_err(|error| format!("could not decode Texture for {}: {error}", binding.name))?
.to_rgba8();
Ok((bytes, image))
}
fn binding_source(
project_root: &Path,
registry: &AssetRegistryDocument,
binding: &MaterialTextureBinding,
) -> Result<(String, Vec<u8>, TextureImportSettings), String> {
let reference = binding
.texture
.as_ref()
.ok_or_else(|| format!("Material input {} is unassigned", binding.name))?;
let record = registry.records.iter().find(|record| {
record.id.as_string() == reference.asset_id
|| reference
.source_path
.as_deref()
.is_some_and(|path| record.path == path)
});
let path = record
.map(|record| record.path.clone())
.or_else(|| reference.source_path.clone())
.ok_or_else(|| format!("Texture {} has no project path", reference.label))?;
let bytes = std::fs::read(project_root.join(&path))
.map_err(|error| format!("could not read Texture {path}: {error}"))?;
let mut settings = record
.and_then(|record| record.texture_import().cloned())
.unwrap_or_default();
normalize_texture_settings(&path, &mut settings);
Ok((path, bytes, settings))
}
fn sample_scalar(
image: Option<&(Vec<u8>, RgbaImage)>,
binding: Option<&MaterialTextureBinding>,
x: u32,
y: u32,
fallback: u8,
) -> u8 {
let (Some((_, image)), Some(binding)) = (image, binding) else {
return fallback;
};
let pixel = image.get_pixel(x, y).0;
match binding.channel {
TextureChannel::R | TextureChannel::Rgb | TextureChannel::Rgba => pixel[0],
TextureChannel::G => pixel[1],
TextureChannel::B => pixel[2],
TextureChannel::A => pixel[3],
}
}
fn flip_normal_green(image: &mut RgbaImage) {
for pixel in image.pixels_mut() {
pixel.0[1] = 255_u8.saturating_sub(pixel.0[1]);
}
}
fn requested_mip_count(width: u32, height: u32, mode: TextureMipmapMode) -> u32 {
if mode != TextureMipmapMode::Generate {
return 1;
}
width.max(height).ilog2() + 1
}
fn generate_mips(image: &RgbaImage, mode: TextureMipmapMode) -> Vec<RgbaImage> {
let mut levels = vec![image.clone()];
if mode != TextureMipmapMode::Generate {
return levels;
}
while levels
.last()
.is_some_and(|level| level.width() > 1 || level.height() > 1)
{
let previous = levels.last().expect("mip chain has a base level");
let width = (previous.width() / 2).max(1);
let height = (previous.height() / 2).max(1);
levels.push(image::imageops::resize(
previous,
width,
height,
FilterType::Lanczos3,
));
}
levels
}
fn encode_uastc(
image: &RgbaImage,
is_srgb: bool,
generate_mipmaps: bool,
) -> Result<Vec<u8>, String> {
let mut params = basis_universal::CompressorParams::new();
params.set_basis_format(basis_universal::BasisTextureFormat::UASTC4x4);
params.set_uastc_quality_level(basis_universal::UASTC_QUALITY_DEFAULT);
params.set_generate_mipmaps(generate_mipmaps);
params.set_print_status_to_stdout(false);
params.set_color_space(if is_srgb {
basis_universal::ColorSpace::Srgb
} else {
basis_universal::ColorSpace::Linear
});
params
.source_image_mut(0)
.init(image.as_raw(), image.width(), image.height(), 4);
let mut compressor = basis_universal::Compressor::new(4);
// SAFETY: the image is tightly packed RGBA8 and all compressor parameters above are valid.
unsafe {
compressor.init(&params);
compressor
.process()
.map_err(|error| format!("UASTC compression failed: {error:?}"))?;
}
Ok(compressor.basis_file().to_vec())
}
fn encode_uncompressed_ktx2(mips: &[RgbaImage], is_srgb: bool) -> Result<Vec<u8>, String> {
let Some(base) = mips.first() else {
return Err("cannot encode an empty mip chain".into());
};
let level_count = u32::try_from(mips.len()).map_err(|_| "too many mip levels".to_string())?;
let dfd = rgba8_data_format_descriptor(is_srgb);
let header_len = 80_usize;
let level_index_len = mips.len() * 24;
let dfd_offset = header_len + level_index_len;
let data_offset = align_to(dfd_offset + dfd.len(), 8);
let mut level_offsets = Vec::with_capacity(mips.len());
let mut cursor = data_offset;
for level in mips {
cursor = align_to(cursor, 8);
level_offsets.push(cursor);
cursor += level.as_raw().len();
}
let mut bytes = Vec::with_capacity(cursor);
bytes.extend_from_slice(&[
0xAB, 0x4B, 0x54, 0x58, 0x20, 0x32, 0x30, 0xBB, 0x0D, 0x0A, 0x1A, 0x0A,
]);
push_u32(&mut bytes, if is_srgb { 43 } else { 37 });
push_u32(&mut bytes, 1);
push_u32(&mut bytes, base.width());
push_u32(&mut bytes, base.height());
push_u32(&mut bytes, 0);
push_u32(&mut bytes, 0);
push_u32(&mut bytes, 1);
push_u32(&mut bytes, level_count);
push_u32(&mut bytes, 0);
push_u32(
&mut bytes,
u32::try_from(dfd_offset).map_err(|_| "KTX2 is too large".to_string())?,
);
push_u32(&mut bytes, u32::try_from(dfd.len()).unwrap_or(u32::MAX));
push_u32(&mut bytes, 0);
push_u32(&mut bytes, 0);
push_u64(&mut bytes, 0);
push_u64(&mut bytes, 0);
for (level, offset) in mips.iter().zip(&level_offsets) {
push_u64(
&mut bytes,
u64::try_from(*offset).map_err(|_| "KTX2 is too large".to_string())?,
);
push_u64(&mut bytes, level.as_raw().len() as u64);
push_u64(&mut bytes, level.as_raw().len() as u64);
}
bytes.extend_from_slice(&dfd);
bytes.resize(data_offset, 0);
for (level, offset) in mips.iter().zip(level_offsets) {
bytes.resize(offset, 0);
bytes.extend_from_slice(level.as_raw());
}
Ok(bytes)
}
fn rgba8_data_format_descriptor(is_srgb: bool) -> Vec<u8> {
let mut dfd = Vec::with_capacity(92);
push_u32(&mut dfd, 92);
push_u16(&mut dfd, 0);
push_u16(&mut dfd, 0);
push_u16(&mut dfd, 2);
push_u16(&mut dfd, 88);
dfd.extend_from_slice(&[1, 1, if is_srgb { 2 } else { 1 }, 0]);
dfd.extend_from_slice(&[0, 0, 0, 0]);
dfd.extend_from_slice(&[4, 0, 0, 0, 0, 0, 0, 0]);
for (bit_offset, channel) in [(0_u16, 0_u8), (8, 1), (16, 2), (24, 15)] {
push_u16(&mut dfd, bit_offset);
dfd.extend_from_slice(&[7, channel]);
dfd.extend_from_slice(&[0, 0, 0, 0]);
push_u32(&mut dfd, 0);
push_u32(&mut dfd, 255);
}
dfd
}
fn align_to(value: usize, alignment: usize) -> usize {
value.div_ceil(alignment) * alignment
}
fn push_u16(bytes: &mut Vec<u8>, value: u16) {
bytes.extend_from_slice(&value.to_le_bytes());
}
fn push_u32(bytes: &mut Vec<u8>, value: u32) {
bytes.extend_from_slice(&value.to_le_bytes());
}
fn push_u64(bytes: &mut Vec<u8>, value: u64) {
bytes.extend_from_slice(&value.to_le_bytes());
}
fn normalize_path(path: &Path) -> String {
path.to_string_lossy().replace('\\', "/")
}
#[cfg(test)]
mod tests {
use super::*;
use image::Rgba;
use shared::{
AssetId, AssetImportSettings, EditorAssetRef, MaterialParameter, MaterialParameterValue,
MaterialRef, ShaderRefDesc,
};
use uuid::Uuid;
fn test_root(name: &str) -> PathBuf {
std::env::temp_dir().join(format!(
"blacksite-texture-{name}-{}-{}",
std::process::id(),
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap()
.as_nanos()
))
}
fn record(id: u128, path: &str, kind: AssetKind) -> AssetRecord {
AssetRecord {
id: AssetId(Uuid::from_u128(id)),
path: path.into(),
label: path.into(),
kind,
source_fingerprint: None,
import_settings: if kind == AssetKind::Texture {
AssetImportSettings::Texture(TextureImportSettings::default())
} else {
AssetImportSettings::None
},
dependencies: Vec::new(),
}
}
fn material(label: &str, texture: Option<EditorAssetRef>, metallic: f32) -> MaterialAsset {
MaterialAsset {
schema_version: shared::MATERIAL_ASSET_SCHEMA_VERSION,
label: label.into(),
shader: ShaderRefDesc::default(),
shader_ref: None,
render_state: Default::default(),
provenance: None,
inputs: MaterialInputSet {
values: vec![MaterialParameter {
name: "metallic".into(),
value: MaterialParameterValue::Float(metallic),
}],
textures: texture
.map(|texture| MaterialTextureBinding {
name: "metallic".into(),
texture: Some(texture),
channel: TextureChannel::B,
})
.into_iter()
.collect(),
},
}
}
fn write_ron(path: &Path, value: &impl serde::Serialize) {
std::fs::create_dir_all(path.parent().unwrap()).unwrap();
std::fs::write(
path,
ron::ser::to_string_pretty(value, ron::ser::PrettyConfig::default()).unwrap(),
)
.unwrap();
}
#[test]
fn infers_poly_haven_texture_roles() {
assert_eq!(
infer_texture_semantic("metal_office_desk_diff_2k.jpg"),
TextureAssetSemantic::Color
);
assert_eq!(
infer_texture_semantic("metal_office_desk_nor_gl_2k.png"),
TextureAssetSemantic::Normal
);
assert_eq!(
infer_texture_semantic("metal_office_desk_arm_2k.jpg"),
TextureAssetSemantic::MaskData
);
}
#[test]
fn normal_y_conversion_is_exact() {
let mut image = RgbaImage::from_pixel(1, 1, Rgba([1, 64, 3, 255]));
flip_normal_green(&mut image);
assert_eq!(image.get_pixel(0, 0).0, [1, 191, 3, 255]);
}
#[test]
fn uncompressed_ktx2_contains_all_mips() {
let image = RgbaImage::from_pixel(4, 2, Rgba([1, 2, 3, 4]));
let mips = generate_mips(&image, TextureMipmapMode::Generate);
let encoded = encode_uncompressed_ktx2(&mips, false).expect("KTX2 should encode");
assert_eq!(
&encoded[..12],
&[0xAB, 0x4B, 0x54, 0x58, 0x20, 0x32, 0x30, 0xBB, 0x0D, 0x0A, 0x1A, 0x0A]
);
assert_eq!(u32::from_le_bytes(encoded[40..44].try_into().unwrap()), 3);
}
#[test]
fn existing_texture_artifact_is_reused_before_source_decode() {
let root = test_root("texture-reuse");
let texture = record(21, "assets/textures/cached.png", AssetKind::Texture);
let source_bytes = b"intentionally not an image";
std::fs::create_dir_all(root.join("assets/textures")).unwrap();
std::fs::write(root.join(&texture.path), source_bytes).unwrap();
let mut settings = texture.texture_import().cloned().unwrap();
normalize_texture_settings(&texture.path, &mut settings);
let settings_bytes = ron::ser::to_string(&settings).unwrap();
let mut hasher = blake3::Hasher::new();
hasher.update(source_bytes);
hasher.update(settings_bytes.as_bytes());
hasher.update(&TEXTURE_PROCESSOR_VERSION.to_le_bytes());
let processing_key = &hasher.finalize().to_hex()[..24];
let output = root.join(format!(
"assets/.import-cache/runtime/textures/{}/{processing_key}/texture.basis",
texture.id.as_string()
));
std::fs::create_dir_all(output.parent().unwrap()).unwrap();
std::fs::write(&output, b"cached artifact").unwrap();
let plan = plan_texture_artifact(&root, &texture).unwrap();
assert!(plan.reused);
assert!(plan.output_bytes.is_empty());
assert_eq!(plan.output_path, output);
std::fs::remove_dir_all(root).unwrap();
}
#[test]
fn packing_signature_ignores_owner_and_scalar_multipliers() {
let root = test_root("signature");
let texture = record(1, "assets/textures/arm.bin", AssetKind::Texture);
std::fs::create_dir_all(root.join("assets/textures")).unwrap();
std::fs::write(root.join(&texture.path), b"stable packed source").unwrap();
let texture_ref = EditorAssetRef::new(texture.id.as_string(), "texture:source", "ARM")
.with_source_path(&texture.path);
let first = record(2, "assets/materials/first.ron", AssetKind::Material);
let second = record(3, "assets/materials/second.ron", AssetKind::Material);
write_ron(
&root.join(&first.path),
&material("First", Some(texture_ref.clone()), 0.1),
);
write_ron(
&root.join(&second.path),
&material("Second", Some(texture_ref), 0.9),
);
let registry = AssetRegistryDocument {
records: vec![texture, first.clone(), second.clone()],
..Default::default()
};
assert_eq!(
material_packing_signature(&root, &first, &registry).unwrap(),
material_packing_signature(&root, &second, &registry).unwrap(),
"owner identity and scalar multipliers must not invalidate identical packed data"
);
std::fs::remove_dir_all(root).unwrap();
}
#[test]
fn unassigned_scalar_texture_rows_do_not_request_packing() {
let root = test_root("unassigned-packing");
let material_record = record(22, "assets/materials/plain.ron", AssetKind::Material);
let mut authored = material("Plain", None, 0.5);
authored.inputs.textures.push(MaterialTextureBinding {
name: "occlusion".into(),
texture: None,
channel: TextureChannel::R,
});
write_ron(&root.join(&material_record.path), &authored);
let registry = AssetRegistryDocument {
records: vec![material_record.clone()],
..Default::default()
};
assert!(
material_packing_signature(&root, &material_record, &registry)
.unwrap()
.is_none()
);
assert!(plan_material_artifact(&root, &material_record, &registry)
.unwrap()
.is_none());
std::fs::remove_dir_all(root).unwrap();
}
#[test]
fn existing_material_artifact_is_reused_before_texture_decode() {
let root = test_root("material-reuse");
let texture = record(31, "assets/textures/arm.bin", AssetKind::Texture);
let material_record = record(32, "assets/materials/cached.ron", AssetKind::Material);
std::fs::create_dir_all(root.join("assets/textures")).unwrap();
std::fs::write(root.join(&texture.path), b"intentionally not an image").unwrap();
let texture_ref = EditorAssetRef::new(texture.id.as_string(), "texture:source", "ARM")
.with_source_path(&texture.path);
write_ron(
&root.join(&material_record.path),
&material("Cached", Some(texture_ref), 1.0),
);
let registry = AssetRegistryDocument {
records: vec![texture, material_record.clone()],
..Default::default()
};
let signature = material_packing_signature(&root, &material_record, &registry)
.unwrap()
.unwrap();
let output = root.join(format!(
"assets/.import-cache/runtime/materials/{}/{}-arm.basis",
material_record.id.as_string(),
signature.0
));
std::fs::create_dir_all(output.parent().unwrap()).unwrap();
std::fs::write(&output, b"cached artifact").unwrap();
let plan = plan_material_artifact(&root, &material_record, &registry)
.unwrap()
.unwrap();
assert!(plan.reused);
assert!(plan.output_bytes.is_empty());
assert_eq!(plan.output_path, output);
std::fs::remove_dir_all(root).unwrap();
}
#[test]
fn dependency_closure_uses_stable_material_and_texture_references() {
let root = test_root("dependencies");
let texture = record(11, "assets/textures/arm.bin", AssetKind::Texture);
let base = record(12, "assets/materials/base.ron", AssetKind::Material);
let instance = record(
13,
"assets/materials/base_instance.ron",
AssetKind::MaterialInstance,
);
let unrelated = record(14, "assets/materials/unrelated.ron", AssetKind::Material);
let texture_ref = EditorAssetRef::new(texture.id.as_string(), "texture:source", "ARM")
.with_source_path(&texture.path);
write_ron(
&root.join(&base.path),
&material("Base", Some(texture_ref), 1.0),
);
write_ron(
&root.join(&unrelated.path),
&material("Unrelated", None, 1.0),
);
write_ron(
&root.join(&instance.path),
&MaterialInstanceAsset {
schema_version: shared::MATERIAL_INSTANCE_SCHEMA_VERSION,
label: "Base Instance".into(),
base: MaterialRef::new(
EditorAssetRef::new(base.id.as_string(), "material:source", "Base")
.with_source_path(&base.path),
),
overrides: MaterialInputSet::default(),
},
);
let registry = AssetRegistryDocument {
records: vec![texture.clone(), base.clone(), instance.clone(), unrelated],
..Default::default()
};
assert_eq!(
direct_material_instance_dependents(&root, &registry, &base)
.into_iter()
.map(|record| record.id)
.collect::<Vec<_>>(),
vec![instance.id.clone()]
);
let dependents = material_dependents_of_texture(&root, &registry, &texture)
.into_iter()
.map(|record| record.id)
.collect::<Vec<_>>();
assert!(dependents.contains(&base.id));
assert!(dependents.contains(&instance.id));
assert_eq!(dependents.len(), 2);
std::fs::remove_dir_all(root).unwrap();
}
}
File diff suppressed because it is too large. Load diff
+605
View File
@@ -0,0 +1,605 @@
use crate::{
serialize_registry, serialize_runtime_catalog, validate_asset_path, write_if_changed,
REGISTRY_PATH, RUNTIME_CATALOG_PATH,
};
use serde::{Deserialize, Serialize};
use shared::{AssetRecord, AssetRegistryDocument};
use std::fs;
use std::path::{Path, PathBuf};
use std::time::{SystemTime, UNIX_EPOCH};
const TRASH_ROOT: &str = "assets/.trash";
const TRASH_MANIFEST: &str = ".blacksite-trash.ron";
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct TrashManifest {
pub schema_version: u32,
pub batch_id: String,
pub original_paths: Vec<String>,
#[serde(default)]
pub derived_paths: Vec<String>,
pub records: Vec<AssetRecord>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TrashBatchSummary {
pub path: PathBuf,
pub batch_id: String,
pub original_paths: Vec<String>,
}
pub fn trash_content(
project_root: &Path,
original_paths: &[PathBuf],
registry: &mut AssetRegistryDocument,
) -> Result<TrashBatchSummary, String> {
let originals = normalize_originals(project_root, original_paths)?;
let batch_id = trash_batch_id();
let batch_path = PathBuf::from(TRASH_ROOT).join(&batch_id);
let absolute_batch = project_root.join(&batch_path);
fs::create_dir_all(&absolute_batch)
.map_err(|error| format!("could not create {}: {error}", absolute_batch.display()))?;
let records = registry
.records
.iter()
.filter(|record| originals.iter().any(|path| descendant(&record.path, path)))
.cloned()
.collect::<Vec<_>>();
let derived_paths = collect_derived_paths(project_root, &records, &originals)?;
let manifest = TrashManifest {
schema_version: 2,
batch_id: batch_id.clone(),
original_paths: originals.clone(),
derived_paths,
records,
};
let original_registry = registry.clone();
let registry_path = project_root.join(REGISTRY_PATH);
let original_registry_bytes = fs::read(&registry_path).ok();
let runtime_path = project_root.join(RUNTIME_CATALOG_PATH);
let original_runtime_bytes = fs::read(&runtime_path).ok();
let mut moved = Vec::new();
let result: Result<(), String> = (|| {
for original in &originals {
let source = project_root.join(original);
let destination = absolute_batch.join(original);
if let Some(parent) = destination.parent() {
fs::create_dir_all(parent)
.map_err(|error| format!("could not create {}: {error}", parent.display()))?;
}
fs::rename(&source, &destination).map_err(|error| {
format!(
"could not move {} to {}: {error}",
source.display(),
destination.display()
)
})?;
moved.push((source, destination));
}
for derived in &manifest.derived_paths {
let source = project_root.join(derived);
let destination = absolute_batch.join(derived);
if let Some(parent) = destination.parent() {
fs::create_dir_all(parent)
.map_err(|error| format!("could not create {}: {error}", parent.display()))?;
}
fs::rename(&source, &destination).map_err(|error| {
format!(
"could not move derived artifact {} to trash: {error}",
source.display()
)
})?;
moved.push((source, destination));
}
let manifest_ron = ron::ser::to_string_pretty(&manifest, ron::ser::PrettyConfig::default())
.map_err(|error| format!("could not serialize trash manifest: {error}"))?;
fs::write(absolute_batch.join(TRASH_MANIFEST), manifest_ron)
.map_err(|error| format!("could not write trash manifest: {error}"))?;
registry
.records
.retain(|record| !originals.iter().any(|path| descendant(&record.path, path)));
write_if_changed(&registry_path, &serialize_registry(registry)?)?;
write_runtime_catalog(&runtime_path, registry)?;
Ok(())
})();
if let Err(error) = result {
rollback_moves(moved);
restore_registry(&registry_path, original_registry_bytes.as_deref());
restore_registry(&runtime_path, original_runtime_bytes.as_deref());
*registry = original_registry;
let _ = fs::remove_dir_all(&absolute_batch);
return Err(format!("trash transaction rolled back: {error}"));
}
Ok(TrashBatchSummary {
path: batch_path,
batch_id,
original_paths: originals,
})
}
pub fn list_trash_batches(project_root: &Path) -> Result<Vec<TrashBatchSummary>, String> {
let root = project_root.join(TRASH_ROOT);
if !root.exists() {
return Ok(Vec::new());
}
let mut batches = Vec::new();
for entry in fs::read_dir(&root)
.map_err(|error| format!("could not inspect {}: {error}", root.display()))?
{
let entry = entry.map_err(|error| format!("could not inspect trash entry: {error}"))?;
if !entry
.file_type()
.map_err(|error| format!("could not inspect trash entry: {error}"))?
.is_dir()
{
continue;
}
let absolute = entry.path();
let manifest = load_or_infer_manifest(&absolute)?;
batches.push(TrashBatchSummary {
path: PathBuf::from(TRASH_ROOT).join(&manifest.batch_id),
batch_id: manifest.batch_id,
original_paths: manifest.original_paths,
});
}
batches.sort_by(|left, right| right.batch_id.cmp(&left.batch_id));
Ok(batches)
}
pub fn restore_trash_batch(
project_root: &Path,
batch_path: &Path,
registry: &mut AssetRegistryDocument,
) -> Result<TrashBatchSummary, String> {
let normalized_batch = normalize(batch_path);
if !normalized_batch.starts_with("assets/.trash/") {
return Err("restore path must identify a managed trash batch".into());
}
let absolute_batch = project_root.join(batch_path);
let manifest = load_or_infer_manifest(&absolute_batch)?;
for original in &manifest.original_paths {
validate_asset_path(Path::new(original))?;
if project_root.join(original).exists() {
return Err(format!("restore collision: {original} already exists"));
}
if !trashed_source(&absolute_batch, original).exists() {
return Err(format!("trash batch is missing {original}"));
}
}
for derived in &manifest.derived_paths {
validate_derived_path(Path::new(derived))?;
if project_root.join(derived).exists() {
return Err(format!("restore collision: {derived} already exists"));
}
if !trashed_source(&absolute_batch, derived).exists() {
return Err(format!("trash batch is missing derived artifact {derived}"));
}
}
for record in &manifest.records {
if registry
.records
.iter()
.any(|existing| existing.path == record.path || existing.id == record.id)
{
return Err(format!(
"registry collision prevents restoring {}",
record.path
));
}
}
let original_registry = registry.clone();
let registry_path = project_root.join(REGISTRY_PATH);
let original_registry_bytes = fs::read(&registry_path).ok();
let runtime_path = project_root.join(RUNTIME_CATALOG_PATH);
let original_runtime_bytes = fs::read(&runtime_path).ok();
let mut moved = Vec::new();
let result: Result<(), String> = (|| {
for original in &manifest.original_paths {
let source = trashed_source(&absolute_batch, original);
let destination = project_root.join(original);
if let Some(parent) = destination.parent() {
fs::create_dir_all(parent)
.map_err(|error| format!("could not create {}: {error}", parent.display()))?;
}
fs::rename(&source, &destination).map_err(|error| {
format!(
"could not restore {} to {}: {error}",
source.display(),
destination.display()
)
})?;
moved.push((source, destination));
}
for derived in &manifest.derived_paths {
let source = trashed_source(&absolute_batch, derived);
let destination = project_root.join(derived);
if let Some(parent) = destination.parent() {
fs::create_dir_all(parent)
.map_err(|error| format!("could not create {}: {error}", parent.display()))?;
}
fs::rename(&source, &destination).map_err(|error| {
format!(
"could not restore derived artifact {} to {}: {error}",
source.display(),
destination.display()
)
})?;
moved.push((source, destination));
}
registry.records.extend(manifest.records.iter().cloned());
registry
.records
.sort_by(|left, right| left.path.cmp(&right.path));
write_if_changed(&registry_path, &serialize_registry(registry)?)?;
write_runtime_catalog(&runtime_path, registry)?;
Ok(())
})();
if let Err(error) = result {
rollback_moves(moved);
restore_registry(&registry_path, original_registry_bytes.as_deref());
restore_registry(&runtime_path, original_runtime_bytes.as_deref());
*registry = original_registry;
return Err(format!("restore transaction rolled back: {error}"));
}
let _ = fs::remove_dir_all(&absolute_batch);
Ok(TrashBatchSummary {
path: batch_path.to_path_buf(),
batch_id: manifest.batch_id,
original_paths: manifest.original_paths,
})
}
fn normalize_originals(project_root: &Path, paths: &[PathBuf]) -> Result<Vec<String>, String> {
if paths.is_empty() {
return Err("no content paths were selected for trash".into());
}
let mut originals: Vec<String> = Vec::new();
for path in paths {
validate_asset_path(path)?;
let normalized = normalize(path);
if !project_root.join(path).exists() {
return Err(format!("content path does not exist: {}", path.display()));
}
if originals
.iter()
.any(|parent| descendant(&normalized, parent))
{
continue;
}
originals.retain(|child| !descendant(child, &normalized));
originals.push(normalized);
}
originals.sort();
Ok(originals)
}
fn load_or_infer_manifest(batch: &Path) -> Result<TrashManifest, String> {
let manifest_path = batch.join(TRASH_MANIFEST);
if let Ok(text) = fs::read_to_string(&manifest_path) {
return ron::from_str(&text).map_err(|error| {
format!(
"invalid trash manifest {}: {error}",
manifest_path.display()
)
});
}
let batch_id = batch
.file_name()
.and_then(|name| name.to_str())
.unwrap_or("legacy")
.to_string();
let scan_root = if batch.join("assets").is_dir() {
batch.join("assets")
} else {
batch.to_path_buf()
};
let mut original_paths = Vec::new();
for entry in fs::read_dir(&scan_root)
.map_err(|error| format!("could not inspect legacy trash batch: {error}"))?
{
let entry =
entry.map_err(|error| format!("could not inspect legacy trash item: {error}"))?;
if entry.file_name() == TRASH_MANIFEST {
continue;
}
original_paths.push(format!("assets/{}", entry.file_name().to_string_lossy()));
}
original_paths.sort();
Ok(TrashManifest {
schema_version: 0,
batch_id,
original_paths,
derived_paths: Vec::new(),
records: Vec::new(),
})
}
fn collect_derived_paths(
project_root: &Path,
records: &[AssetRecord],
originals: &[String],
) -> Result<Vec<String>, String> {
let mut derived = Vec::new();
for record in records {
let Some(settings) = record.import_settings.model() else {
continue;
};
for path in [
settings.static_mesh_manifest_path.as_deref(),
settings.animation_manifest_path.as_deref(),
]
.into_iter()
.flatten()
{
validate_derived_path(Path::new(path))?;
if originals.iter().any(|original| descendant(path, original)) {
continue;
}
let absolute = project_root.join(path);
let Ok(metadata) = fs::symlink_metadata(&absolute) else {
continue;
};
if metadata.file_type().is_symlink() {
return Err(format!(
"derived artifact may not be a symlink: {}",
absolute.display()
));
}
if metadata.is_file() {
derived.push(path.to_string());
}
}
}
derived.sort();
derived.dedup();
Ok(derived)
}
fn validate_derived_path(path: &Path) -> Result<(), String> {
if validate_asset_path(path).is_ok() {
return Ok(());
}
if path.is_absolute()
|| path.components().any(|component| {
matches!(
component,
std::path::Component::ParentDir
| std::path::Component::RootDir
| std::path::Component::Prefix(_)
)
})
{
return Err("derived artifact paths must remain project-relative".into());
}
let normalized = normalize(path);
if descendant(&normalized, "assets/meshes/generated")
|| descendant(&normalized, "assets/animations/generated")
{
Ok(())
} else {
Err(format!(
"unsupported derived artifact path outside generated manifest roots: {normalized}"
))
}
}
fn trashed_source(batch: &Path, original: &str) -> PathBuf {
let preserved = batch.join(original);
if preserved.exists() {
preserved
} else {
batch.join(original.strip_prefix("assets/").unwrap_or(original))
}
}
fn rollback_moves(moved: Vec<(PathBuf, PathBuf)>) {
for (source, destination) in moved.into_iter().rev() {
if let Some(parent) = source.parent() {
let _ = fs::create_dir_all(parent);
}
let _ = fs::rename(destination, source);
}
}
fn restore_registry(path: &Path, bytes: Option<&[u8]>) {
if let Some(bytes) = bytes {
let _ = fs::write(path, bytes);
} else {
let _ = fs::remove_file(path);
}
}
fn write_runtime_catalog(path: &Path, registry: &AssetRegistryDocument) -> Result<(), String> {
let catalog = shared::RuntimeContentCatalog::from(registry);
write_if_changed(path, &serialize_runtime_catalog(&catalog)?)?;
Ok(())
}
fn trash_batch_id() -> String {
SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|duration| format!("{}-{:09}", duration.as_secs(), duration.subsec_nanos()))
.unwrap_or_else(|_| "now".into())
}
fn normalize(path: &Path) -> String {
path.to_string_lossy().replace('\\', "/")
}
fn descendant(path: &str, parent: &str) -> bool {
path == parent
|| path
.strip_prefix(parent)
.is_some_and(|suffix| suffix.starts_with('/'))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn trash_and_restore_preserve_bytes_and_registry_ids() {
let root = std::env::temp_dir().join(format!(
"blacksite-trash-{}",
shared::AssetId::new().as_string()
));
fs::create_dir_all(root.join("assets/Props")).unwrap();
fs::create_dir_all(root.join("assets/.index")).unwrap();
fs::write(root.join("assets/Props/box.png"), b"asset bytes").unwrap();
let record = AssetRecord {
id: shared::AssetId::new(),
path: "assets/Props/box.png".into(),
label: "Box".into(),
kind: shared::AssetKind::Texture,
source_fingerprint: None,
import_settings: shared::AssetImportSettings::for_kind(shared::AssetKind::Texture),
dependencies: Vec::new(),
};
let mut registry = AssetRegistryDocument {
records: vec![record.clone()],
..Default::default()
};
fs::write(
root.join(REGISTRY_PATH),
serialize_registry(&registry).unwrap(),
)
.unwrap();
let batch = trash_content(
&root,
&[PathBuf::from("assets/Props/box.png")],
&mut registry,
)
.unwrap();
assert!(!root.join("assets/Props/box.png").exists());
assert!(registry.records.is_empty());
restore_trash_batch(&root, &batch.path, &mut registry).unwrap();
assert_eq!(
fs::read(root.join("assets/Props/box.png")).unwrap(),
b"asset bytes"
);
assert_eq!(registry.records, vec![record]);
fs::remove_dir_all(root).unwrap();
}
#[test]
fn trash_and_restore_include_model_derived_manifests() {
let root = std::env::temp_dir().join(format!(
"blacksite-trash-derived-{}",
shared::AssetId::new().as_string()
));
fs::create_dir_all(root.join("assets/Props")).unwrap();
fs::create_dir_all(root.join("assets/meshes/generated")).unwrap();
fs::create_dir_all(root.join("assets/animations/generated")).unwrap();
fs::create_dir_all(root.join("assets/.index")).unwrap();
fs::write(root.join("assets/Props/desk.glb"), b"model bytes").unwrap();
fs::write(
root.join("assets/meshes/generated/desk.static_mesh.ron"),
b"static manifest",
)
.unwrap();
fs::write(
root.join("assets/animations/generated/desk.animation.ron"),
b"animation manifest",
)
.unwrap();
let mut record = AssetRecord {
id: shared::AssetId::new(),
path: "assets/Props/desk.glb".into(),
label: "Desk".into(),
kind: shared::AssetKind::Model,
source_fingerprint: None,
import_settings: shared::AssetImportSettings::Model(shared::ImportSettings::default()),
dependencies: Vec::new(),
};
record.model_import_mut().static_mesh_manifest_path =
Some("assets/meshes/generated/desk.static_mesh.ron".into());
record.model_import_mut().animation_manifest_path =
Some("assets/animations/generated/desk.animation.ron".into());
let mut registry = AssetRegistryDocument {
records: vec![record.clone()],
..Default::default()
};
fs::write(
root.join(REGISTRY_PATH),
serialize_registry(&registry).unwrap(),
)
.unwrap();
let batch = trash_content(
&root,
&[PathBuf::from("assets/Props/desk.glb")],
&mut registry,
)
.unwrap();
assert!(!root.join("assets/Props/desk.glb").exists());
assert!(!root
.join("assets/meshes/generated/desk.static_mesh.ron")
.exists());
assert!(!root
.join("assets/animations/generated/desk.animation.ron")
.exists());
let manifest: TrashManifest = ron::from_str(
&fs::read_to_string(root.join(&batch.path).join(TRASH_MANIFEST)).unwrap(),
)
.unwrap();
assert_eq!(manifest.schema_version, 2);
assert_eq!(
manifest.derived_paths,
vec![
"assets/animations/generated/desk.animation.ron",
"assets/meshes/generated/desk.static_mesh.ron",
]
);
restore_trash_batch(&root, &batch.path, &mut registry).unwrap();
assert_eq!(
fs::read(root.join("assets/Props/desk.glb")).unwrap(),
b"model bytes"
);
assert_eq!(
fs::read(root.join("assets/meshes/generated/desk.static_mesh.ron")).unwrap(),
b"static manifest"
);
assert_eq!(
fs::read(root.join("assets/animations/generated/desk.animation.ron")).unwrap(),
b"animation manifest"
);
assert_eq!(registry.records, vec![record]);
fs::remove_dir_all(root).unwrap();
}
#[test]
fn restore_collision_keeps_trash_untouched() {
let root = std::env::temp_dir().join(format!(
"blacksite-trash-{}",
shared::AssetId::new().as_string()
));
fs::create_dir_all(root.join("assets/Props")).unwrap();
fs::create_dir_all(root.join("assets/.index")).unwrap();
fs::write(root.join("assets/Props/box.png"), b"original").unwrap();
let mut registry = AssetRegistryDocument::default();
fs::write(
root.join(REGISTRY_PATH),
serialize_registry(&registry).unwrap(),
)
.unwrap();
let batch = trash_content(
&root,
&[PathBuf::from("assets/Props/box.png")],
&mut registry,
)
.unwrap();
fs::write(root.join("assets/Props/box.png"), b"external").unwrap();
assert!(restore_trash_batch(&root, &batch.path, &mut registry).is_err());
assert_eq!(
fs::read(root.join("assets/Props/box.png")).unwrap(),
b"external"
);
assert!(root.join(&batch.path).join("assets/Props/box.png").exists());
fs::remove_dir_all(root).unwrap();
}
}
+187
View File
@@ -0,0 +1,187 @@
//! Debounced project-content watching shared by editor hosts and automation.
use notify::{RecommendedWatcher, RecursiveMode, Watcher};
use std::collections::{BTreeMap, BTreeSet};
use std::path::{Path, PathBuf};
use std::sync::mpsc::{self, Receiver};
use std::time::{Duration, Instant};
#[derive(Debug, Default)]
pub struct DebouncedContentChanges {
paths: BTreeSet<PathBuf>,
last_change: Option<Instant>,
suppressed: usize,
}
impl DebouncedContentChanges {
pub fn begin_transaction(&mut self) {
self.suppressed += 1;
}
pub fn end_transaction(&mut self) {
self.suppressed = self.suppressed.saturating_sub(1);
}
pub fn record(&mut self, path: PathBuf, now: Instant) {
if self.suppressed == 0 {
self.paths.insert(path);
self.last_change = Some(now);
}
}
pub fn take_ready(&mut self, now: Instant, debounce: Duration) -> Vec<PathBuf> {
if self.suppressed > 0
|| self
.last_change
.is_none_or(|last_change| now.duration_since(last_change) < debounce)
{
return Vec::new();
}
self.last_change = None;
std::mem::take(&mut self.paths).into_iter().collect()
}
}
pub struct ContentWatchService {
_watcher: RecommendedWatcher,
events: Receiver<notify::Result<notify::Event>>,
changes: DebouncedContentChanges,
assets_root: PathBuf,
suppressed_paths: BTreeMap<PathBuf, Instant>,
}
impl ContentWatchService {
pub fn watch_project(project_root: &Path) -> Result<Self, String> {
let (sender, events) = mpsc::channel();
let mut watcher = notify::recommended_watcher(move |event| {
let _ = sender.send(event);
})
.map_err(|error| format!("could not create content watcher: {error}"))?;
let assets = project_root.join(crate::ASSETS_DIRECTORY);
watcher
.watch(&assets, RecursiveMode::Recursive)
.map_err(|error| format!("could not watch {}: {error}", assets.display()))?;
Ok(Self {
_watcher: watcher,
events,
changes: DebouncedContentChanges::default(),
assets_root: assets,
suppressed_paths: BTreeMap::new(),
})
}
pub fn begin_transaction(&mut self) {
self.changes.begin_transaction();
}
pub fn end_transaction(&mut self) {
while self.events.try_recv().is_ok() {}
self.changes.end_transaction();
}
/// Ignores watcher noise for one host-authored file while direct runtime consumers observe
/// its new revision. This prevents an inline Material slider edit from starting a full project
/// processing pass without hiding unrelated external changes.
pub fn suppress_path(&mut self, path: &Path, duration: Duration) {
let path = if path.is_absolute() {
path.to_path_buf()
} else {
self.assets_root
.parent()
.unwrap_or(&self.assets_root)
.join(path)
};
self.suppressed_paths
.insert(path, Instant::now() + duration);
}
/// Drains host events and returns one deterministic path set after the debounce window.
pub fn poll(&mut self, debounce: Duration) -> Result<Vec<PathBuf>, String> {
let now = Instant::now();
self.suppressed_paths.retain(|_, deadline| *deadline >= now);
while let Ok(event) = self.events.try_recv() {
let event = event.map_err(|error| format!("content watch failed: {error}"))?;
for path in event.paths {
if self
.suppressed_paths
.get(&path)
.is_some_and(|deadline| *deadline >= now)
{
continue;
}
if self.is_user_content_path(&path) {
self.changes.record(path, now);
}
}
}
Ok(self.changes.take_ready(now, debounce))
}
fn is_user_content_path(&self, path: &Path) -> bool {
is_user_content_path(&self.assets_root, path)
}
}
fn is_user_content_path(assets_root: &Path, path: &Path) -> bool {
let Ok(relative) = path.strip_prefix(assets_root) else {
return false;
};
!crate::is_managed_path(relative)
&& relative != Path::new("content.catalog.ron")
&& relative
.extension()
.and_then(|extension| extension.to_str())
!= Some("tmp")
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn debounce_deduplicates_and_transaction_suppression_discards_noise() {
let start = Instant::now();
let mut changes = DebouncedContentChanges::default();
changes.record(PathBuf::from("assets/a.png"), start);
changes.record(PathBuf::from("assets/a.png"), start);
assert!(changes
.take_ready(start, Duration::from_millis(50))
.is_empty());
assert_eq!(
changes.take_ready(start + Duration::from_millis(51), Duration::from_millis(50)),
vec![PathBuf::from("assets/a.png")]
);
changes.begin_transaction();
changes.record(PathBuf::from("assets/internal.ron"), start);
changes.end_transaction();
assert!(changes
.take_ready(start + Duration::from_secs(1), Duration::ZERO)
.is_empty());
}
#[test]
fn watcher_ignores_managed_and_generated_publication_noise() {
let root = Path::new("/project/assets");
assert!(is_user_content_path(
root,
Path::new("/project/assets/Props/a.png")
));
assert!(!is_user_content_path(
root,
Path::new("/project/assets/.index/registry.ron")
));
assert!(!is_user_content_path(
root,
Path::new("/project/assets/content.catalog.ron")
));
assert!(!is_user_content_path(
root,
Path::new("/project/assets/meshes/generated/model.static_mesh.ron")
));
assert!(!is_user_content_path(
root,
Path::new("/project/assets/Props/a.tmp")
));
}
}