README.md
March 9, 2026 · View on GitHub
ComfyUI-HyMotion
Text-to-Motion Generation · Robust FBX Retargeting · Interactive 3D Preview
A full-featured ComfyUI implementation of HY-MOTION 1.0, enabling high-fidelity human motion generation from text prompts. This node pack provides a complete pipeline from text description to rigged FBX animation, with real-time 3D preview capabilities and robust retargeting to custom skeletons.
✨ Key Features
| Feature | Description |
|---|---|
| Text-to-Motion | Generate realistic human animations from natural language descriptions using DiT (Diffusion Transformer) architecture |
| Robust Retargeting | Transfer SMPL-H motions to custom skeletons (Mixamo, DAZ(G3 and G9) UE5, UniRig) with intelligent fuzzy mapping, canonical T-pose support, and geometric fallbacks |
| Interactive 3D Viewer | Three.js preview with transform gizmos (G/R/S keys), resizable viewport, and smooth sub-frame interpolation |
| Prompt Enhancement | AI-powered prompt rewriting with automatic duration estimation using Text2MotionPrompter |
| Multiple Export Formats | Export to FBX (with skeleton & textures) or NPZ (raw SMPL-H data) |
| SMPL Integration | Convert motion capture data (GVHMR/MotionCapture output) to HY-Motion format for retargeting |
| MHR GPU Converter | Ultra-fast GPU-accelerated MHR-to-HyMotion conversion with finger fitting and auto-alignment |
| GGUF Support | Memory-efficient text encoding with quantized Qwen3 models via ComfyUI-GGUF |
🚀 Installation
Option 1: Manual Installation
cd ComfyUI/custom_nodes
git clone https://github.com/Aero-Ex/ComfyUI-HyMotion
cd ComfyUI-HyMotion
pip install -r requirements.txt
Note
The installation includes fbxsdkpy from a custom PyPI index for FBX support.
📦 Model Downloads
Core Motion Models
Download and place in ComfyUI/models/hymotion/:
| Model | Size | Description | Download |
|---|---|---|---|
| HY-Motion-1.0 | ~4.5GB | Full quality model | latest.ckpt |
| HY-Motion-1.0-Lite | ~1.5GB | Faster, lower VRAM | latest.ckpt |
Directory structure:
ComfyUI/models/hymotion/
├── HY-Motion-1.0/
│ └── latest.ckpt
└── HY-Motion-1.0-Lite/
└── latest.ckpt
Text Encoders
Download and place in ComfyUI/models/text_encoders/:
| Encoder | Format | Description | Download |
|---|---|---|---|
| CLIP ViT-L/14 | SafeTensors | Visual-text encoder | clip-vit-large-patch14.safetensors |
| Qwen3-8B | FP8 | Language model (16GB+ VRAM) | Qwen3-8B_fp8.safetensors |
| Qwen3-8B | GGUF | Quantized (lower VRAM) | Browse GGUF options |
🔧 Node Reference
Core Pipeline Nodes (HY-Motion/modular)
| Node | Purpose | Inputs | Outputs |
|---|---|---|---|
| HY-Motion DiT Loader | Load the motion generation model | Model name, device | HYMOTION_DIT |
| HY-Motion Text Encoder Loader | Load CLIP + Qwen3 text encoders | CLIP model, LLM model, device | HYMOTION_TEXT_ENCODER |
| HY-Motion Text Encode | Convert text prompt to embeddings | Text encoder, prompt | HYMOTION_TEXT_EMBEDS |
| HY-Motion Sampler | Generate motion from embeddings | DiT, embeds, duration, seed, CFG | HYMOTION_DATA |
| HY-Motion Export FBX | Export motion to FBX file | Motion data, template, FPS, scale | FBX file path |
| HY-Motion Prompt Rewrite | Enhance prompt & estimate duration | Raw prompt, enhancer mode | Rewritten prompt, duration |
Preview Nodes (HY-Motion/view)
| Node | Purpose | Description |
|---|---|---|
| HY-Motion 2D Motion Preview | Render motion as image sequence | Matplotlib-based skeleton visualization with camera controls |
| HY-Motion 3D Model Loader | Load FBX/GLB/GLTF/OBJ files | Interactive Three.js viewer with transform controls |
| HY-Motion FBX Player | Play FBX animations (legacy) | Dedicated FBX playback from output directory |
Utility Nodes (HY-Motion/utils)
| Node | Purpose |
|---|---|
| HY-Motion Save NPZ | Export raw SMPL-H motion data to NumPy format |
| HY-Motion Retarget to FBX | Transfer SMPL-H motion to custom skeletons with robust bone mapping |
| HY-Motion SMPL to Data | Convert SMPL parameters from motion capture to HY-Motion format |
MHR Conversion Nodes (HY-Motion/loaders, HY-Motion/converters)
| Node | Purpose | Inputs | Outputs |
|---|---|---|---|
| HY-Motion MHR Loader | Load MHR vertex data from NPZ files | MHR NPZ name | MHR_DATA |
| HY-Motion MHR Converter (GPU) | Ultra-fast GPU-accelerated conversion with opt-in finger fitting | MHR Data, fit_hands, flip_orientation | HYMOTION_DATA |
📋 Workflows
Sample workflows are included in the workflows/ directory:
workflows/HunyuanMotion.json: Basic text-to-motion pipeline.workflows/Text_Video-To-3DMotion.json: Advanced pipeline with video-to-motion and retargeting.
⚙️ Technical Details
Advanced Character Support
The retargeting engine in v1.0.3 has been updated for professional production workflows with a focus on stability and ease of use:
- Daz Genesis G3 & G9 Support: Explicitly tuned for Daz characters.
-
Important
-
Optimal Daz Workflow: For best results, first import your Daz character into Blender then export it from Blender as an FBX file. This ensures all bone orientations are normalized and provides the highest quality retargeting.
-
- Automatic Rig Normalization: Automatically detects Daz G3/G8/G9 rigs and cleans up complex FBX Pre/Post rotations, preventing the "exploding bone" distortions common in raw exports.
- UE5 Manny IK Snapping: Automatically snaps
ik_footandik_handbones to their biological counterparts using a recursive FK solver, ensuring full compatibility with the UE5 Mannequin standard. - UniRig/ArticulationXL: Built-in support for UniRig-detected skeletons.
- Canonical T-Pose: Intelligent rest-pose detection for stable retargeting from SMPL-H (NPZ) sources.
- Geometric Fallbacks: Advanced bone matching using hierarchy analysis and relative position when names do not match.
- In-Place Support: Lock root motion for horizontal axes to create clean game-ready loopable animations.
Requirements
- Python 3.11+
- CUDA-compatible GPU (5GB+ VRAM recommended)
- ComfyUI (latest version)
📂 Repository Structure
ComfyUI-HyMotion/
├── hymotion/ # Core logic and utilities
│ ├── network/ # DiT and Text Encoder architectures
│ ├── pipeline/ # Diffusion sampling logic
│ └── utils/ # Retargeting, loaders, and math utilities
├── nodes_modular.py # Primary ComfyUI node definitions
├── nodes_2d_preview.py # 2D visualization nodes
├── nodes_3d_viewer.py # 3D viewer integration
├── web/ # Frontend for 3D viewer
├── workflows/ # Example ComfyUI workflows
└── tests/ # Parity and integration tests
🤝 Contributing
Contributions are welcome! Please feel free to submit issues and pull requests.
📜 Credits
This project is based on the following research and implementations:
- HY-Motion - High-fidelity human motion generation.
- MHR (Mesh-based Human Reconstruction) - High-fidelity mesh reconstruction from video (the basis for our GPU conversion pipeline).
- SMPL-X - Expressive body model.
ComfyUI implementation by Aero-Ex.