Hy3DModelLoader

Hy3DModelLoader is the front door of Kijai's Hunyuan3D wrapper. It loads Tencent's shape model - the thing that hallucinates actual 3D geometry from a flat image - and hands you a ready-to-run pipeline plus a bonus VAE. If you've seen a "turn one image into a 3D mesh" ComfyUI workflow, this is the node sitting at the top left of it.

This is image-to-3D, not text-to-3D. You feed the pipeline a 2D image (from a LoadImage upstream, usually generated however you like), and the shape model reconstructs the unseen sides of the object. The KB's verdict on what comes back is worth holding onto: the surface is genuinely impressive, the topology underneath is triangle soup with machine-made UVs - fine for a 3D print or a static prop, not for something that has to animate.

What it actually loads

Unlike the texture stage (which uses diffusers pipelines), this node loads a single-file checkpoint - hunyuan3d-dit-v2-0.safetensors - from ComfyUI/models/diffusion_models/. Grab the converted weights from Kijai/Hunyuan3D-2_safetensors (the author's own conversion; much friendlier than the original .ckpt), drop it in that folder, and the model dropdown will see it.

The two outputs matter:

• pipeline (HY3DMODEL) - the DiT shape model, wired into Hy3DGenerateMesh or Hy3DGenerateMeshMultiView, which produce the shape latents.
• vae (HY3DVAE) - comes along for free from the same file, and feeds Hy3DVAEDecode, where latents become an actual triangle mesh.

That bundled VAE is the default one. If you're on the 2.1 fast/turbo path you'll use a separate Hy3DVAELoader instead - but for the plain 2.0 flow, this node's vae output is all you need.

The three optional inputs worth knowing

• compile_args - plug the output of Hy3DTorchCompileSettings in here to torch.compile the shape model at load. Speeds up sampling meaningfully on a Linux box with Triton; on Windows it's often more trouble than it's worth (see below).
• attention_mode - sdpa (default) or sageattn. SageAttention is faster, and it's the classic portable-Windows install pain point in the community threads - people get stuck on it for hours. Start with sdpa.
• cublas_ops - toggles optimized cuBLAS linear layers (via aredden/torch-cublas-hgemm) to speed up decoding. Only bother if that package is installed.

Install

The whole pack installs as one clone - ComfyUI Manager (search "Hunyuan3DWrapper") or:

cd ComfyUI/custom_nodes
git clone https://github.com/kijai/ComfyUI-Hunyuan3DWrapper
# restart ComfyUI, then in your python env:
pip install -r ComfyUI-Hunyuan3DWrapper/requirements.txt

The shape model alone is relatively painless. The compiled-dependency misery lives in the texture stage (the rasterizer wheel below), which this node doesn't need for basic mesh generation.

Common issues

• Nothing in the dropdown - you haven't put the .safetensors in ComfyUI/models/diffusion_models/. It's the converted Kijai one, not the .ckpt.
• Out of memory - the shape model wants real VRAM; 16 GB is comfortable, and people do squeeze it onto 8 GB cards with fp16 and offload tricks (Kijai's own GitHub issue covers it), but expect slow going.
• Compile hangs or errors - that's the compile_args path needing Triton; torch.compile is a "nice to have," not a requirement. Leave the compile settings node unplugged and the loader runs uncompiled just fine.