ComfyUI Extension: ComfyUI HunyuanWorld - Professional 3D World Generation
Transform text and images into immersive 360° 3D worlds using Tencent's HunyuanWorld-1.0 in ComfyUI with native FLUX architecture integration.
Custom Nodes (0)
README
NOT WORKING YET!!!!!
ComfyUI HunyuanWorld Node Pack
A comprehensive ComfyUI node pack for HunyuanWorld offering text-to-panorama generation, 3D world reconstruction, and related utilities directly within ComfyUI.
🔧 Development Status: Offline Mode In Progress
This node pack aims for complete offline operation but currently requires additional configuration development. For immediate offline panorama generation, use the recommended workaround below.
Requirements
- ComfyUI (latest)
- Python 3.x
- CUDA-enabled GPU (for accelerated models)
- Dependencies: see requirements.txt
Installation
Automatic Installation (Recommended)
-
Clone this repository into your ComfyUI custom_nodes directory:
cd C:\ComfyUI\custom_nodes git clone https://github.com/cedarconnor/ComfyUI_HunyuanWorld.git
-
Install all dependencies with a single command:
cd C:\ComfyUI\custom_nodes\ComfyUI_HunyuanWorld C:\ComfyUI\.venv\Scripts\python.exe -m pip install -r requirements.txt C:\ComfyUI\.venv\Scripts\python.exe install.py
-
Place model files:
- FLUX Base Models →
C:\ComfyUI\models\unet\
- flux1-dev-fp8.safetensors
- flux1-fill-dev.safetensors
- HunyuanWorld Models →
C:\ComfyUI\models\Hunyuan_World\
- HunyuanWorld-PanoDiT-Text.safetensors
- HunyuanWorld-PanoDiT-Image.safetensors
- HunyuanWorld-PanoInpaint-Scene.safetensors
- HunyuanWorld-PanoInpaint-Sky.safetensors
- FLUX Base Models →
-
Restart ComfyUI to load the new nodes.
Manual Installation (If automatic fails)
If the automatic installation encounters issues, install dependencies manually:
# Core requirements
C:\ComfyUI\.venv\Scripts\python.exe -m pip install -r requirements.txt
# Git-based dependencies
C:\ComfyUI\.venv\Scripts\python.exe -m pip install "git+https://github.com/EasternJournalist/utils3d.git"
C:\ComfyUI\.venv\Scripts\python.exe -m pip install "git+https://github.com/microsoft/MoGe.git"
# Additional HunyuanWorld dependencies
C:\ComfyUI\.venv\Scripts\python.exe -m pip install basicsr realesrgan zim-anything easydict
Troubleshooting
Import Errors: If you see "HunyuanWorld modules are not available", ensure all dependencies are installed. Run the installation verification:
C:\ComfyUI\.venv\Scripts\python.exe install.py
Model Requirements: The node pack automatically detects your ComfyUI installation and loads components from standard directories:
- FLUX models:
C:\ComfyUI\models\unet\
(flux1-dev-fp8.safetensors, flux1-fill-dev.safetensors) - HunyuanWorld LoRAs:
C:\ComfyUI\models\Hunyuan_World\
(HunyuanWorld-PanoDiT-Text.safetensors, HunyuanWorld-PanoDiT-Image.safetensors) - CLIP encoder:
C:\ComfyUI\models\clip\clip_l.safetensors
- T5 encoder:
C:\ComfyUI\models\text_encoders\t5xxl_fp16.safetensors
- FLUX VAE:
C:\ComfyUI\models\vae\ae.safetensors
Recommended Offline Workaround:
- Use ComfyUI's native FLUX Dev node to load
flux1-dev-fp8.safetensors
- Add LoRA Loader node with
HunyuanWorld-PanoDiT-Text.safetensors
- Generate panoramas using the combined FLUX + HunyuanWorld LoRA workflow
- This provides the same panorama generation capability using ComfyUI's proven model loading system
VRAM Issues: Use CPU offloading and VAE tiling in the model loader settings for systems with limited VRAM.
Performance: For faster generation, ensure you have sufficient VRAM and use bfloat16 precision.
Node Categories
Loaders
- HYW_ModelLoader: Load HunyuanWorld models and create runtime instance
- HYW_SettingsLoader: Load settings from
settings.json
- HYW_Config: Create or override inference configuration
Generation
- HYW_PanoGen: Generate panorama (text or image conditioned)
- HYW_PanoGenBatch: Batch panorama generation
- HYW_PanoInpaint_Scene: Inpaint scene regions in panorama
- HYW_PanoInpaint_Advanced: Advanced multi-region inpainting
- HYW_PanoInpaint_Sky: Inpaint sky regions
- HYW_SkyMaskGenerator: Generate sky mask for panorama
Reconstruction
- HYW_WorldReconstructor: Reconstruct 3D world mesh from panorama
- HYW_MeshProcessor: Process and clean mesh geometry
- HYW_MeshAnalyzer: Analyze mesh quality and statistics
Export
- HYW_TextureBaker: Bake PBR textures from panorama and mesh data
- HYW_MeshExport: Export mesh and textures to GLB/OBJ/etc.
- HYW_Thumbnailer: Generate 3D world preview thumbnails
Utils
- HYW_SeamlessWrap360: Seamlessly wrap panoramas horizontally
- HYW_PanoramaValidator: Validate panorama images
- HYW_MetadataManager: Manage workflow metadata and hashing
Examples
See the examples/
directory for detailed step-by-step guides:
Configuration
Edit settings.json
to configure default model paths, runtime parameters, and optimizations. For example:
{
"model_paths": {
"flux_text": "models/unet/flux1-dev-fp8.safetensors",
"flux_image": "models/unet/flux1-fill-dev.safetensors",
"pano_text_lora": "models/Hunyuan_World/HunyuanWorld-PanoDiT-Text.safetensors",
"pano_image_lora": "models/Hunyuan_World/HunyuanWorld-PanoDiT-Image.safetensors"
},
"device": "cuda:0",
"dtype": "bfloat16",
"defaults": {
"pano_size": [1920, 960],
"guidance_scale": 30.0,
"num_inference_steps": 50,
"blend_extend": 6,
"true_cfg_scale": 0.0,
"shifting_extend": 0
},
"optimization": {
"enable_model_cpu_offload": true,
"enable_vae_tiling": true,
"enable_xformers": true
}
}
Contributing
Contributions welcome! Please open issues or PRs to add new features, improve documentation, or fix bugs.
License
This project follows the HunyuanWorld-1.0 Community License. See the original repository for details.