TRELLIS.2 / Pixal3D Model Loader (per-stage) ⚡

ComfyUI core can already run TRELLIS.2 - the stage nodes, the conditioning, the VAE decoders are all native now, pure PyTorch, no CUDA extension wheels. What core can't do is load the checkpoints the way the models are actually published. Its own loaders want Comfy-Org's merged single file. This node is the adapter for everyone holding the split release: four separate flow DiTs, dropped into one MODEL that core's stages understand.

Why you'd want the split files at all

The merged file is convenient and enormous. The per-stage release is how the people quantizing and re-hosting TRELLIS.2 ship it - one file per stage, each independently replaceable, and each able to be a GGUF quant. That last part matters: a Q4 or Q8 sparse-structure DiT is how you get a 4B-class 3D model under the VRAM ceiling of a 12GB card. If you've ever run Flux at Q5_K_M, you already know the trade this pack is built around.

It also means you can swap one stage without touching the rest. Better texture DiT lands? Replace texture and re-queue, no re-download of the shape cascade.

What it actually does

You pick four files, and the node merges them into one state dict - key prefixes realigned to ComfyUI core's TRELLIS.2 modules - then hands it to comfy.sd.load_diffusion_model_state_dict. The stage names are the seams:

• sparse_structure - ss_flow_img_dit_1_3B_64, the coarse occupancy pass.
• shape_512 - slat_flow_img2shape_dit_1_3B_512, the first cascade shape pass.
• shape_1024 - slat_flow_img2shape_dit_1_3B_1024, the high-res one.
• texture - slat_flow_imgshape2tex_dit_1_3B_1024. Set to none and you get shape only, no materials.
• weight_dtype - default, bf16 or fp32, and the tooltip is honest about its scope: it only governs safetensors compute dtype. GGUF stays quantized either way.

TRELLIS.2 versus Pixal3D is detected from the weights themselves - Pixal3D carries projection heads TRELLIS.2 doesn't - and if you feed it a mix of the two, it refuses rather than assembling a Frankenstein model. That check is worth trusting; a half-TRELLIS, half-Pixal3D merge would not fail loudly at sampling time, it would just produce nonsense.

Anything GGUF in the selection flips the model onto this pack's GGML ops (the same dequant-on-the-fly path Unet Loader (GGUF) uses) and wraps it in a GGUF-aware patcher. Mixed selections work - a GGUF sparse-structure DiT next to fp16 shape stages is fine.

Files and folders

Dropdowns scan ComfyUI/models/trellis2/ and ComfyUI/models/pixal3d/, any subfolder depth, and show entries as trellis2/… or pixal3d/… so you can tell which tree a file came from. Both are registered for extra_model_paths.yaml under the same keys.

For TRELLIS.2, the fp16 set comes from ChrisColeTech/TRELLIS.2-4B-FP16's fp16/ folder. For Pixal3D, either ChrisColeTech/Pixal3D ckpts/ (safetensors) or ChrisColeTech/Pixal3D-GGUF split/{Sparse,shape,texture,decoder}. Don't bother collecting tex_512 checkpoints - neither pipeline runs them - and the *_enc_* shape encoders aren't used here either.

The one output is model, and it plugs into core's TRELLIS.2 conditioning and shape-stage nodes exactly like a stock diffusion model would - the MODEL wire is the contract, and nothing downstream knows or cares that four files went in.

Install

ComfyUI Manager, search "ComfyUI-GGUF-Loader", or by hand:

cd ComfyUI/custom_nodes
git clone https://github.com/ChrisColeTech/ComfyUI-GGUF-Loader
pip install --upgrade gguf

Restart. The pack's requirements.txt also pulls timm, scikit-image, trimesh, addict, einops and fast-simplification, but those are for the preprocessor and 3D/rigging nodes - this loader itself only needs gguf.

Where people get burned

The one that bites hardest: your ComfyUI has to actually have native TRELLIS.2 support (the node's own error says 0.39+). On an older install, load_diffusion_model_state_dict simply doesn't recognise the merged architecture and you get "ComfyUI did not recognise the merged model" - which reads like a corrupt download and isn't. Update ComfyUI first, then start suspecting files.

Second: an empty dropdown. It shows none when the stage can't be matched to a filename pattern in either folder, and picking it raises "no file chosen for stage". That's normally a folder problem, not a node problem - the files must be under models/trellis2 or models/pixal3d, not buried in a ComfyUI/models/checkpoints/trellis2-stuff you made up yourself.

Third, the quiet one: skipping texture and then wondering why the bake comes out blank in the texturing stage. Shape only means shape only.

For a full walk from image to textured GLB, pair this with the pack's VAE, DINOv3 and Prepare Image loaders and core's stage nodes - the pack ships example_workflows/trellis2_image_to_textured_glb_api.json, which is the sane starting graph rather than something you hand-build from scratch.