Skip to content

[Bug] Animation clip can register and play with zero matching joints on namespace/hierarchy mismatch #1318

Description

@untoldengine

Problem

An animation clip can register successfully (registerRuntimeAnimationClips) even when none of its channels resolve against the target skeleton's joint paths — e.g. a namespace prefix mismatch ("skel:LeftArm" vs "LeftArm") or a hierarchy mismatch (differing parent chains) between the exported clip and the skeleton it's bound to. In that case the clip is added to animationComponent.animationClips and plays back without error, but every joint samples from its rest pose (CompiledAnimationClip.Channel.animated == false for all channels) — the character silently doesn't animate.

There's currently no validation step that reports this clearly. The caller sees a clip selected and playing (currentAnimation set, currentTime advancing) with no visible motion and no error, which makes a namespace/hierarchy export mismatch hard to diagnose — it looks identical to "the clip has no keyframes" or "the pose is correct but tiny," not "the paths never matched."

Proposed fix

  • When a clip is registered (or first compiled against a skeleton via AnimationComponent.compiledClip), check whether at least one channel actually resolved to an animated joint.
  • If zero channels matched, surface this clearly instead of silently succeeding — e.g. a new handleError case (mirroring the existing .noAnimationClip pattern in Systems/ErrorHandlingSystem.swift) that names the clip, the entity, and ideally a hint that no joint path in the clip matched the skeleton (common cause: namespace prefix or hierarchy mismatch).
  • Consider whether registration should still succeed (so partial/intentional no-op clips aren't blocked) or whether this should only be a loud diagnostic, not a hard failure.

Acceptance criteria

  • A clip whose channels animate zero joints against the bound skeleton is clearly reported (not a silent no-op).
  • The error/diagnostic distinguishes this case from other existing clip errors (e.g. .noAnimationClip) and names the clip/entity involved.
  • Regression test: register a clip with mismatched joint paths (namespace or hierarchy mismatch) against a skeleton and assert the mismatch is reported rather than silently accepted.

Context

Surfaced while reviewing PR #1316 (animation playback helpers / one-shot clip fixes) — that PR addresses a separate root-motion wrapping bug (now closed by #1314/#1316) but does not touch clip registration or joint-path validation, so this is tracked separately.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions