Prompt Chain Regional Z-Image (Attention Couple)

Regional prompting techniques don't transfer across architectures - every time the community's base model changes shape, someone has to rebuild the masking mechanism from scratch. Z-Image's S3-DiT attention layout is nothing like SDXL's UNet, so PromptChain's SDXL-era Attention Couple node can't just be pointed at a Z-Image checkpoint and expected to work. This node is the from-scratch rebuild, and it shows: where the SDXL version has two tunable numbers, this one has five.

How it works

Same underlying goal as its SDXL sibling - patch the model so each character's prompt stays inside their own mask instead of bleeding across the whole canvas - but Z-Image's single-stream DiT attention needed real engineering to pull that off cleanly, and the extra knobs are the evidence. Two separate mechanisms are exposed here rather than folded into one weight: how strongly the shared background competes for space inside a figure's silhouette, and how hard each figure's pixels are kept from attending to another figure's pixels. That second one is specifically the fix for identity bleed - two characters swapping hair or outfit partway through sampling - the single most common reason anyone reaches for regional prompting in the first place, on any architecture.

The inputs and outputs that matter

model, clip, and regions (Prompt Chain's 4th output) are required, same as the SDXL node. Of the numeric fields:

• base_weight (default 1.0) - how much the shared background prompt competes inside a figure's own region. At 1.0 the background reads everywhere, for maximum scene cohesion; drop it and each figure's own prompt dominates its silhouette more.
• mask_dilation (default 22px) - grows each region mask so hair, ribbons, and props aren't clipped, same as everywhere else in the pack.
• region_strength (default 1.0, 0–8) - the hardness of the per-character text lock. At 1.0 each figure reads only its own character's prompt, which is what stops outfits swapping between figures; below 1.0 softens the boundary, 0 turns it off entirely.
• figure_isolation (default 4, 0–20) - the real fix for identity bleed. A separate lever from region_strength: it controls how hard each figure's pixels are stopped from attending to the other figure's pixels (one character's hair rendering onto both, for instance), while each figure still attends fully to the shared background so the scene stays coherent. 0 turns it off.
• end_percent (default 0.7, 0.05–1.0) - how far into denoising the regional bias stays active before switching off so late steps can refine freely. Push it higher for stronger separation, including on faces, but the tooltip's own honest caveat is that the coarse 16px grid can jag fine detail if you hold it too long; push it lower for smoother output at the risk of identities blending back together in the final steps.

Optional masks and pose work as they do throughout the pack - per-figure masks (typically the 3D Poser's MASKS) and the matching POSE_JSON for name-based binding after a rename. Outputs are MODEL, positive, negative - into your sampler exactly like the SDXL version.

How to install it

Manager: search ComfyUI-PromptChain. Manual:

cd ComfyUI/custom_nodes
git clone https://github.com/mobcat40/ComfyUI-PromptChain.git

Restart. This node is specifically for a Z-Image checkpoint in your graph - using it on an SDXL model isn't the intended path; that's PromptChain_AttentionCouple.

Common issues & troubleshooting

Two characters are swapping hair or clothing. That's identity bleed specifically, and region_strength alone won't fully fix it - raise figure_isolation instead. It's a separate mechanism (pixel-attention rather than text-attention) built for exactly this symptom.

Fine detail looks jagged in regions. You've likely pushed end_percent too high for the resolution you're rendering at. Bring it back down toward 0.5–0.6 and let the last steps refine without the regional grid constraining them.

Everything reads as one blended scene. Check region_strength isn't sitting near 0, and confirm masks is actually wired - without real per-figure masks, there's nothing for any of the five knobs to act on.

This is Z-Image only. If your checkpoint isn't Z-Image, this node's attention patching won't apply correctly; use the SDXL-family Attention Couple node instead.