A043-studios-ComfyUI_HunyuanWorldnode/INSTALL_GUIDE.md

# 📦 Complete Installation Guide for ComfyUI-HunyuanWorld

This guide provides step-by-step instructions for installing ComfyUI-HunyuanWorld from GitHub.

## 🎯 Quick Start (TL;DR)

```bash
cd ComfyUI/custom_nodes
git clone https://github.com/A043-studios/ComfyUI_HunyuanWorldnode.git
cd ComfyUI_HunyuanWorldnode
python install.py
# Restart ComfyUI
```

## 📋 Prerequisites

### System Requirements
- **OS**: Windows 10+, macOS 10.15+, or Linux (Ubuntu 18.04+)
- **Python**: 3.8 or higher
- **GPU**: NVIDIA GPU with 4GB+ VRAM (recommended)
- **RAM**: 8GB+ system RAM
- **Storage**: 10GB+ free space (for models)

### Software Requirements
- [ComfyUI](https://github.com/comfyanonymous/ComfyUI) installed and working
- Git (for cloning the repository)
- Python package manager (pip)

## 🚀 Installation Methods

### Method 1: ComfyUI Manager (Easiest)

1. **Install ComfyUI Manager** (if not already installed):
   ```bash
   cd ComfyUI/custom_nodes
   git clone https://github.com/ltdrdata/ComfyUI-Manager.git
   ```

2. **Restart ComfyUI** and you'll see the Manager button

3. **Search and Install**:
   - Click the Manager button
   - Search for "HunyuanWorld"
   - Click "Install"
   - Restart ComfyUI

### Method 2: Git Clone (Recommended)

1. **Navigate to ComfyUI custom_nodes directory**:
   ```bash
   cd ComfyUI/custom_nodes
   ```

2. **Clone the repository**:
   ```bash
   git clone https://github.com/A043-studios/ComfyUI_HunyuanWorldnode.git
   ```

3. **Navigate to the cloned directory**:
   ```bash
   cd ComfyUI_HunyuanWorldnode
   ```

4. **Run the installation script**:
   ```bash
   python install.py
   ```
   
   Or install manually:
   ```bash
   pip install -r requirements.txt
   ```

5. **Restart ComfyUI**

### Method 3: Download ZIP

1. **Download the latest release**:
   - Go to [Releases](https://github.com/A043-studios/ComfyUI_HunyuanWorldnode/releases)
   - Download the latest ZIP file

2. **Extract to ComfyUI**:
   - Extract to `ComfyUI/custom_nodes/ComfyUI_HunyuanWorldnode`

3. **Install dependencies**:
   ```bash
   cd ComfyUI/custom_nodes/ComfyUI_HunyuanWorldnode
   python install.py
   ```

4. **Restart ComfyUI**

## 🔧 Advanced Installation

### Virtual Environment (Recommended for Development)

```bash
# Create virtual environment
python -m venv hunyuanworld_env

# Activate virtual environment
# On Windows:
hunyuanworld_env\Scripts\activate
# On macOS/Linux:
source hunyuanworld_env/bin/activate

# Install ComfyUI-HunyuanWorld
cd ComfyUI/custom_nodes
git clone https://github.com/yourusername/ComfyUI-HunyuanWorld.git
cd ComfyUI-HunyuanWorld
pip install -r requirements.txt
```

### Docker Installation (Coming Soon)

```bash
# Pull the image
docker pull yourusername/comfyui-hunyuanworld:latest

# Run with GPU support
docker run --gpus all -p 8188:8188 yourusername/comfyui-hunyuanworld:latest
```

### Development Installation

```bash
# Clone with development dependencies
git clone https://github.com/A043-studios/ComfyUI_HunyuanWorldnode.git
cd ComfyUI_HunyuanWorldnode

# Install in development mode
pip install -e .[dev]

# Install pre-commit hooks
pre-commit install
```

## 🧪 Verification

### Test Installation

1. **Check if nodes are available**:
   - Start ComfyUI
   - Right-click in the workflow area
   - Look for "HunyuanWorld" in the node menu

2. **Run the test script**:
   ```bash
   cd ComfyUI/custom_nodes/ComfyUI-HunyuanWorld
   python examples/simple_workflow.py
   ```

3. **Check dependencies**:
   ```bash
   python -c "import __init__; print('✅ Import successful')"
   ```

### Expected Output

You should see nodes like:
- 🌍 HunyuanWorld: Model Loader (Real)
- 🌍 HunyuanWorld: Image to 3D (Real)
- 🌍 HunyuanWorld: Simple Image to 3D
- 🌍 HunyuanWorld: Hybrid Generator

## 🔍 Troubleshooting

### Common Issues

#### "Module not found" errors
```bash
# Ensure you're in the right directory
cd ComfyUI/custom_nodes/ComfyUI-HunyuanWorld

# Reinstall dependencies
pip install -r requirements.txt --force-reinstall
```

#### "CUDA out of memory"
```bash
# Use low VRAM settings
# In the node settings:
# - Set low_vram_mode=True
# - Use precision="fp16"
# - Use model="tencent/Hunyuan3D-2mini"
```

#### "Hunyuan3D libraries not available"
```bash
# Install Hunyuan3D from source
git clone https://github.com/tencent/hunyuan3d-2.git
cd hunyuan3d-2
pip install -e .
```

#### Nodes not appearing in ComfyUI
1. Check ComfyUI console for error messages
2. Ensure ComfyUI was restarted after installation
3. Verify the installation directory is correct
4. Check file permissions

### Getting Help

1. **Check the logs**: Look at ComfyUI console output for error messages
2. **Search issues**: Check [GitHub Issues](https://github.com/A043-studios/ComfyUI_HunyuanWorldnode/issues)
3. **Create an issue**: Use the bug report template
4. **Community support**: Ask in ComfyUI Discord/Reddit

## 🔄 Updating

### Update from Git
```bash
cd ComfyUI/custom_nodes/ComfyUI_HunyuanWorldnode
git pull origin main
pip install -r requirements.txt --upgrade
```

### Update via ComfyUI Manager
1. Open ComfyUI Manager
2. Go to "Update" tab
3. Find ComfyUI-HunyuanWorld
4. Click "Update"

## 🗑️ Uninstallation

```bash
# Remove the directory
rm -rf ComfyUI/custom_nodes/ComfyUI-HunyuanWorld

# Or on Windows
rmdir /s ComfyUI\custom_nodes\ComfyUI-HunyuanWorld
```

## 📚 Next Steps

After successful installation:

1. **Read the README**: Check out usage examples and workflows
2. **Try examples**: Run the example workflows
3. **Explore nodes**: Experiment with different settings
4. **Join community**: Contribute to the project

## 🆘 Support

- 📖 **Documentation**: [README.md](README.md)
- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/A043-studios/ComfyUI_HunyuanWorldnode/issues)
- 💡 **Feature Requests**: [GitHub Issues](https://github.com/A043-studios/ComfyUI_HunyuanWorldnode/issues)
- 🤝 **Contributing**: [CONTRIBUTING.md](CONTRIBUTING.md)

---

**Happy 3D generating! 🌍✨**