Resolve FBX external texture dependencies

This commit is contained in:
Rbanh committed 2026-07-13 13:41:23 -04:00
1 parent 7e99243a78
commit 3e30c61c71
22 files changed
+1670 -265

No files matched your search

+1 -1
View File
@@ -1455,7 +1455,7 @@ pub fn import_external_assets(paths: &[PathBuf]) -> Result<usize, String> {
};
let dest_dir = import_dir_for_extension(extension);
if extension.eq_ignore_ascii_case("fbx") {
super::import::copy_fbx_with_sidecar(source, Path::new(dest_dir))?;
super::import::copy_fbx_bundle(source, Path::new(dest_dir))?;
copied += 1;
continue;
}
+535 -42
View File
@@ -1,71 +1,564 @@
//! External asset import helpers (FBX sidecar folders, etc.).
//! External asset bundle inspection and transactional import.
use std::collections::BTreeMap;
use std::fs;
use std::path::{Path, PathBuf};
use std::path::{Component, Path, PathBuf};
/// Copies an FBX file and its sibling `.fbm` embedded-texture folder when present.
pub fn copy_fbx_with_sidecar(source: &Path, dest_dir: &Path) -> Result<(), String> {
let Some(file_name) = source.file_name() else {
return Err("FBX import path has no file name".into());
};
fs::create_dir_all(dest_dir)
.map_err(|err| format!("could not create {}: {err}", dest_dir.display()))?;
let dest = dest_dir.join(file_name);
fs::copy(source, &dest).map_err(|err| {
use bevy_ufbx::texture::external_texture_paths;
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct FbxDependencyInspection {
pub relative_paths: Vec<String>,
pub resolved_paths: Vec<PathBuf>,
pub missing_paths: Vec<PathBuf>,
}
/// Parses every external FBX texture reference without loading it through Bevy.
pub(crate) fn inspect_fbx_dependencies(source: &Path) -> Result<FbxDependencyInspection, String> {
let bytes = fs::read(source)
.map_err(|error| format!("could not read FBX {}: {error}", source.display()))?;
let filename_hint = source.to_string_lossy();
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(&filename_hint),
..Default::default()
},
)
.map_err(|error| format!("could not parse FBX {}: {error:?}", source.display()))?;
let relative_paths = external_texture_paths(&scene).map_err(|errors| {
format!(
"could not copy {} to {}: {err}",
"unsafe FBX texture reference(s) in {}: {}",
source.display(),
dest.display()
errors
.into_iter()
.map(|error| error.to_string())
.collect::<Vec<_>>()
.join("; ")
)
})?;
let source_root = source.parent().unwrap_or_else(|| Path::new(""));
let canonical_root = fs::canonicalize(source_root).map_err(|error| {
format!(
"could not resolve FBX source directory {}: {error}",
source_root.display()
)
})?;
let mut resolved_paths = Vec::new();
let mut missing_paths = Vec::new();
for relative_path in &relative_paths {
let resolved = source_root.join(relative_path);
if !resolved.is_file() {
missing_paths.push(resolved.clone());
resolved_paths.push(resolved);
continue;
}
let canonical = fs::canonicalize(&resolved).map_err(|error| {
format!(
"could not resolve FBX dependency {}: {error}",
resolved.display()
)
})?;
if !canonical.starts_with(&canonical_root) {
return Err(format!(
"FBX dependency {} resolves outside source directory {}",
resolved.display(),
source_root.display()
));
}
resolved_paths.push(resolved);
}
missing_paths.sort();
Ok(FbxDependencyInspection {
relative_paths,
resolved_paths,
missing_paths,
})
}
if let Some(fbm_dir) = fbm_sidecar_dir(source) {
if fbm_dir.is_dir() {
let dest_fbm = dest_dir.join(fbm_dir.file_name().unwrap_or_default());
copy_dir_recursive(&fbm_dir, &dest_fbm)?;
/// Returns one stable browser-facing error for all missing FBX source textures.
pub(crate) fn validate_fbx_dependencies(source: &Path) -> Result<(), String> {
let inspection = inspect_fbx_dependencies(source)?;
if inspection.missing_paths.is_empty() {
return Ok(());
}
Err(format!(
"missing {} FBX source texture(s): {}",
inspection.missing_paths.len(),
inspection
.missing_paths
.iter()
.map(|path| path.to_string_lossy().replace('\\', "/"))
.collect::<Vec<_>>()
.join(", ")
))
}
/// Copies an FBX and every referenced external texture as one staged filesystem transaction.
pub fn copy_fbx_bundle(source: &Path, dest_dir: &Path) -> Result<(), String> {
let inspection = inspect_fbx_dependencies(source)?;
if !inspection.missing_paths.is_empty() {
return Err(format!(
"FBX import is missing {} required texture(s): {}",
inspection.missing_paths.len(),
inspection
.missing_paths
.iter()
.map(|path| path.display().to_string())
.collect::<Vec<_>>()
.join(", ")
));
}
let file_name = source
.file_name()
.ok_or_else(|| "FBX import path has no file name".to_string())?;
let mut entries = BTreeMap::new();
entries.insert(PathBuf::from(file_name), source.to_path_buf());
for (relative, resolved) in inspection
.relative_paths
.iter()
.zip(inspection.resolved_paths.iter())
{
let relative = PathBuf::from(relative);
if let Some(existing) = entries.insert(relative.clone(), resolved.clone()) {
if existing != *resolved {
return Err(format!(
"FBX import maps multiple source files to {}",
relative.display()
));
}
}
}
Ok(())
copy_bundle_transactionally(&entries, dest_dir)
}
fn fbm_sidecar_dir(source: &Path) -> Option<PathBuf> {
let stem = source.file_stem()?.to_str()?;
let parent = source.parent()?;
Some(parent.join(format!("{stem}.fbm")))
}
fn copy_bundle_transactionally(
entries: &BTreeMap<PathBuf, PathBuf>,
dest_dir: &Path,
) -> Result<(), String> {
fs::create_dir_all(dest_dir)
.map_err(|error| format!("could not create {}: {error}", dest_dir.display()))?;
let canonical_dest_dir = fs::canonicalize(dest_dir).map_err(|error| {
format!(
"could not resolve FBX import destination {}: {error}",
dest_dir.display()
)
})?;
for relative in entries.keys() {
validate_bundle_relative_path(relative)?;
validate_existing_destination_parents(dest_dir, &canonical_dest_dir, relative)?;
let target = dest_dir.join(relative);
if target.is_dir() {
return Err(format!(
"FBX import target {} is an existing directory",
target.display()
));
}
}
fn copy_dir_recursive(source: &Path, dest: &Path) -> Result<(), String> {
fs::create_dir_all(dest)
.map_err(|err| format!("could not create {}: {err}", dest.display()))?;
for entry in fs::read_dir(source).map_err(|err| err.to_string())? {
let entry = entry.map_err(|err| err.to_string())?;
let src_path = entry.path();
let dest_path = dest.join(entry.file_name());
if src_path.is_dir() {
copy_dir_recursive(&src_path, &dest_path)?;
} else {
fs::copy(&src_path, &dest_path).map_err(|err| {
let stage_root = dest_dir.join(format!(".blacksite-import-{}", uuid::Uuid::new_v4()));
let staged_root = stage_root.join("new");
let backup_root = stage_root.join("backup");
let stage_result = (|| {
for (relative, source) in entries {
let staged = staged_root.join(relative);
if let Some(parent) = staged.parent() {
fs::create_dir_all(parent).map_err(|error| {
format!(
"could not create import staging {}: {error}",
parent.display()
)
})?;
}
fs::copy(source, &staged).map_err(|error| {
format!(
"could not copy {} to {}: {err}",
src_path.display(),
dest_path.display()
"could not stage FBX bundle file {} as {}: {error}",
source.display(),
relative.display()
)
})?;
}
commit_staged_bundle(
entries,
dest_dir,
&canonical_dest_dir,
&staged_root,
&backup_root,
)
})();
let cleanup_result = fs::remove_dir_all(&stage_root);
match (stage_result, cleanup_result) {
(Err(error), _) => Err(error),
(Ok(()), Ok(())) => Ok(()),
(Ok(()), Err(error)) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
(Ok(()), Err(error)) => {
bevy::log::warn!(
"FBX bundle imported but staging cleanup failed for {}: {error}",
stage_root.display()
);
Ok(())
}
}
}
fn validate_bundle_relative_path(relative: &Path) -> Result<(), String> {
if relative.as_os_str().is_empty()
|| !relative
.components()
.all(|component| matches!(component, Component::Normal(_)))
{
return Err(format!(
"FBX import target path {} is not a safe relative path",
relative.display()
));
}
Ok(())
}
fn validate_existing_destination_parents(
dest_dir: &Path,
canonical_dest_dir: &Path,
relative: &Path,
) -> Result<(), String> {
let mut current = dest_dir.to_path_buf();
let Some(parent) = relative.parent() else {
return Ok(());
};
for component in parent.components() {
let Component::Normal(segment) = component else {
return Err(format!(
"FBX import target path {} is not a safe relative path",
relative.display()
));
};
current.push(segment);
let metadata = match fs::symlink_metadata(&current) {
Ok(metadata) => metadata,
Err(error) if error.kind() == std::io::ErrorKind::NotFound => break,
Err(error) => {
return Err(format!(
"could not inspect FBX import target {}: {error}",
current.display()
));
}
};
if metadata.file_type().is_symlink() {
return Err(format!(
"FBX import target parent {} is a symbolic link",
current.display()
));
}
if !metadata.is_dir() {
return Err(format!(
"FBX import target parent {} is not a directory",
current.display()
));
}
let canonical = fs::canonicalize(&current).map_err(|error| {
format!(
"could not resolve FBX import target parent {}: {error}",
current.display()
)
})?;
if !canonical.starts_with(canonical_dest_dir) {
return Err(format!(
"FBX import target parent {} resolves outside destination {}",
current.display(),
dest_dir.display()
));
}
}
Ok(())
}
fn commit_staged_bundle(
entries: &BTreeMap<PathBuf, PathBuf>,
dest_dir: &Path,
canonical_dest_dir: &Path,
staged_root: &Path,
backup_root: &Path,
) -> Result<(), String> {
let mut installed = Vec::new();
let mut backups = Vec::new();
for relative in entries.keys() {
let target = dest_dir.join(relative);
let staged = staged_root.join(relative);
if let Some(parent) = target.parent() {
if let Err(error) = fs::create_dir_all(parent) {
return rollback_bundle(
&installed,
&backups,
format!(
"could not create import target {}: {error}",
parent.display()
),
);
}
let canonical_parent = match fs::canonicalize(parent) {
Ok(canonical_parent) => canonical_parent,
Err(error) => {
return rollback_bundle(
&installed,
&backups,
format!(
"could not resolve import target {}: {error}",
parent.display()
),
);
}
};
if !canonical_parent.starts_with(canonical_dest_dir) {
return rollback_bundle(
&installed,
&backups,
format!(
"FBX import target {} resolves outside destination {}",
parent.display(),
dest_dir.display()
),
);
}
}
if target.exists() {
let backup = backup_root.join(relative);
if let Some(parent) = backup.parent() {
if let Err(error) = fs::create_dir_all(parent) {
return rollback_bundle(
&installed,
&backups,
format!(
"could not create import backup {}: {error}",
parent.display()
),
);
}
}
if let Err(error) = fs::rename(&target, &backup) {
return rollback_bundle(
&installed,
&backups,
format!(
"could not back up import target {}: {error}",
target.display()
),
);
}
backups.push((backup, target.clone()));
}
if let Err(error) = fs::rename(&staged, &target) {
return rollback_bundle(
&installed,
&backups,
format!(
"could not publish import target {}: {error}",
target.display()
),
);
}
installed.push(target);
}
Ok(())
}
fn rollback_bundle(
installed: &[PathBuf],
backups: &[(PathBuf, PathBuf)],
cause: String,
) -> Result<(), String> {
let mut rollback_errors = Vec::new();
for target in installed.iter().rev() {
if let Err(error) = fs::remove_file(target) {
if error.kind() != std::io::ErrorKind::NotFound {
rollback_errors.push(format!("remove {}: {error}", target.display()));
}
}
}
for (backup, target) in backups.iter().rev() {
if let Err(error) = fs::rename(backup, target) {
rollback_errors.push(format!(
"restore {} to {}: {error}",
backup.display(),
target.display()
));
}
}
if rollback_errors.is_empty() {
Err(cause)
} else {
Err(format!(
"{cause}; rollback also failed: {}",
rollback_errors.join("; ")
))
}
}
#[cfg(test)]
mod tests {
use super::fbm_sidecar_dir;
use std::path::Path;
use super::*;
fn temp_root(label: &str) -> PathBuf {
std::env::temp_dir().join(format!("blacksite-fbx-{label}-{}", uuid::Uuid::new_v4()))
}
fn committed_chair_bytes() -> Vec<u8> {
fs::read(
Path::new(env!("CARGO_MANIFEST_DIR"))
.join("../../assets/models/painted_wooden_chair_02_2k.fbx"),
)
.unwrap()
}
fn replace_equal_length(bytes: &mut [u8], from: &[u8], to: &[u8]) -> usize {
assert_eq!(from.len(), to.len());
let mut count = 0;
let mut offset = 0;
while let Some(index) = bytes[offset..]
.windows(from.len())
.position(|window| window == from)
{
let start = offset + index;
bytes[start..start + from.len()].copy_from_slice(to);
offset = start + from.len();
count += 1;
}
count
}
fn write_textures(root: &Path, folder: &str) {
let folder = root.join(folder);
fs::create_dir_all(&folder).unwrap();
for name in [
"painted_wooden_chair_02_diff_2k.jpg",
"painted_wooden_chair_02_nor_gl_2k.exr",
"painted_wooden_chair_02_rough_2k.exr",
] {
fs::write(folder.join(name), name.as_bytes()).unwrap();
}
}
#[test]
fn fbm_sidecar_path() {
fn committed_chair_reports_one_stable_missing_dependency_state() {
let path = Path::new(env!("CARGO_MANIFEST_DIR"))
.join("../../assets/models/painted_wooden_chair_02_2k.fbx");
let error = validate_fbx_dependencies(&path).unwrap_err();
assert!(error.starts_with("missing 3 FBX source texture(s):"));
assert_eq!(error.matches("painted_wooden_chair_02_").count(), 3);
}
#[test]
fn sibling_texture_bundle_is_copied_with_relative_layout() {
let root = temp_root("sibling");
let source_root = root.join("source");
let destination = root.join("destination");
fs::create_dir_all(&source_root).unwrap();
let source = source_root.join("chair.fbx");
fs::write(&source, committed_chair_bytes()).unwrap();
write_textures(&source_root, "textures");
copy_fbx_bundle(&source, &destination).unwrap();
assert!(destination.join("chair.fbx").is_file());
assert!(destination
.join("textures/painted_wooden_chair_02_diff_2k.jpg")
.is_file());
assert!(!destination.read_dir().unwrap().any(|entry| entry
.unwrap()
.file_name()
.to_string_lossy()
.starts_with(".blacksite-import-")));
fs::remove_dir_all(root).unwrap();
}
#[test]
fn fbm_texture_bundle_is_copied_with_relative_layout() {
let root = temp_root("fbm");
let source_root = root.join("source");
let destination = root.join("destination");
fs::create_dir_all(&source_root).unwrap();
let source = source_root.join("chair.fbx");
let mut bytes = committed_chair_bytes();
assert!(replace_equal_length(&mut bytes, b"textures/", b"test.fbm/") > 0);
fs::write(&source, bytes).unwrap();
write_textures(&source_root, "test.fbm");
copy_fbx_bundle(&source, &destination).unwrap();
assert!(destination
.join("test.fbm/painted_wooden_chair_02_diff_2k.jpg")
.is_file());
fs::remove_dir_all(root).unwrap();
}
#[test]
fn traversal_reference_is_rejected_before_destination_changes() {
let root = temp_root("traversal");
let source_root = root.join("source");
let destination = root.join("destination");
fs::create_dir_all(&source_root).unwrap();
fs::create_dir_all(&destination).unwrap();
let source = source_root.join("chair.fbx");
let mut bytes = committed_chair_bytes();
assert!(replace_equal_length(&mut bytes, b"textures/", b"../evil//") > 0);
fs::write(&source, bytes).unwrap();
fs::write(destination.join("chair.fbx"), b"original").unwrap();
let error = copy_fbx_bundle(&source, &destination).unwrap_err();
assert!(error.contains("parent traversal"));
assert_eq!(
fbm_sidecar_dir(Path::new("/tmp/Character.fbx")),
Some(Path::new("/tmp/Character.fbm").to_path_buf())
fs::read(destination.join("chair.fbx")).unwrap(),
b"original"
);
fs::remove_dir_all(root).unwrap();
}
#[test]
fn missing_bundle_preserves_existing_destination() {
let root = temp_root("missing");
let source_root = root.join("source");
let destination = root.join("destination");
fs::create_dir_all(&source_root).unwrap();
fs::create_dir_all(&destination).unwrap();
let source = source_root.join("chair.fbx");
fs::write(&source, committed_chair_bytes()).unwrap();
fs::write(destination.join("chair.fbx"), b"original").unwrap();
let error = copy_fbx_bundle(&source, &destination).unwrap_err();
assert!(error.contains("missing 3 required texture(s)"));
assert_eq!(
fs::read(destination.join("chair.fbx")).unwrap(),
b"original"
);
fs::remove_dir_all(root).unwrap();
}
#[cfg(unix)]
#[test]
fn destination_symlink_escape_is_rejected_before_external_changes() {
use std::os::unix::fs::symlink;
let root = temp_root("destination-symlink");
let source_root = root.join("source");
let destination = root.join("destination");
let outside = root.join("outside");
fs::create_dir_all(&source_root).unwrap();
fs::create_dir_all(&destination).unwrap();
fs::create_dir_all(&outside).unwrap();
let source = source_root.join("chair.fbx");
fs::write(&source, committed_chair_bytes()).unwrap();
write_textures(&source_root, "textures");
symlink(&outside, destination.join("textures")).unwrap();
let error = copy_fbx_bundle(&source, &destination).unwrap_err();
assert!(error.contains("symbolic link"));
assert!(!destination.join("chair.fbx").exists());
assert!(!outside.join("painted_wooden_chair_02_diff_2k.jpg").exists());
fs::remove_dir_all(root).unwrap();
}
}
+48 -19
View File
@@ -7,6 +7,7 @@ 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};
@@ -484,6 +485,7 @@ fn build_fbx_manifest(
ufbx::LoadOpts {
target_unit_meters: 1.0,
target_axes: ufbx::CoordinateAxes::right_handed_y_up(),
filename: ufbx::StringOpt::Ref(&record.path),
..Default::default()
},
)
@@ -563,7 +565,7 @@ fn build_fbx_manifest(
path: record.path.clone(),
format,
fingerprint,
dependencies: fbx_dependencies(&record.path),
dependencies: fbx_dependencies(&record.path, &scene)?,
},
import,
metadata: StaticMeshMetadata {
@@ -592,25 +594,26 @@ fn fbx_material_label(scene: &ufbx::Scene, element_id: u32) -> Option<String> {
.map(|index| FbxAssetLabel::Material(index).to_string())
}
fn fbx_dependencies(source_path: &str) -> Vec<String> {
fn fbx_dependencies(source_path: &str, scene: &ufbx::Scene) -> Result<Vec<String>, String> {
let path = Path::new(source_path);
let Some(stem) = path.file_stem().and_then(|stem| stem.to_str()) else {
return Vec::new();
};
let Some(parent) = path.parent() else {
return Vec::new();
};
let sidecar = parent.join(format!("{stem}.fbm"));
if !sidecar.is_dir() {
return Vec::new();
}
walkdir::WalkDir::new(sidecar)
.follow_links(false)
.into_iter()
.filter_map(Result::ok)
.filter(|entry| entry.file_type().is_file())
.map(|entry| entry.path().to_string_lossy().replace('\\', "/"))
.collect()
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> {
@@ -823,4 +826,30 @@ mod tests {
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_tag: "Model".into(),
source_fingerprint: None,
import_settings: 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_")));
}
}
+113 -2
View File
@@ -1,7 +1,9 @@
//! Thumbnail cache for asset browser grid cells.
use std::collections::{HashMap, HashSet};
use std::path::Path;
use bevy::asset::LoadState;
use bevy::prelude::*;
use bevy_egui::{egui, EguiPrimaryContextPass, EguiTextureHandle, EguiUserTextures};
use egui_phosphor_icons::icons;
@@ -79,6 +81,9 @@ impl AssetThumbnailCache {
if self.failed.contains_key(&key) {
return;
}
if !self.texture_source_ready(&key, &path) {
return;
}
let handle: Handle<Image> = asset_server.load(asset_server_path(&path));
self.pending.insert(key, handle);
}
@@ -161,7 +166,7 @@ impl AssetThumbnailCache {
{
return;
}
if !self.model_source_ready(&key, &model_path) {
if !self.source_material_ready(&key, &model_path) {
return;
}
if studio.enqueue_source(
@@ -224,6 +229,32 @@ impl AssetThumbnailCache {
true
}
fn texture_source_ready(&mut self, key: &str, texture_path: &str) -> bool {
if Path::new(texture_path).is_file() {
return true;
}
self.mark_studio_failed(key, &format!("missing texture: {texture_path}"), false);
false
}
fn source_material_ready(&mut self, key: &str, model_path: &str) -> bool {
if !self.model_source_ready(key, model_path) {
return false;
}
if model_path
.rsplit_once('.')
.is_some_and(|(_, extension)| extension.eq_ignore_ascii_case("fbx"))
{
if let Err(reason) =
crate::assets::import::validate_fbx_dependencies(std::path::Path::new(model_path))
{
self.mark_studio_failed(key, &reason, false);
return false;
}
}
true
}
pub(crate) fn complete_studio_thumbnail(
&mut self,
key: &str,
@@ -268,6 +299,11 @@ impl AssetThumbnailCache {
.cloned()
.collect(),
failed_keys: self.failed.keys().cloned().collect(),
failure_reasons: self
.failed
.iter()
.map(|(key, failure)| (key.clone(), failure.reason.clone()))
.collect(),
}
}
}
@@ -277,6 +313,14 @@ fn register_loaded_thumbnails(
mut cache: ResMut<AssetThumbnailCache>,
mut textures: ResMut<EguiUserTextures>,
) {
let failed: Vec<(String, String)> = cache
.pending
.iter()
.filter_map(|(key, handle)| match asset_server.load_state(handle.id()) {
LoadState::Failed(error) => Some((key.clone(), error.to_string())),
_ => None,
})
.collect();
let ready: Vec<(String, Handle<Image>)> = cache
.pending
.iter()
@@ -284,6 +328,10 @@ fn register_loaded_thumbnails(
.map(|(key, handle)| (key.clone(), handle.clone()))
.collect();
for (key, error) in failed {
cache.mark_studio_failed(&key, &format!("texture load failed: {error}"), false);
}
for (key, handle) in ready {
cache.pending.remove(&key);
cache.failed.remove(&key);
@@ -397,7 +445,11 @@ pub fn draw_asset_cell_with(
},
);
response
if let Some(reason) = failed {
response.on_hover_text(reason)
} else {
response
}
}
#[derive(Clone)]
@@ -405,6 +457,7 @@ pub struct ThumbnailCacheSnapshot {
pub texture_ids: HashMap<String, egui::TextureId>,
pub pending_keys: Vec<String>,
pub failed_keys: Vec<String>,
pub failure_reasons: HashMap<String, String>,
}
impl ThumbnailCacheSnapshot {
@@ -420,6 +473,10 @@ impl ThumbnailCacheSnapshot {
self.failed_keys.iter().any(|failed| failed == key)
}
pub fn failure_reason_for_key(&self, key: &str) -> Option<&str> {
self.failure_reasons.get(key).map(String::as_str)
}
pub fn texture_for(&self, asset: &EditorAsset) -> Option<egui::TextureId> {
self.texture_ids.get(&asset_cache_key(asset)).copied()
}
@@ -435,6 +492,10 @@ impl ThumbnailCacheSnapshot {
.iter()
.any(|key| key == &asset_cache_key(asset))
}
pub fn failure_reason(&self, asset: &EditorAsset) -> Option<&str> {
self.failure_reason_for_key(&asset_cache_key(asset))
}
}
pub fn prefetch_folder_thumbnails(world: &mut World, folder: &str) {
@@ -534,3 +595,53 @@ pub fn invalidate_on_catalog_refresh(world: &mut World) {
world.commands().entity(root).despawn();
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn missing_fbx_material_dependencies_are_one_stable_non_retryable_state() {
let model_path = Path::new(env!("CARGO_MANIFEST_DIR"))
.join("../../assets/models/painted_wooden_chair_02_2k.fbx")
.to_string_lossy()
.into_owned();
let mut cache = AssetThumbnailCache::default();
assert!(cache.model_source_ready("model", &model_path));
assert!(!cache.source_material_ready("material", &model_path));
let first = cache.state("material");
assert!(!cache.source_material_ready("material", &model_path));
assert_eq!(cache.state("material"), first);
let Some(ThumbnailState::Failed { reason, retryable }) = first else {
panic!("missing FBX textures should produce one stable failure");
};
assert!(!retryable);
assert!(reason.starts_with("missing 3 FBX source texture(s):"));
assert!(cache.studio_pending.is_empty());
}
#[test]
fn missing_texture_is_one_stable_non_retryable_state() {
let path = std::env::temp_dir().join(format!(
"blacksite-missing-thumbnail-{}-{}.png",
std::process::id(),
std::thread::current().name().unwrap_or("test")
));
let path = path.to_string_lossy().into_owned();
let mut cache = AssetThumbnailCache::default();
assert!(!cache.texture_source_ready("texture", &path));
let first = cache.state("texture");
assert!(!cache.texture_source_ready("texture", &path));
assert_eq!(cache.state("texture"), first);
let Some(ThumbnailState::Failed { reason, retryable }) = first else {
panic!("missing texture should produce one stable failure");
};
assert!(!retryable);
assert_eq!(reason, format!("missing texture: {path}"));
assert!(cache.pending.is_empty());
}
}
@@ -83,6 +83,72 @@ impl ThumbnailModelSource for FbxThumbnailSource {
}
}
pub(crate) fn spawn_fbx_mesh_subasset_preview(
commands: &mut Commands,
meshes: &mut Assets<Mesh>,
materials: &mut Assets<StandardMaterial>,
root: Entity,
catalog_path: &str,
mesh_label: &str,
) -> bool {
let Some(encoded_index) = mesh_label
.strip_prefix("Mesh")
.and_then(|index| index.parse::<usize>().ok())
else {
warn!("FBX thumbnail: unsupported mesh label {mesh_label}");
return false;
};
let node_index = encoded_index / 1000;
let material_index = encoded_index % 1000;
let Ok(bytes) = std::fs::read(catalog_path) else {
warn!("FBX thumbnail: could not read {catalog_path}");
return false;
};
let Ok(scene) = ufbx::load_memory(
&bytes,
ufbx::LoadOpts {
target_unit_meters: 1.0,
target_axes: ufbx::CoordinateAxes::right_handed_y_up(),
..Default::default()
},
) else {
warn!("FBX thumbnail: failed to parse {catalog_path}");
return false;
};
let Some(node) = scene.nodes.as_ref().get(node_index) else {
warn!("FBX thumbnail: mesh label {mesh_label} has no source node");
return false;
};
let Some(mesh_ref) = node.mesh.as_ref() else {
warn!("FBX thumbnail: mesh label {mesh_label} has no source mesh");
return false;
};
let Some(indices) = group_faces_by_material(mesh_ref.as_ref()).remove(&material_index) else {
warn!("FBX thumbnail: mesh label {mesh_label} has no material group");
return false;
};
if indices.is_empty() {
return false;
}
let mesh = meshes.add(build_mesh(mesh_ref.as_ref(), &indices));
let material = materials.add(StandardMaterial {
base_color: Color::srgb(0.72, 0.72, 0.75),
perceptual_roughness: 0.65,
..default()
});
let transform = Transform::from_matrix(convert_matrix(&node.geometry_to_world));
commands.entity(root).with_children(|parent| {
parent.spawn((
RenderLayers::layer(THUMBNAIL_LAYER),
Mesh3d(mesh),
MeshMaterial3d(material),
transform,
));
});
true
}
fn build_mesh(ufbx_mesh: &ufbx::Mesh, indices: &[u32]) -> Mesh {
let mut mesh = Mesh::new(
PrimitiveTopology::TriangleList,
@@ -3,6 +3,7 @@
mod fbx;
pub(crate) mod gltf;
pub(crate) use fbx::spawn_fbx_mesh_subasset_preview;
pub use fbx::FbxThumbnailSource;
pub use gltf::{gltf_skinned_primitive_labels, GltfThumbnailSource};
+52 -11
View File
@@ -15,7 +15,7 @@ use shared::{material_from_desc, standard_material_asset_path, ModelRef};
use super::cache::AssetThumbnailCache;
use super::job::{ThumbnailJob, ThumbnailJobSource};
use super::sources::{source_for_extension, uses_scene_root};
use super::sources::{source_for_extension, spawn_fbx_mesh_subasset_preview, uses_scene_root};
use crate::assets::asset_server_path;
use crate::infra::EditorOnly;
@@ -27,6 +27,7 @@ const SCENE_FRAME_PADDING: f32 = 1.35;
const MATERIAL_SPHERE_FRAME_PADDING: f32 = 1.28;
const MESH_WARMUP_FRAMES: u8 = 12;
const POST_ATTACH_FRAMES: u8 = 8;
const FIRST_RENDER_WARMUP_FRAMES: u8 = 120;
const RENDER_FRAMES: u8 = 3;
const COOLDOWN_FRAMES: u8 = 2;
const LOAD_TIMEOUT_FRAMES: u32 = 240;
@@ -51,6 +52,7 @@ pub struct ThumbnailStudio {
queue: VecDeque<ThumbnailJob>,
active: Option<ActiveModelThumbnail>,
cooldown_frames: u8,
render_pipeline_warmed: bool,
}
struct ActiveModelThumbnail {
@@ -209,6 +211,7 @@ fn setup_thumbnail_studio(mut commands: Commands, mut images: ResMut<Assets<Imag
queue: VecDeque::new(),
active: None,
cooldown_frames: 0,
render_pipeline_warmed: false,
});
}
@@ -288,7 +291,7 @@ fn process_thumbnail_studio(
camera.is_active = true;
}
active.camera_active = true;
active.frames_remaining = RENDER_FRAMES;
active.frames_remaining = capture_frames(studio.render_pipeline_warmed);
}
studio.active = Some(active);
return;
@@ -299,6 +302,7 @@ fn process_thumbnail_studio(
active.frames_remaining -= 1;
studio.active = Some(active);
} else {
studio.render_pipeline_warmed = true;
cache.complete_studio_thumbnail(
&active.cache_key,
active.render_image.clone(),
@@ -426,12 +430,15 @@ fn spawn_thumbnail_job_content(
material_label,
} => spawn_mesh_subasset_preview(
commands,
mesh_storage,
materials,
asset_server,
root,
model_path,
mesh_label,
material_label.as_deref(),
MeshSubassetPreviewSpec {
model_path,
mesh_label,
material_label: material_label.as_deref(),
},
),
ThumbnailJobSource::SourceMaterial {
model_path,
@@ -452,18 +459,38 @@ fn spawn_thumbnail_job_content(
}
}
struct MeshSubassetPreviewSpec<'a> {
model_path: &'a str,
mesh_label: &'a str,
material_label: Option<&'a str>,
}
fn spawn_mesh_subasset_preview(
commands: &mut Commands,
mesh_storage: &mut Assets<Mesh>,
materials: &mut Assets<StandardMaterial>,
asset_server: &AssetServer,
root: Entity,
model_path: &str,
mesh_label: &str,
material_label: Option<&str>,
preview: MeshSubassetPreviewSpec<'_>,
) -> bool {
let source_path = asset_server_path(model_path);
let mesh: Handle<Mesh> = asset_server.load(labeled_asset_path(&source_path, mesh_label));
let material = if let Some(material_label) = material_label {
if preview
.model_path
.rsplit_once('.')
.is_some_and(|(_, extension)| extension.eq_ignore_ascii_case("fbx"))
{
return spawn_fbx_mesh_subasset_preview(
commands,
mesh_storage,
materials,
root,
preview.model_path,
preview.mesh_label,
);
}
let source_path = asset_server_path(preview.model_path);
let mesh: Handle<Mesh> =
asset_server.load(labeled_asset_path(&source_path, preview.mesh_label));
let material = if let Some(material_label) = preview.material_label {
asset_server.load(standard_material_asset_path(&source_path, material_label))
} else {
materials.add(StandardMaterial {
@@ -509,6 +536,14 @@ fn studio_render_image() -> Image {
Image::new_target_texture(THUMB_SIZE, THUMB_SIZE, TextureFormat::Rgba16Float, None)
}
fn capture_frames(render_pipeline_warmed: bool) -> u8 {
if render_pipeline_warmed {
RENDER_FRAMES
} else {
FIRST_RENDER_WARMUP_FRAMES
}
}
fn finish_active_thumbnail(
commands: &mut Commands,
studio: &mut ThumbnailStudio,
@@ -734,4 +769,10 @@ mod tests {
assert!(material_distance < scene_distance * 0.6);
assert!((0.75..0.82).contains(&projected_radius_fraction));
}
#[test]
fn first_capture_keeps_camera_active_for_render_pipeline_warmup() {
assert_eq!(capture_frames(true), RENDER_FRAMES);
assert!(capture_frames(false) > capture_frames(true));
}
}
+83 -14
View File
@@ -49,7 +49,9 @@ use crate::assets::{
ThumbnailCacheSnapshot, ThumbnailStudio,
};
use crate::ui::helpers::asset_label;
use crate::ui::theme::{panel_heading, ACCENT, BORDER, ELEVATED_BG, TEXT, TEXT_DIM, WIDGET_BG};
use crate::ui::theme::{
panel_heading, ACCENT, BORDER, ELEVATED_BG, ERROR, SUCCESS, TEXT, TEXT_DIM, WARNING, WIDGET_BG,
};
use crate::ui::widgets::{icon_button_small, tool_button};
const FOOTER_HEIGHT: f32 = 64.0;
@@ -375,6 +377,10 @@ fn embedded_assets_for_asset(world: &World, asset: &EditorAsset) -> Vec<Embedded
return Vec::new();
};
let mut embedded = Vec::new();
let use_source_materials = matches!(
record.import_settings.material_policy,
MaterialImportPolicy::SourceMaterials
);
let static_manifest = record
.import_settings
.static_mesh_manifest_path
@@ -446,7 +452,11 @@ fn embedded_assets_for_asset(world: &World, asset: &EditorAsset) -> Vec<Embedded
},
label,
kind: AssetSubAssetKind::Material,
detail: "Embedded source material".to_string(),
detail: if use_source_materials {
"Embedded source material".to_string()
} else {
"Source material disabled by Authoring Override".to_string()
},
texture_path: None,
thumbnail_key: subasset_thumbnail_key(
parent_path,
@@ -1129,14 +1139,14 @@ fn draw_asset_grid_item(
let selection = &row.selection;
let asset = &row.asset;
let is_selected = selected.as_ref() == Some(selection);
let failed = cache_snapshot.is_failed(asset);
let failure = cache_snapshot.failure_reason(asset);
let has_children = has_embedded_assets(world, asset);
let response = draw_asset_cell_with(
ui,
asset,
cache_snapshot.texture_for(asset),
cache_snapshot.is_pending(asset),
failed.then_some("failed"),
failure,
is_selected,
thumbnail_size,
);
@@ -1190,7 +1200,7 @@ fn draw_asset_grid_item(
}
}
if failed && response.double_clicked() {
if failure.is_some() && response.double_clicked() {
let key = crate::assets::asset_cache_key(asset);
world
.resource_mut::<crate::assets::AssetThumbnailCache>()
@@ -1349,7 +1359,8 @@ fn draw_embedded_asset_cell(
.and_then(|path| thumbnail_for_path(world, cache_snapshot, path))
});
let pending = cache_snapshot.is_pending_key(&embedded.thumbnail_key);
let failed = cache_snapshot.is_failed_key(&embedded.thumbnail_key);
let failure = cache_snapshot.failure_reason_for_key(&embedded.thumbnail_key);
let failed = failure.is_some();
let thumb_size = thumbnail_size.clamp(44.0, 64.0);
let cell_size = egui::vec2(104.0, thumb_size + 50.0);
let (rect, response) = ui.allocate_exact_size(cell_size, egui::Sense::click_and_drag());
@@ -1360,6 +1371,11 @@ fn draw_embedded_asset_cell(
} else {
response
};
let response = if let Some(reason) = failure {
response.on_hover_text(reason)
} else {
response
};
let fill = if selected {
crate::ui::theme::SELECTION_BG_MUTED
} else if response.hovered() {
@@ -1883,9 +1899,53 @@ pub(crate) fn top_level_asset_details_panel(
}
if !record.dependencies.is_empty() {
ui.separator();
ui.label(panel_heading("Dependencies"));
let missing_count = record
.dependencies
.iter()
.filter(|dependency| !dependency_path(dependency).is_file())
.count();
ui.horizontal_wrapped(|ui| {
ui.label(panel_heading("Dependencies"));
if missing_count > 0 {
let optional = matches!(
record.import_settings.material_policy,
MaterialImportPolicy::AuthoringOverride
);
ui.small(
egui::RichText::new(if optional {
format!("{missing_count} missing | override")
} else {
format!("{missing_count} missing")
})
.color(if optional {
WARNING
} else {
ERROR
}),
);
}
});
for dep in &record.dependencies {
ui.add(egui::Label::new(dep).truncate());
let exists = dependency_path(dep).is_file();
ui.horizontal(|ui| {
ui.label(
egui::RichText::new(if exists {
icons::CHECK_CIRCLE.as_str()
} else {
icons::WARNING_CIRCLE.as_str()
})
.font(egui::FontId::new(
12.0,
egui::FontFamily::Name(PHOSPHOR.into()),
))
.color(if exists {
SUCCESS
} else {
WARNING
}),
);
ui.add(egui::Label::new(dep).truncate()).on_hover_text(dep);
});
}
}
}
@@ -2032,12 +2092,12 @@ fn subasset_details_panel(
}
}
AssetSubAssetKind::Material => {
ui.small(
egui::RichText::new(
"Source materials are assigned through static mesh renderer slots.",
)
.color(TEXT_DIM),
);
let status = if embedded.detail.contains("Authoring Override") {
"Authoring Override is active; this source material is not assigned."
} else {
"Source material is assigned through static mesh renderer slots."
};
ui.small(egui::RichText::new(status).color(TEXT_DIM));
}
AssetSubAssetKind::Skeleton => {
ui.small(
@@ -2072,6 +2132,15 @@ fn subasset_details_panel(
}
}
fn dependency_path(reference: &str) -> PathBuf {
let path = Path::new(reference);
if path.starts_with("assets") {
path.to_path_buf()
} else {
Path::new("assets").join(path)
}
}
fn asset_action_buttons(
world: &mut World,
ui: &mut egui::Ui,