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

A normal VAE loader takes one file and gives you one VAE. This one takes three decoder files and gives you two VAEs - one for geometry, one for texture - because TRELLIS.2's stack genuinely is shaped that way. If you've been staring at a folder of ss_dec_*, shape_dec_* and tex_dec_* files wondering how they fit into ComfyUI's single-VAE-shaped hole, this node is the answer.

Why there are two

TRELLIS.2's representation is a structured latent - the SLAT idea from the original TRELLIS, refined into the more compact sparse-voxel form in the 2.0 release. Two different things get decoded out of that latent space, and they were never going to share one decoder:

• the shape side, which decodes structure occupancy and then the continuous shape field - that's what becomes your mesh triangles;
• the texture side, which decodes the appearance field - base colour, plus the metallic and roughness channels the bake step reads.

So the node builds shape_vae out of the structure decoder plus the shape decoder, and texture_vae out of the texture decoder alone. Unusual, mildly confusing, and completely correct.

Inputs that matter

• structure_decoder - ss_dec_conv3d_16l8, the sparse-structure decoder from the TRELLIS-image-large lineage.
• shape_decoder - shape_dec_next_dc_f16c32.
• texture_decoder - tex_dec_next_dc_f16c32. Optional: leave it on none and texture_vae comes back empty, which is right when your graph does shape only. Connect it the moment you want materials.

The two outputs are shape_vae and texture_vae, both plain VAE objects. shape_vae goes to core's VAE Decode Structure and the shape-decode stage; texture_vae goes wherever the texturing stage decodes appearance. Everything downstream is core TRELLIS.2 nodes - this loader is only doing the plumbing that core's merged-file assumption skips.

A nice consequence of both being ordinary comfy VAE objects: nothing else in your graph needs to know they aren't image VAEs. You can't accidentally wire one into VAE Decode and get a pretty picture, but the type system holding is why the pack's example workflows look like normal ComfyUI graphs.

The files

Dropdowns scan models/trellis2/ and models/pixal3d/, any depth, and show trellis2/… or pixal3d/… prefixes. Both pipelines use the same decoder files, so one copy under models/trellis2 serves Pixal3D runs too - TRELLIS.2's fp16/ release has shape_dec_next_dc_f16c32 and tex_dec_next_dc_f16c32, while ss_dec_conv3d_16l8_fp16 comes from microsoft/ckpts/ss_dec_conv3d_16l8_fp16 in the upstream TRELLIS release, which is exactly the kind of split packaging that motivates a loader like this.

Safetensors only here. The structure and shape decoders aren't offered in GGUF, so there's no quantisation decision to make on this node - and no weight_dtype widget either.

Install

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

ComfyUI Manager, search "ComfyUI-GGUF-Loader", does the same thing. Restart afterwards. Nothing extra beyond gguf is needed for these two VAEs.

Where it goes wrong

"Is that a valid VAE?" - the node runs throw_exception_if_invalid() on each VAE it builds, so a wrong file fails at load rather than three nodes downstream in a decode stage. If it throws, you've almost certainly pointed shape_decoder at a texture decoder or vice versa; the filenames are close enough that this happens, and mixing them up is the single most likely mistake here.

Empty dropdown = wrong folder. If a stage shows only none, the file isn't under models/trellis2 or models/pixal3d. It doesn't search your whole models tree.

Texture VAE blank, bake empty. Leaving texture_decoder on none is legitimate for a shape-only run and produces a perfectly good untextured mesh. It just won't ever have materials, and later stage nodes have nothing to decode into. That's not a bug report, that's the switch you set.

You'll also want the pack's TRELLIS.2 / Pixal3D Model Loader (per-stage), DINOv3 Loader and Prepare Image alongside this one - the loaders are a set. Start from example_workflows/trellis2_image_to_textured_glb_api.json rather than inventing the wiring; the cascade settings in there (12 steps per stage, guidance 7.5 / rescale 0.7 / shift 5 for structure, 7.5 / 0.5 for shape, 1.0 for texture) are the owner's own sidecar values and a far better starting point than defaults.