🌍 HunyuanWorld: Model Loader (Real)

This node doesn't generate anything, and that's the point. HunyuanWorldModelLoader is the engine bay of the pack's "Real" pipeline: it loads the actual Tencent Hunyuan3D models from HuggingFace and hands the loaded machinery to HunyuanWorldImageTo3D through a custom HUNYUAN3D_PIPELINE type. If you've ever loaded a checkpoint for SD, you know the shape of the job - it's just a lot heavier, because you're loading two models at once.

The reason it's worth understanding rather than just dropping in: this is where most installs quietly fail, and where your VRAM budget is decided. Nothing else in the pack produces the HUNYUAN3D_PIPELINE wire type, so the loader isn't optional if you want an actual mesh.

How it works

Under the hood it's a thin, honest wrapper around the official hy3dgen library. It asks ComfyUI's model_management for the active torch device, picks fp16 or fp32 from your precision setting, then calls Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(model_name, ...) for geometry - and, when texture is enabled, Hunyuan3DPaintPipeline.from_pretrained(...) for the paint step. Both get loaded with low_cpu_mem_usage, shoved into a dict along with the device and dtype, and returned as the single pipeline output. First load downloads the weights from HuggingFace, which is why the first run feels like it's hung.

The inputs that matter

• model_name - three official repos: tencent/Hunyuan3D-2 (full quality, ~8GB+ VRAM), tencent/Hunyuan3D-2mini (the balanced ~4GB test bed), and tencent/Hunyuan3D-2mv (multiview-optimized, ~6GB+). Default is the full model, which is the wrong default for most people - start with mini.
• precision - fp16 is the default and roughly halves memory and doubles speed. Only reach for fp32 if you're chasing numerical correctness on a card with room to spare.
• enable_texture - whether the paint pipeline loads alongside the shape pipeline. It doubles the load cost, so if you never want textures, turning this off saves you a download and a pile of VRAM.
• low_vram_mode - on by default, maps to low_cpu_mem_usage. Leave it on unless you understand why you'd turn it off.

Output is a single pipeline wire, and its only consumer is HunyuanWorldImageTo3D.

Installing it

Same story as the rest of the pack, with one step that's easy to miss:

cd ComfyUI/custom_nodes
git clone https://github.com/A043-studios/ComfyUI_HunyuanWorldnode.git
cd ComfyUI_HunyuanWorldnode
python install.py        # or: pip install -r requirements.txt

# The critical part: the actual Hunyuan3D library, which the requirements file omits
git clone https://github.com/tencent/hunyuan3d-2.git
cd hunyuan3d-2
pip install -e .

Then restart ComfyUI. The tell that something's wrong with the above: the pack loads, and your terminal prints a warning that it's running in "compatibility mode." That's just a graceful way of saying hy3dgen isn't installed - every node appears, but this loader raises "Hunyuan3D libraries not available" the moment you run it.

Where people get burned

Two failure modes dominate. First, skipping the pip install -e . step - the pack's own requirements don't include hy3dgen, so a bare pip install -r requirements.txt gives you a pack that looks fine and refuses to work. Second, VRAM: the default full model plus texture pipeline is a lot of weights, and OOM at load time is the classic symptom. Drop to tencent/Hunyuan3D-2mini, keep fp16 and low_vram_mode on, and you'll fit where you wouldn't have thought you could.

One thing to note before you commit to this pack for the long haul: it's a young, single-release project, and its README oversells a couple of the sibling nodes (the "Simplified" and "Hybrid" ones are stubs right now). The loader is one of the two pieces that genuinely work - treat it and the Image-to-3D node as the real product, and you'll be fine.