ComfyUI Extension: ComfyUI HunyuanWorld - Professional 3D World Generation

Authored by cedarconnor

Created

Updated

6 stars

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)

    1. Clone this repository into your ComfyUI custom_nodes directory:

      cd C:\ComfyUI\custom_nodes
      git clone https://github.com/cedarconnor/ComfyUI_HunyuanWorld.git
      
    2. 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
      
    3. Place model files:

      • FLUX Base ModelsC:\ComfyUI\models\unet\
        • flux1-dev-fp8.safetensors
        • flux1-fill-dev.safetensors
      • HunyuanWorld ModelsC:\ComfyUI\models\Hunyuan_World\
        • HunyuanWorld-PanoDiT-Text.safetensors
        • HunyuanWorld-PanoDiT-Image.safetensors
        • HunyuanWorld-PanoInpaint-Scene.safetensors
        • HunyuanWorld-PanoInpaint-Sky.safetensors
    4. 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:

    1. Use ComfyUI's native FLUX Dev node to load flux1-dev-fp8.safetensors
    2. Add LoRA Loader node with HunyuanWorld-PanoDiT-Text.safetensors
    3. Generate panoramas using the combined FLUX + HunyuanWorld LoRA workflow
    4. 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.