VRGDG LTX 2.5 MSR Reference Loader

VRGDG LTX 2.5 MSR Reference Loader exists to solve a specific compatibility problem: the LTX 2.5 Multi-Reference Guide (MSR) wants its reference images as separate stills, each with its own learned slot embedding - not as one big frame batch. This node loads up to four subject images plus an optional background, resizes each to your target resolution, and hands them out as individual IMAGE outputs (pic1–pic4 and background) ready to feed the MSR node.

If you're coming from the pack's LTX 2.3 reference builder, this is the part that trips people up. The older builder expanded references into a single frame batch because LTX 2.3 conditioned on a sequence. LTX 2.5's MSR assigns slot embeddings to individual inputs, so batching them together would collapse the reference identities into one blob. The loader keeps them separate because the downstream node needs them separate. That's the whole design, and it's a good illustration of how LTX evolved - the ecosystem doc tracks the family from 0.9's "fast but finicky" roots through the 2.x era, and reference handling is exactly the kind of thing that got more sophisticated.

The inputs

• subject_1 through subject_4 - the reference images. At least subject_1 is required; the rest are optional. These are image pickers, so you select from ComfyUI's input folder (or upload).
• background_image - the optional background reference.
• background_mode - what to do about the background: use_uploaded_background, neutral_placeholder_wip (a gray placeholder, useful mid-workflow), or no_background.
• width / height - the target size each reference is resized to. Default 736×1280, a portrait resolution that suits LTX video work. Keep them aligned with what your sampler expects.

The outputs

• pic1, pic2, pic3, pic4 - the four subjects as separate one-image batches.
• background - the background, or None in no_background mode.

Installing it

It's part of the VRGameDevGirl pack: Manager → search vrgamedev, or:

cd ComfyUI/custom_nodes
git clone https://github.com/vrgamegirl19/comfyui-vrgamedevgirl.git

Restart, hard-refresh. The catch: this node produces references for a node that isn't in this pack - you also need ComfyUI-LTX2.5-MSR installed for the Multi-Reference Guide itself. If the MSR node is missing, this loader has nothing to feed.

Common issues

• "subject_1 is required." The node refuses to run with no subject. Pick at least one.
• References look stretched. width/height are applied as a straight resize to a common target - that's what MSR needs. If the result looks off, adjust the target to match your source aspect ratio rather than fighting it.
• Missing background error. In use_uploaded_background mode, a background image is mandatory. Use neutral_placeholder_wip or no_background if you don't have one yet.
• "Slot collapse" / identity mixing. That's the exact failure this node's design prevents - make sure you're wiring the separate pic1…pic4 outputs to the separate MSR inputs and not re-batching them.

It's a small, sharp tool in a bigger pack. If you're doing LTX 2.5 MSR work with consistent subjects, this is the loader that makes your references actual references instead of a guessing game.