Hunyuan 3D 2.1 - Model Loader

The first-run experience with any Hunyuan3D ComfyUI pack is the same: "okay, now where do I get the giant checkpoint, and which folder does it go in?" Hunyuan 3D 2.1 - Model Loader is this pack's answer to that question. Drop it in, hit run, and it downloads both model files from HuggingFace for you - no digging through model cards, no hunting for the right path.

It's a zero-input node, which reads as weird until you see what it's for. It has no widgets and no inputs, just two outputs:

• model_path (STRING) - the path to the shape DiT checkpoint on your disk.
• vae (HY3DVAE) - a fully loaded, fp16 shape VAE, ready to hand to Hy3D21VAEDecode.

How it works. The node checks whether hunyuan3D-dit-v2-1-fp16.ckpt exists in ComfyUI/models/diffusion_models and Hunyuan3D-vae-v2-1-fp16.ckpt exists in ComfyUI/models/vae. If a file is missing, it downloads the matching weight from the tencent/Hunyuan3D-2.1 HuggingFace repo (enabling hf_transfer if it's available) and renames it to the local name it expects. Then it builds the ShapeVAE with a hardcoded config - 4096 latents, 64-dim embedding, 81920-point output - loads the state dict, casts to fp16, and hands it to your graph. First run is a ~6.9 GB DiT plus ~655 MB VAE download; after that it's instant.

Where it slots in. This node is the front half of the loader + generator2 combo. The natural chain:

Hy3D21ModelLoader ── model_path ──> Hy3D21MeshGenerator2 ── latents ─┐
        └────────────── vae ────────────────────────────────────────> Hy3D21VAEDecode ──> trimesh

Because the loader downloads and returns the path, the generator never has to re-discover the file, and the VAE stays resident for the decode step.

The gotcha that will cost you 7 GB. The loader looks for the -fp16-suffixed filenames. The README's manual instructions tell you to place hunyuan3d-dit-v2-1.ckpt (no suffix). Download per the README and the loader won't see it - it'll re-download its own copy under the -fp16 name. If you let the loader fetch everything, never touch the manual steps and you're fine. If you already placed models by hand, either rename them to match or skip this node entirely.

Is it even required? No, and that's worth saying. It's a convenience node. If you manage your own checkpoints, Hy3D21MeshGenerator (which lists diffusion_models in a dropdown) plus Hy3D21VAELoader (same for vae) does the whole job without any auto-download. Reach for the Model Loader when you want the graph to be self-bootstrapping - share a workflow, someone double-clicks it, and the weights appear.

Install. ComfyUI Manager (search "Hunyuan3d") or clone into ComfyUI/custom_nodes:

cd ComfyUI/custom_nodes
git clone https://github.com/visualbruno/ComfyUI-Hunyuan3d-2-1
cd ComfyUI-Hunyuan3d-2-1
python -m pip install -r requirements.txt

Target Python 3.12 (3.13 breaks the prebuilt wheels), and remember the textured-3D half of the pack needs the C++ rasterizer/renderer wheels - the loader and mesh generation alone don't. One more thing: if your work lives in the EU, UK, or South Korea, Hunyuan 3D's community license doesn't grant you the weights at all - this loader happily downloads them either way, so check your own legal situation before you let it.