Skip to content

Commit

Permalink
Fix Maya-exported rigs by not trying to topologically sort glTF nodes. (
Browse files Browse the repository at this point in the history 
bevyengine#17641)

The code added in bevyengine#14343 seems to be trying to ensure that a `Handle`
for each glTF node exists by topologically sorting the directed graph of
glTF nodes containing edges from parent to child and from skin to joint.
Unfortunately, such a graph can contain cycles, as there's no guarantee
that joints are descendants of nodes with the skin. In particular, glTF
exported from Maya using the popular babylon.js export plugin create
skins attached to nodes that animate their parent nodes. This was
causing the topological sort code to enter an infinite loop.

Assuming that the intent of the topological sort is indeed to ensure
that `Handle`s exist for each glTF node before populating them, there's
a better mechanism for this: `LoadContext::get_label_handle`. This is
the documented way to obtain a handle for a node before populating it,
obviating the need for a topological sort. This patch replaces the
topological sort with a pre-pass that uses
`LoadContext::get_label_handle` to get handles for each `Node` before
populating them. This fixes the problem with Maya rigs, in addition to
making the code simpler and faster.
  • Loading branch information
@pcwalton
pcwalton authored Feb 2, 2025
1 parent 361397f commit 7774a62
Show file tree
Hide file tree
Showing 2 changed files with 74 additions and 111 deletions.
2 changes: 2 additions & 0 deletions crates/bevy_gltf/Cargo.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,8 @@ gltf = { version = "1.4.0", default-features = false, features = [
] }
thiserror = { version = "2", default-features = false }
base64 = "0.22.0"
fixedbitset = "0.5"
itertools = "0.13"
percent-encoding = "2.1"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1"
Expand Down
183 changes: 72 additions & 111 deletions crates/bevy_gltf/src/loader.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@ use crate::{
GltfMaterialName, GltfMeshExtras, GltfNode, GltfSceneExtras, GltfSkin,
};

use alloc::collections::VecDeque;
use bevy_asset::{
io::Reader, AssetLoadError, AssetLoader, Handle, LoadContext, ReadAssetBytesError,
};
Expand Down Expand Up @@ -42,6 +41,7 @@ use bevy_scene::Scene;
#[cfg(not(target_arch = "wasm32"))]
use bevy_tasks::IoTaskPool;
use bevy_transform::components::Transform;
use fixedbitset::FixedBitSet;
use gltf::{
accessor::Iter,
image::Source,
Expand All @@ -50,6 +50,7 @@ use gltf::{
texture::{Info, MagFilter, MinFilter, TextureTransform, WrappingMode},
Document, Material, Node, Primitive, Semantic,
};
use itertools::Itertools;
use serde::{Deserialize, Serialize};
#[cfg(any(
feature = "pbr_specular_textures",
Expand Down Expand Up @@ -793,13 +794,36 @@ async fn load_gltf<'a, 'b, 'c>(
let mut named_nodes = <HashMap<_, _>>::default();
let mut skins = vec![];
let mut named_skins = <HashMap<_, _>>::default();
for node in GltfTreeIterator::try_new(&gltf)? {

// First, create the node handles.
for node in gltf.nodes() {
let label = GltfAssetLabel::Node(node.index());
let label_handle = load_context.get_label_handle(label.to_string());
nodes.insert(node.index(), label_handle);
}

// Then check for cycles.
check_gltf_for_cycles(&gltf)?;

// Now populate the nodes.
for node in gltf.nodes() {
let skin = node.skin().map(|skin| {
let joints = skin
let joints: Vec<_> = skin
.joints()
.map(|joint| nodes.get(&joint.index()).unwrap().clone())
.collect();

if joints.len() > MAX_JOINTS {
warn!(
"The glTF skin {} has {} joints, but the maximum supported is {}",
skin.name()
.map(ToString::to_string)
.unwrap_or_else(|| skin.index().to_string()),
joints.len(),
MAX_JOINTS
);
}

let gltf_skin = GltfSkin::new(
&skin,
joints,
Expand Down Expand Up @@ -1904,114 +1928,6 @@ async fn load_buffers(
Ok(buffer_data)
}

/// Iterator for a Gltf tree.
///
/// It resolves a Gltf tree and allows for a safe Gltf nodes iteration,
/// putting dependent nodes before dependencies.
struct GltfTreeIterator<'a> {
nodes: Vec<Node<'a>>,
}

impl<'a> GltfTreeIterator<'a> {
#[expect(
clippy::result_large_err,
reason = "`GltfError` is only barely past the threshold for large errors."
)]
fn try_new(gltf: &'a gltf::Gltf) -> Result<Self, GltfError> {
let nodes = gltf.nodes().collect::<Vec<_>>();

let mut empty_children = VecDeque::new();
let mut parents = vec![None; nodes.len()];
let mut unprocessed_nodes = nodes
.into_iter()
.enumerate()
.map(|(i, node)| {
let children = node
.children()
.map(|child| child.index())
.collect::<HashSet<_>>();
for &child in &children {
let parent = parents.get_mut(child).unwrap();
*parent = Some(i);
}
if children.is_empty() {
empty_children.push_back(i);
}
(i, (node, children))
})
.collect::<HashMap<_, _>>();

let mut nodes = Vec::new();
let mut warned_about_max_joints = <HashSet<_>>::default();
while let Some(index) = empty_children.pop_front() {
if let Some(skin) = unprocessed_nodes.get(&index).unwrap().0.skin() {
if skin.joints().len() > MAX_JOINTS && warned_about_max_joints.insert(skin.index())
{
warn!(
"The glTF skin {} has {} joints, but the maximum supported is {}",
skin.name()
.map(ToString::to_string)
.unwrap_or_else(|| skin.index().to_string()),
skin.joints().len(),
MAX_JOINTS
);
}

let skin_has_dependencies = skin
.joints()
.any(|joint| unprocessed_nodes.contains_key(&joint.index()));

if skin_has_dependencies && unprocessed_nodes.len() != 1 {
empty_children.push_back(index);
continue;
}
}

let (node, children) = unprocessed_nodes.remove(&index).unwrap();
assert!(children.is_empty());
nodes.push(node);

if let Some(parent_index) = parents[index] {
let (_, parent_children) = unprocessed_nodes.get_mut(&parent_index).unwrap();

assert!(parent_children.remove(&index));
if parent_children.is_empty() {
empty_children.push_back(parent_index);
}
}
}

if !unprocessed_nodes.is_empty() {
return Err(GltfError::CircularChildren(format!(
"{:?}",
unprocessed_nodes
.iter()
.map(|(k, _v)| *k)
.collect::<Vec<_>>(),
)));
}

nodes.reverse();
Ok(Self {
nodes: nodes.into_iter().collect(),
})
}
}

impl<'a> Iterator for GltfTreeIterator<'a> {
type Item = Node<'a>;

fn next(&mut self) -> Option<Self::Item> {
self.nodes.pop()
}
}

impl<'a> ExactSizeIterator for GltfTreeIterator<'a> {
fn len(&self) -> usize {
self.nodes.len()
}
}

enum ImageOrPath {
Image {
image: Image,
Expand Down Expand Up @@ -2415,6 +2331,51 @@ fn material_needs_tangents(material: &Material) -> bool {
false
}

/// Checks all glTF nodes for cycles, starting at the scene root.
#[expect(
clippy::result_large_err,
reason = "need to be signature compatible with `load_gltf`"
)]
fn check_gltf_for_cycles(gltf: &gltf::Gltf) -> Result<(), GltfError> {
// Initialize with the scene roots.
let mut roots = FixedBitSet::with_capacity(gltf.nodes().len());
for root in gltf.scenes().flat_map(|scene| scene.nodes()) {
roots.insert(root.index());
}

// Check each one.
let mut visited = FixedBitSet::with_capacity(gltf.nodes().len());
for root in roots.ones() {
check(gltf.nodes().nth(root).unwrap(), &mut visited)?;
}
return Ok(());

// Depth first search.
#[expect(
clippy::result_large_err,
reason = "need to be signature compatible with `load_gltf`"
)]
fn check(node: Node, visited: &mut FixedBitSet) -> Result<(), GltfError> {
// Do we have a cycle?
if visited.contains(node.index()) {
return Err(GltfError::CircularChildren(format!(
"glTF nodes form a cycle: {} -> {}",
visited.ones().map(|bit| bit.to_string()).join(" -> "),
node.index()
)));
}

// Recurse.
visited.insert(node.index());
for kid in node.children() {
check(kid, visited)?;
}
visited.remove(node.index());

Ok(())
}
}

#[cfg(test)]
mod test {
use std::path::Path;
Expand Down

0 comments on commit 7774a62

Please sign in to comment.