MiniMax H3 Visual Reference Role (Legacy)

A single reference image often does more than one job. The same photo of a woman in a red coat can define her identity and serve as the exact first frame and anchor a keyframe at Shot 3. Most tools make you pick one. This node - part of ComfyUI-MiniMax-H3-Guide's legacy reference chain - lets you chain role bindings on one asset so H3's prompt carries each independently constrained piece of evidence.

It's the fine-grained cousin of the single role dropdown on a Visual Reference node. Where that dropdown picks one job, this one builds a role_bindings chain that a Visual Reference or a Reference Sheet Visual Reference can consume wholesale.

What you set

• reference_role - the exact job. Fourteen choices, and the routing split is the thing to internalize: endpoint roles (exact first/last frame) route to Image to Video; reusable/direct roles (identity, scene, style, motion, edit source, camera/cuts) route to Ref2VA. The "Unassigned" default deliberately stops execution rather than inventing a Subject or endpoint.
• retention - how strongly H3 keeps it: fully_preserved, partially_preserved, attribute_transfer, weak_reference, or Auto (which is conservative: exact endpoints and motion get fully_preserved; style and storyboard get weak_reference).
• content_group - the reusable-content key. Give related roles on different assets the same value when they jointly define one <Subject N>. Merged bindings must share one retention marker, because H3 allows one retention row per Subject.
• transfer_target - only for attribute_transfer: name the different content group that receives this source attribute. The final context must contain a visible, non-transfer binding with that destination group, or the transfer has nowhere to land.
• shot_scope - optional. 3 for one shot, 3,4 for selected shots, 3-4 for a range, all for everywhere. Empty means wherever relevant.
• notes - binding-specific instructions about what to preserve, transfer, ignore, or change.

previous_roles chains from the preceding role node; leave it disconnected for the first role on this media.

Outputs

role_bindings connects to another Role node's previous_roles input, and the final chain plugs into a Visual Reference node's role_bindings input - or a Reference Sheet Visual Reference's. The role chain belongs to one media asset; the Visual Reference node is what adds it to the ordered context the Guide and Enhancer read. role_preview is a readable dump of every role, retention relation, group, scope, and note - wire it to a text viewer and confirm the chain before it reaches the Guide.

Installing

cd ComfyUI/custom_nodes
git clone https://github.com/ethanfel/ComfyUI-MiniMax-H3-Guide

Restart ComfyUI; it lands under MiniMax H3/Prompting. No Python dependencies - you just need a ComfyUI build with native MiniMax H3 support.

Where people get burned

The transfer trap is the most common: picking attribute_transfer, naming a target, but never actually creating the destination binding, so the final context is missing its receiving end and the role silently fails validation. The other classic is merging two roles into one content_group with different retention markers - they must agree or the compiler flags a conflict. And remember the routing split: an image can't be both an exact endpoint frame and a storyboard frame. If it's the first frame, it goes to Image to Video; the storyboard reading belongs on a different role or it'll try to ride two routes at once.