RS Image Reference (Experimental · Not Recommended)

Most experimental nodes in a Comfy pack come with a cheerful "Experimental!" badge and no further warning. This one puts "Not Recommended" in its own display name, and its docs page opens with "Supported, NOT RECOMMENDED." That's refreshing, honestly - and it's the correct expectation to set before you spend an evening wiring it up.

So what is it? RS Image Reference attaches a reference image to one numbered character in the pack's regional sampler. Character 1 gets this face, character 2 gets that one. It's the reference-image slot in a workflow that otherwise identifies people by prompt and LoRA - and its job is the awkward gap between "I described her" and "that's actually her."

How it works, per model family

The notable design decision: you don't load an IP-Adapter or a Redux patch yourself. The sampler picks a backend based on the model family you connected and applies it under the regional routing:

• Anima - a learned IP-Adapter residual plus a cross-attention helper LoRA; the image is square-padded and encoded through SigLIP2 at a variable grid (384 px lands at 576 tokens).
• SDXL / Illustrious - SDXL IP-Adapter Plus, fixed 224 px CLIP-Vision grid, 16 adapter tokens. The docs flat-out say quality is inconsistent and clothing details go missing while colors oversaturate.
• FLUX.1 - Redux image conditioning with regional attention priors.
• FLUX.2 / FLUX 3, Krea 2, MOSS - native reference latents, with Krea 2 and MOSS additionally needing a separately downloaded edit LoRA.
• SD1.5 - IP-Adapter Plus, same fixed grid.

The routing only works with the sampler's regional layout. moss_native rejects an active reference outright rather than half-applying it.

Inputs

• image (required) - normal ComfyUI IMAGE, so a Load Image node. One reference node per character.
• character_id - 1–10, match the Character Prompt row. The reference inherits that character's point, box or mask; it does not add its own placement controls.
• resolution - 64–1024, step 64, default 384. Longest edge; aspect ratio is preserved and Anima pads the rest. Bigger means more tokens means more VRAM, not automatically better.
• strength - 0–2, default 0.6. Set to 0 and nothing is processed at all - no encoder, no adapter, no download. The tested values are weirdly spread and worth quoting because they're the only concrete numbers available: FLUX.1 at 0.1, SDXL at 0.5, FLUX.2/3 at 1.5, other families around 0.6. They're trial settings, not a scheme.
• enabled - plain on/off.
• Optional building_pipe in, single building_pipe out.

Install

Base pack first:

cd ComfyUI/custom_nodes
git clone https://github.com/raspie10032/ComfyUI_RS_MultiCharacter_Sampler.git

Then the reference extras, with the Python that actually runs ComfyUI (add -s if you installed with the portable build):

python -m pip install -r requirements-reference.txt

That pulls transformers, huggingface-hub, safetensors and einops. Restart. The weights aren't in that file - they download on first sampling with an active reference, and the sampler's progress panel shows the file and percentage.

Common issues

SDXL output got worse, not more like your reference. Documented: SDXL/Illustrious is the weak backend - lost clothing detail, oversaturated colors. Drop strength to 0.5 or below, or don't bother.

You can't reproduce an old render. Metadata stores number, hash, resolution and strength, never the image - reconnect references yourself.

The detailer changed nothing. By design - references are sampler-only. The face pass won't reinforce them.

It looks frozen on the first run. It's downloading an adapter and an encoder at sampling time. If the progress panel is showing filenames, wait.

You wired one onto a text slot. Doesn't work. Only active character slots survive Finalize, and text regions can't carry a reference.

The render is nothing like the photo. This is the honest failure mode of the whole reference-image approach, and it's why the node is labelled Not Recommended. Broad visual cues transfer - palette, hairstyle, vibe - identity does not. The curated docs on character consistency are blunt: IP-Adapter and its relatives never followed the ecosystem past SDXL, mentions have been flat for two years, and asking "how do I keep a character consistent with IP-Adapter" on a 2026 model reads as an anachronism. IP-Adapter also flattens detail the longer you run it at weight.

If you need the same person twice, train or find a character LoRA and use RS Character LoRA - the same pack, same pipe, and it's what the README tells you to prefer. Reach for the reference node when you have no LoRA and just want the vibe of a specific image in a specific region, and treat everything it gives you past that as a bonus.