feat(cli): tres gltf --animations, clips from separate files - #1476
Merged
Conversation
- Introduced the `--animations` option to allow merging of animation clips from separate files with the model's own animations. - Updated documentation to reflect the new `--animations` feature, including usage examples for loading multiple animation files. - Enhanced the CLI to parse and validate animation clip files, ensuring proper integration with the model. - Added tests to verify the functionality of the new animation merging feature, including handling of overlapping clip names and reporting of loaded clips.
- Changed warning indicators in the documentation to use a consistent ⚠ symbol for clarity. - Updated the command examples to reflect the correct paths and options for the Engineer model. - Enhanced output messages in the CLI to provide more detailed information about parsed nodes, meshes, and animation clips. - Adjusted the `--verbose` flag description to specify that it lists both slot and clip names.
✅ Deploy Preview for cientos-tresjs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for rapier-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for tresjs-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for postprocessing-tresjs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for tresjs-lab ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
@tresjs/cientos
@tresjs/core
@tresjs/eslint-config
@tresjs/leches
@tresjs/nuxt
@tresjs/post-processing
@tresjs/rapier
commit: |
…tional tests - Updated the GLTF command to explicitly type the `sources` array as `AnimationSourceInput[]` for better type safety. - Added new tests to verify the correct binding of animation clips and node name sanitization in the build IR process. - Improved documentation within tests to clarify the purpose of retarget checks and node name handling.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Mixamo, KayKit and Quaternius all ship the mesh in one file and the clips in others, so
tres gltfon a rig export produced a component with an emptyactionsand no hint as to why.This adds
-a, --animations <path>, repeatable, and merges the clips at generate time.tres gltf public/models/Engineer.glb \ -a public/models/animations/Rig_Medium/Rig_Medium_General.glb \ -a public/models/animations/Rig_Medium/Rig_Medium_MovementBasic.glb \ -a public/models/animations/Rig_Medium/Rig_Medium_MovementAdvanced.glb -o src/models ▲ ■ ● Tres gltf Engineer.glb ✔ Parse 51 named nodes · 8 meshes · 1 material · 37 clips merged 37ms ✔ Emit 6 slots 1ms ✔ src/models/Engineer.gen.vue slots Engineer_ArmLeft, Engineer_ArmRight, Engineer_Body, Engineer_Head, Engineer_LegLeft, Engineer_LegRight clips Death_A, Death_A_Pose, Death_B, Death_B_Pose, Hit_A, Hit_B, … 31 more — rerun with --verbose Done in 87msEach file gets its own
useGLTF(its own url inferred frompublic/, its own{ draco: true }when compressed) and the clips are concatenated, model first:
That
isLoadingguard is the load-order bug this would otherwise ship: a clip library is afraction of the size of the model it drives, so it resolves first, and a mixer handed clips
before the tree exists binds every track to nothing — which three caches rather than retries.
ActionNamebecomes the union across every file, and the node names the external clips drivesurvive pruning exactly like the model's own do.
Both files are parsed, so both can be checked
Track targets. Each external clip's track names are resolved against the model's node
names before anything is emitted — the one animation failure that is completely silent at
runtime. A clip that binds partially is reported; a clip nothing of which binds is left out of
ActionNameentirely rather than sitting there doing nothing:Name collisions. Clip libraries overlap (the three above all ship a
T-Pose). The arraydecides: last file passed wins,
ActionNamelists the name once, and the CLI says which filewon instead of leaving it to be discovered.
A rig with nothing to play now points at the flag rather than generating a mute component:
Elsewhere
--dry-runcounts each file on its own line plus the merged total, which is neither the sumnor the model's own count.
--instanceworks with it: the provider file owns the loads and the merge, the consumerreads
animationsoff the injected context./cientos/loaders/gltf-animations— a KayKit Engineer rig with zero clipsof its own, 37 merged from three libraries, in a dropdown.
Test plan
tres gltf public/models/Engineer.glb -a <clips>.glbwrites a component whoseactionsis keyed by the merged union
plays
ActionName-awarns and points at the flag-apath errors by name, not with a bare ENOENT--dry-runreports per-file counts and the merged total-acombined with--instanceputs the loads in the provider file(load-order guard)