Skip to content

Conversation

@greeble-dev
Copy link
Contributor

@greeble-dev greeble-dev commented Dec 6, 2025

Objective

Enable features like keeping meshes and animations in separate glTFs, and binding meshes to another mesh's animation player.

Background

When bevy_animation is enabled, bevy_gltf will:

  • Check which hierarchies have nodes affected by animations.
  • For each animated hierarchy:
    • For the root node, add an AnimationPlayer component.
    • For each node, add an AnimationTargetId component, and an AnimatedBy component that points to the root node.

This works well for glTFs that are self-contained meshes with animations. But it fails for two cases:

  1. Separate mesh and animation glTFs.
    • The mesh wants the full suite of animation components, but gets none of them since its glTF has no animations.
  2. Binding a mesh to another mesh's animation player.
    • The mesh wants the glTF loader to give it AnimationTargetId components so it can bind to animations.
    • It doesn't want AnimatedBy and AnimationPlayer components created automatically - the AnimatedBy components will be created separately when binding to the other mesh's player.
    • See 🧪 Bone attachments #18262 for an example.

Solution

Add these settings:

/// Decides if the loader will create [`AnimationTargetId`] components. These
/// are used to identify which parts of an [`AnimationClip`] can be applied to
/// a node.
pub enum GltfCreateAnimationTargetIds {
    /// Never create `AnimationTargetId`s.
    Never,
    /// Always create `AnimationTargetId`s. This is typically used when the glTF
    /// does not contain animations itself, but might be bound to animations in
    /// another glTF or some other source.
    Always,
    /// Only create `AnimationTargetId`s for a hierarchy if at least one node in
    /// the hierarchy is affected by an animation within the glTF.
    #[default]
    Automatically,
}

/// Decides if the loader will create [`AnimationPlayer`] and [`AnimatedBy`]
/// components.
///
/// These components are only created if a hierarchy has [`AnimationTargetId`]
/// components (see [`GltfCreateAnimationTargetIds`]). `AnimationPlayer` components
/// are created on the root node of a hierarchy. `AnimatedBy` components are
/// created on all nodes in a hierarchy, alongside the `AnimationTargetId`
/// components.
pub enum GltfCreateAnimationPlayers {
    /// Never create `AnimationPlayer` and `AnimatedBy` components.
    Never,
    /// Only create `AnimationPlayer` and `AnimatedBy` components if
    /// the hierarchy has `AnimationTargetId` components.
    #[default]
    Automatically,
}

So for the two example cases:

  1. Separate mesh and animation glTFs.
    • Set CreateAnimationTargetIds::Always.
  2. Binding a mesh to another mesh's animation player.
    • Set CreateAnimationTargetIds::Always if necessary, and CreateAnimationPlayers::Never.

The PR also moves the component creation code from load_node to where the scenes are created. This made the logic a bit simpler, and I think it's nicer if everything is done in one self-contained step rather then being mixed in with other per-node work.

Testing

Tested every combination of settings on a few glTFs with and without animation. Also:

# Check that `bevy_gltf` compiles without `bevy_animation`.
cargo check --no-default-features --features "bevy_gltf"

@greeble-dev greeble-dev added C-Feature A new feature, making something new possible A-Animation Make things move and change over time S-Needs-Review Needs reviewer attention (from anyone!) to move forward A-glTF Related to the glTF 3D scene/model format labels Dec 6, 2025
@greeble-dev greeble-dev changed the title Add bevy_gltf settings that control when animation players and targets are created Add bevy_gltf settings for animation player and target creation Dec 7, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

A-Animation Make things move and change over time A-glTF Related to the glTF 3D scene/model format C-Feature A new feature, making something new possible S-Needs-Review Needs reviewer attention (from anyone!) to move forward

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant