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
View File
@@ -25,6 +25,7 @@ pub mod material;
pub mod mesh;
pub mod node;
pub mod scene;
pub mod texture;
pub mod types;
pub mod utils;
+118 -66
View File
@@ -5,11 +5,12 @@ use crate::material::process_materials;
use crate::mesh::process_meshes;
use crate::node::{process_nodes, process_skins};
use crate::scene::build_scene;
use crate::texture::external_texture_path_report;
use crate::types::{Fbx, FbxAxisSystem, FbxMeta, Handedness};
use bevy::asset::{io::Reader, AssetLoader, LoadContext, RenderAssetUsages};
use bevy::prelude::*;
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::collections::{BTreeSet, HashMap};
/// Settings for FBX file loading.
///
@@ -74,77 +75,128 @@ impl AssetLoader for FbxLoader {
return Err(FbxError::InvalidData("FBX file too small".to_string()));
}
// Parse with ufbx
// Provide the asset path as a filename hint so ufbx can compute relative_filename
let filename_hint = load_context.path().path().to_string_lossy().to_string();
let root = 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(|e| FbxError::UfbxError(format!("{:?}", e)))?;
let scene: &ufbx::Scene = &*root;
let root = parse_fbx(&bytes, &filename_hint)?;
let texture_report = external_texture_path_report(&root);
if texture_report.paths.is_empty() {
if !texture_report.errors.is_empty() {
warn_texture_failures(
load_context.path(),
texture_report.errors.iter().map(ToString::to_string),
);
}
return process_scene(&root, settings, load_context, &HashMap::new());
}
// Process meshes
let (meshes, named_meshes, mesh_transforms, mesh_material_info) =
process_meshes(scene, settings, load_context)?;
// `ufbx::Scene` is not Send, so finish discovery and drop it before awaiting asset I/O.
drop(root);
let mut failures = texture_report
.errors
.iter()
.map(ToString::to_string)
.collect::<BTreeSet<_>>();
let mut external_texture_bytes = HashMap::new();
let asset_path = load_context.path().clone();
for relative_path in texture_report.paths {
let resolved_path = match asset_path.resolve_embed_str(&relative_path) {
Ok(path) => path,
Err(error) => {
failures.insert(format!("{relative_path} ({error})"));
continue;
}
};
match load_context.read_asset_bytes(resolved_path.clone()).await {
Ok(bytes) => {
external_texture_bytes.insert(relative_path, bytes);
}
Err(error) => {
failures.insert(format!("{resolved_path} ({error})"));
}
}
}
if !failures.is_empty() {
warn_texture_failures(load_context.path(), failures);
}
// Process materials and textures
let (materials, named_materials) = if !settings.load_materials.is_empty() {
process_materials(scene, settings, load_context)?
} else {
(Vec::new(), HashMap::new())
};
// Process nodes and hierarchy
let (nodes, named_nodes, node_map) = process_nodes(scene, &meshes, load_context)?;
// Process skins
let (skins, named_skins) = process_skins(scene, &node_map, load_context)?;
// Build scene
let scene_handle = build_scene(
scene,
&meshes,
&materials,
&named_materials,
&mesh_transforms,
&mesh_material_info,
settings,
load_context,
)?;
// Extract metadata
let metadata = FbxMeta::default();
// Build final FBX asset
Ok(Fbx {
scenes: vec![scene_handle.clone()],
named_scenes: HashMap::new(),
meshes,
named_meshes,
materials,
named_materials,
nodes,
named_nodes,
skins,
named_skins,
default_scene: Some(scene_handle),
axis_system: FbxAxisSystem {
up: Vec3::Y,
front: Vec3::Z,
handedness: Handedness::Right,
},
unit_scale: 1.0,
metadata,
})
let root = parse_fbx(&bytes, &filename_hint)?;
process_scene(&root, settings, load_context, &external_texture_bytes)
}
fn extensions(&self) -> &[&str] {
&["fbx"]
}
}
fn parse_fbx(bytes: &[u8], filename_hint: &str) -> Result<ufbx::SceneRoot, FbxError> {
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| FbxError::UfbxError(format!("{error:?}")))
}
fn process_scene(
scene: &ufbx::Scene,
settings: &FbxLoaderSettings,
load_context: &mut LoadContext<'_>,
external_texture_bytes: &HashMap<String, Vec<u8>>,
) -> Result<Fbx, FbxError> {
let (meshes, named_meshes, mesh_transforms, mesh_material_info) =
process_meshes(scene, settings, load_context)?;
let (materials, named_materials) = if !settings.load_materials.is_empty() {
process_materials(scene, settings, load_context, external_texture_bytes)?
} else {
(Vec::new(), HashMap::new())
};
let (nodes, named_nodes, node_map) = process_nodes(scene, &meshes, load_context)?;
let (skins, named_skins) = process_skins(scene, &node_map, load_context)?;
let scene_handle = build_scene(
scene,
&meshes,
&materials,
&named_materials,
&mesh_transforms,
&mesh_material_info,
settings,
load_context,
)?;
Ok(Fbx {
scenes: vec![scene_handle.clone()],
named_scenes: HashMap::new(),
meshes,
named_meshes,
materials,
named_materials,
nodes,
named_nodes,
skins,
named_skins,
default_scene: Some(scene_handle),
axis_system: FbxAxisSystem {
up: Vec3::Y,
front: Vec3::Z,
handedness: Handedness::Right,
},
unit_scale: 1.0,
metadata: FbxMeta::default(),
})
}
fn warn_texture_failures(
asset_path: &bevy::asset::AssetPath<'_>,
failures: impl IntoIterator<Item = String>,
) {
let failures = failures.into_iter().collect::<Vec<_>>();
warn!(
"bevy_ufbx: skipped {} unavailable external texture reference(s) for {}: {}",
failures.len(),
asset_path,
failures.join("; ")
);
}
+62 -77
View File
@@ -3,19 +3,21 @@
use crate::error::FbxError;
use crate::label::FbxAssetLabel;
use crate::loader::FbxLoaderSettings;
use crate::texture::external_texture_reference;
use crate::utils::convert_texture_uv_transform;
use bevy::asset::{Handle, LoadContext};
use bevy::pbr::StandardMaterial;
use bevy::prelude::*;
use bevy_material::AlphaMode;
use bevy_image::{CompressedImageFormats, ImageSampler, ImageType};
use std::collections::HashMap;
use std::collections::{BTreeSet, HashMap};
/// Process all materials from the FBX scene.
pub fn process_materials(
scene: &ufbx::Scene,
settings: &FbxLoaderSettings,
load_context: &mut LoadContext,
load_context: &mut LoadContext<'_>,
external_texture_bytes: &HashMap<String, Vec<u8>>,
) -> Result<
(
Vec<Handle<StandardMaterial>>,
@@ -25,7 +27,12 @@ pub fn process_materials(
> {
let mut materials = Vec::new();
let mut named_materials = HashMap::new();
let texture_handles = process_textures(scene, settings, load_context)?;
let texture_handles = process_textures(
scene,
settings,
load_context,
external_texture_bytes,
)?;
for (index, ufbx_material) in scene.materials.as_ref().iter().enumerate() {
if ufbx_material.element.element_id == 0 {
@@ -60,18 +67,15 @@ pub fn process_materials(
pub fn process_textures(
scene: &ufbx::Scene,
settings: &FbxLoaderSettings,
load_context: &mut LoadContext,
load_context: &mut LoadContext<'_>,
external_texture_bytes: &HashMap<String, Vec<u8>>,
) -> Result<HashMap<u32, Handle<Image>>, FbxError> {
let mut texture_handles = HashMap::new();
let mut external_handles = HashMap::<String, Handle<Image>>::new();
let mut unavailable = BTreeSet::new();
let asset_path = load_context.path().clone();
for (index, texture) in scene.textures.as_ref().iter().enumerate() {
let asset_path = load_context.path().clone();
let fbx_dir = asset_path
.path()
.parent()
.unwrap_or_else(|| std::path::Path::new(""))
.to_path_buf();
// Priority 1: Embedded texture data
if !texture.content.is_empty() {
let ext = extract_extension(&texture.filename).unwrap_or("png");
@@ -91,39 +95,62 @@ pub fn process_textures(
texture_handles.insert(texture.element.element_id, handle);
continue;
}
Err(e) => {
eprintln!("bevy_ufbx: failed to load embedded texture {index}: {e}");
// Fall through to try external paths
Err(error) => {
warn!(
"bevy_ufbx: skipped embedded texture {index} for {asset_path}: {error}"
);
continue;
}
}
}
// Priority 2: relative_filename from ufbx (relative to FBX file)
if !texture.relative_filename.is_empty() {
let rel = texture.relative_filename.as_ref();
let is_absolute = rel.starts_with('/')
|| (rel.len() >= 3 && rel.chars().nth(1) == Some(':'));
if !is_absolute {
let texture_path = fbx_dir.join(rel).to_string_lossy().to_string();
let image_handle = load_context.load(texture_path);
texture_handles.insert(texture.element.element_id, image_handle);
let reference = match external_texture_reference(index, texture) {
Ok(Some(reference)) => reference,
Ok(None) => continue,
Err(error) => {
unavailable.insert(error.to_string());
continue;
}
};
if let Some(handle) = external_handles.get(&reference.relative_path) {
texture_handles.insert(reference.element_id, handle.clone());
continue;
}
// Priority 3: Extract relative path from filename / absolute_filename
// Preserves .fbm folder structure if present (e.g., "model.fbm/texture.jpg")
let relative_path = extract_relative_texture_path(texture);
let Some(bytes) = external_texture_bytes.get(&reference.relative_path) else {
continue;
};
let extension = std::path::Path::new(&reference.relative_path)
.extension()
.and_then(|extension| extension.to_str())
.unwrap_or("png");
let image = match Image::from_buffer(
&bytes,
ImageType::Extension(extension),
CompressedImageFormats::NONE,
true,
ImageSampler::Default,
settings.load_materials,
) {
Ok(image) => image,
Err(error) => {
unavailable.insert(format!("{} ({error})", reference.relative_path));
continue;
}
};
let handle = load_context
.add_labeled_asset(FbxAssetLabel::Texture(index).to_string(), image);
external_handles.insert(reference.relative_path, handle.clone());
texture_handles.insert(reference.element_id, handle);
}
if !relative_path.is_empty() {
let texture_path = fbx_dir
.join(relative_path)
.to_string_lossy()
.to_string();
let image_handle = load_context.load(texture_path);
texture_handles.insert(texture.element.element_id, image_handle);
}
if !unavailable.is_empty() {
warn!(
"bevy_ufbx: skipped {} unavailable external texture reference(s) for {}: {}",
unavailable.len(),
asset_path,
unavailable.into_iter().collect::<Vec<_>>().join("; ")
);
}
Ok(texture_handles)
@@ -140,48 +167,6 @@ fn extract_extension(filename: &ufbx::String) -> Option<&str> {
.filter(|ext| !ext.contains('/') && !ext.contains('\\'))
}
/// Extract a relative texture path from a ufbx Texture's filename or absolute_filename.
///
/// Handles absolute paths by looking for `.fbm` folders (FBX's standard embedded texture
/// directory) and extracting from there, or falling back to just the filename.
fn extract_relative_texture_path<'a>(texture: &'a ufbx::Texture) -> &'a str {
if !texture.filename.is_empty() {
let filename = texture.filename.as_ref();
let is_absolute = filename.starts_with('/')
|| (filename.len() >= 3 && filename.chars().nth(1) == Some(':'));
if is_absolute {
extract_from_absolute(filename)
} else {
filename
}
} else if !texture.absolute_filename.is_empty() {
extract_from_absolute(texture.absolute_filename.as_ref())
} else {
""
}
}
/// Extract a relative path from an absolute path, preserving `.fbm` folder structure.
fn extract_from_absolute(path: &str) -> &str {
if let Some(fbm_pos) = path.rfind(".fbm/").or_else(|| path.rfind(".fbm\\")) {
let before_fbm = &path[..fbm_pos];
let folder_start = before_fbm
.rfind(&['/', '\\'][..])
.map(|p| p + 1)
.unwrap_or(0);
&path[folder_start..]
} else {
let last_slash = path.rfind(&['/', '\\'][..]);
if let Some(pos) = last_slash {
&path[pos + 1..]
} else {
path
}
}
}
/// Create a StandardMaterial from ufbx material.
pub fn create_standard_material(
ufbx_material: &ufbx::Material,
+211
View File
@@ -0,0 +1,211 @@
//! External FBX texture reference discovery and path normalization.
use std::collections::BTreeSet;
use std::fmt;
use std::path::{Component, Path};
/// One safe external texture reference declared by an FBX texture element.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FbxExternalTextureReference {
pub texture_index: usize,
pub element_id: u32,
pub relative_path: String,
}
/// A texture reference that cannot be resolved inside the FBX asset source.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FbxTexturePathError {
pub texture_index: usize,
pub raw_path: String,
pub reason: String,
}
/// Deterministic external texture discovery result, including safe and rejected references.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct FbxExternalTexturePathReport {
pub paths: Vec<String>,
pub errors: Vec<FbxTexturePathError>,
}
impl fmt::Display for FbxTexturePathError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(
formatter,
"texture {} path `{}` is unsafe: {}",
self.texture_index, self.raw_path, self.reason
)
}
}
/// Returns the normalized external path for one texture, or `None` for embedded/no-file textures.
pub fn external_texture_reference(
texture_index: usize,
texture: &ufbx::Texture,
) -> Result<Option<FbxExternalTextureReference>, FbxTexturePathError> {
if !texture.content.is_empty() {
return Ok(None);
}
let Some(raw_path) = texture_path_candidate(texture) else {
return Ok(None);
};
let relative_path = normalize_external_texture_path(raw_path).map_err(|reason| {
FbxTexturePathError {
texture_index,
raw_path: raw_path.to_string(),
reason,
}
})?;
Ok(Some(FbxExternalTextureReference {
texture_index,
element_id: texture.element.element_id,
relative_path,
}))
}
/// Returns every distinct safe external texture path in deterministic order.
pub fn external_texture_paths(
scene: &ufbx::Scene,
) -> Result<Vec<String>, Vec<FbxTexturePathError>> {
let report = external_texture_path_report(scene);
if report.errors.is_empty() {
Ok(report.paths)
} else {
Err(report.errors)
}
}
/// Discovers safe and rejected references without discarding either side of the result.
pub fn external_texture_path_report(scene: &ufbx::Scene) -> FbxExternalTexturePathReport {
let mut paths = BTreeSet::new();
let mut errors = Vec::new();
for (texture_index, texture) in scene.textures.as_ref().iter().enumerate() {
match external_texture_reference(texture_index, texture) {
Ok(Some(reference)) => {
paths.insert(reference.relative_path);
}
Ok(None) => {}
Err(error) => errors.push(error),
}
}
errors.sort_by(|left, right| {
(left.texture_index, &left.raw_path).cmp(&(right.texture_index, &right.raw_path))
});
errors.dedup();
FbxExternalTexturePathReport {
paths: paths.into_iter().collect(),
errors,
}
}
fn texture_path_candidate(texture: &ufbx::Texture) -> Option<&str> {
if !texture.relative_filename.is_empty() {
return Some(texture.relative_filename.as_ref());
}
if !texture.filename.is_empty() {
return Some(texture.filename.as_ref());
}
if !texture.absolute_filename.is_empty() {
return Some(texture.absolute_filename.as_ref());
}
None
}
fn normalize_external_texture_path(raw_path: &str) -> Result<String, String> {
let normalized = raw_path.trim().replace('\\', "/");
if normalized.is_empty() {
return Err("path is empty".into());
}
if normalized.contains('\0') {
return Err("path contains a NUL byte".into());
}
if normalized.contains('#') || normalized.contains('?') || normalized.contains("://") {
return Err("path contains asset-source, label, or query syntax".into());
}
let normalized = if is_absolute_like(&normalized) {
extract_fbm_suffix(&normalized).ok_or_else(|| {
"absolute paths are rejected unless they identify a portable .fbm sidecar".to_string()
})?
} else {
normalized
};
let mut components = Vec::new();
for component in Path::new(&normalized).components() {
match component {
Component::Normal(segment) => {
let segment = segment.to_str().ok_or_else(|| "path is not UTF-8".to_string())?;
if segment.contains(':') {
return Err("path contains a platform or asset-source prefix".into());
}
components.push(segment);
}
Component::CurDir => {}
Component::ParentDir => return Err("parent traversal is not allowed".into()),
Component::RootDir | Component::Prefix(_) => {
return Err("absolute paths are not allowed".into());
}
}
}
if components.is_empty() {
return Err("path does not identify a file".into());
}
Ok(components.join("/"))
}
fn is_absolute_like(path: &str) -> bool {
path.starts_with('/')
|| path.starts_with("//")
|| path.as_bytes().get(1).is_some_and(|byte| *byte == b':')
}
fn extract_fbm_suffix(path: &str) -> Option<String> {
let lower = path.to_ascii_lowercase();
let fbm_end = lower.rfind(".fbm/")? + ".fbm/".len();
let fbm_start = path[..fbm_end - 1]
.rfind('/')
.map(|index| index + 1)
.unwrap_or(0);
Some(path[fbm_start..].to_string())
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn sibling_texture_folder_is_preserved() {
assert_eq!(
normalize_external_texture_path("textures\\chair_diff.jpg").unwrap(),
"textures/chair_diff.jpg"
);
}
#[test]
fn absolute_fbm_path_is_portably_rebased() {
assert_eq!(
normalize_external_texture_path("C:\\Build\\Chair.fbm\\chair_diff.jpg").unwrap(),
"Chair.fbm/chair_diff.jpg"
);
}
#[test]
fn absolute_non_sidecar_path_is_rejected() {
let error = normalize_external_texture_path("C:\\Build\\textures\\chair_diff.jpg")
.unwrap_err();
assert!(error.contains("absolute paths are rejected"));
}
#[test]
fn parent_traversal_is_rejected() {
let error = normalize_external_texture_path("../shared/chair_diff.jpg").unwrap_err();
assert!(error.contains("parent traversal"));
}
#[test]
fn asset_path_syntax_is_rejected() {
assert!(normalize_external_texture_path("remote://chair_diff.jpg").is_err());
assert!(normalize_external_texture_path("textures/chair.jpg#Image0").is_err());
}
}