H3 Auto Refs (folders, by prompt)

If you've ever run a multi-character H3 scene and watched everyone render as the same person, this node is the fix you wanted. H3AutoRefs looks at your script text, figures out which characters are actually in it, and pulls their reference photos from per-character folders automatically - no manual wiring of nine image loaders, no "which ref goes in which slot" bookkeeping.

The mechanism is clean. You keep a refs_root folder with one subfolder per character (input/h3_refs/rae/, input/h3_refs/mark/, …). The node scans the prompt text for folder names as whole words - dialogue is stripped first, so a character who's merely talked about never accidentally matches - then each matched character contributes up to max_per_character images (default 3, and the tooltip's advice to sort for front/three-quarter/profile sets is genuinely good; that set holds identity best). Everything stays under H3's 9-reference-slot cap, and the matching <Picture N> identity lines are generated and prepended to the prompt automatically. That last part is the real time-saver: it's the binding text that tells the model which photo is which subject, and getting it wrong is exactly how refs blend into one averaged face.

The inputs that matter

• prompt_text - the text scanned for character names (the premise, or the writer's output).
• extra_text - a second text to scan. Wire the scene idea here so a writer that renames the character to ID_A still casts the right photos.
• characters - explicit comma list of folders; overrides the prompt scan entirely when set. This is your control when the scan over-matches.
• overrides - folder remaps like rae=rae_night to swap a character's ref set for specific scenes.
• enabled - the master switch (wire USE AUTO REFS here). Off means no scan, no photos, found=false, run continues.
• on_no_match - no_reference (default) warns and renders without photos; error stops the run.

Outputs: ref_1 through ref_9 (the picked photos, one per slot), plus refs_batch (all of them in one batch, so two or three matched characters don't overflow a 3-slot chain), prompt_out (the prompt with identity bindings prepended), report, and found - a boolean you can feed to the writer so it knows whether to say "looks like the person in the photos" or describe them from prose. An earlier version had a subtle trap where the scan stopped at the first three characters it found; that's fixed - it now scans up to nine and splits the reference slots across everyone who matched.

Install

Part of the H3 Multishot pack:

cd ComfyUI/custom_nodes
git clone https://github.com/jlucasmcrell/ComfyUI-H3-Multishot

or ComfyUI-Manager → H3 Multishot. Restart, ComfyUI v0.30.0+, no extra dependencies. Models go in the usual spots: the checkpoint in models/diffusion_models/, encoder and VAEs in text_encoders/ and vae/.

The honest caveat is the same one the whole ref system carries: fewer characters per run holds faces more firmly. Five named characters all get a photo, but a two-character scene will hold better. If identity is the whole job, keep the cast small and give everyone three good angles.