ComfyUI-HY-Motion1

ComfyUI-HY-Motion1

A ComfyUI plugin based on HY-Motion 1.0 for text-to-3D human motion generation.

Features

- Text-to-Motion Generation: Generate 3D human motion from text descriptions
- Prompt Rewrite: Automatically optimize text prompts and estimate motion duration using LLM
- Multi-sample Generation: Generate multiple motion samples simultaneously
- Motion Preview: Real-time skeleton preview rendering
- 3D Animation Preview: Interactive Three.js viewer with playback controls
- GLB Export: Export to GLB format with skeleton animation (no dependencies required)
- FBX Export: Export to standard FBX format for Maya/Blender and other DCC tools
- Custom Character Retargeting: Retarget motion to custom FBX models (Mixamo supported, right now)
- NPZ Save: Save in universal NPZ format
- GGUF Support: Load quantized Qwen3-8B GGUF models for lower VRAM usage
- CPU Offload: Option to run LLM models on CPU to save GPU VRAM

Installation

1. Install Dependencies

bash
cd ComfyUI/custom_nodes/ComfyUI-HY-Motion1
pip install -r requirements.txt

2. Download Model Weights

Place model weights in ComfyUI's models directory:

ComfyUI/
└── models/
    └── HY-Motion/
        └── ckpts/
            ├── tencent/
            │   ├── HY-Motion-1.0/
            │   │   ├── config.yml
            │   │   └── latest.ckpt
            │   └── HY-Motion-1.0-Lite/
            │       ├── config.yml
            │       └── latest.ckpt
            ├── GGUF/                    # Optional: for GGUF models
            │   └── Qwen3-8B-Q4_K_M.gguf
            ├── clip-vit-large-patch14   # Required for text encoding
            ├── Qwen3-0.6B              # Optional: lightweight alternative
            ├── Qwen3-8B-bnb-4bit/       # Optional: bnb-4bit quantized
            └── Qwen3-8B-AWQ/           # Optional: AWQ quantized

3. Install Additional Dependencies (Optional)

For AWQ Models

To use AWQ quantized models, install the auto-awq package:

bash
pip install auto-awq

If auto-awq installation fails, the system will automatically fall back to regular loading.

4. Model Download Links

| Model             | Source                                                                    | VRAM Required |
| Qwen3-8B-bnb-4bit | unsloth/Qwen3-8B-bnb-4bit | ~4-5GB        |
| Qwen3-8B-AWQ      | Qwen/Qwen3-8B-AWQ                 | ~3-4GB        |
| Qwen3-8B-GGUF     | Qwen/Qwen3-8B-GGUF               | ~5GB (Q4_K_M) |
| HY-Motion-1.0     | tencent/HY-Motion-1.0         | ~8GB+         |

Download using huggingface-cli:

bash
Create directory first
mkdir -p models/HY-Motion/ckpts/tencent

Download models
huggingface-cli download tencent/HY-Motion-1.0 --local-dir models/HY-Motion/ckpts/tencent

or manually download from https://huggingface.co/tencent/HY-Motion-1.0/tree/main

Node Documentation

HY-Motion Load LLM

Load Qwen3-8B LLM from HuggingFace (supports BitsAndBytes quantization).

| Parameter      | Description                                                               |
| model_name     | Select Qwen3 model from the list                                          |
| quantization   | Quantization mode:none / int8 / int4 / bnb-4bit / awq |
| offload_to_cpu | Load model on CPU i

……（后略，见原文）