TK3R ZImage Fun ControlNet (Custom)

Z-Image got the best-served ControlNet ecosystem of any modern base: Alibaba's Fun union covers canny, depth, pose, MLSD, HED, and scribble, plus a proper inpaint mode. ComfyUI's native ZImageFunControlnet applies it, but with a single strength slider and no timing - full control for the whole sample, or nothing. TK3RZImageFunControlnet is that node with start_percent, stop_percent, and a decay curve bolted on.

The practical payoff is the same as everywhere else in this pack: stop the controlnet at 75–85% through sampling and the model gets a free run at fine detail. Push stop_percent down toward 0.3–0.4 and the controlnet is only setting composition, leaving everything else to the model. On a 6B model that's fast to iterate on, so this is a genuinely useful dial, not ceremony.

How it works

Same machinery as the sibling Qwen node in this pack - the controlnet loads as a MODEL_PATCH, and the node wraps it in a patch that injects the condition at the model's transformer blocks. What makes this one special is that it recognizes Z-Image's actual controlnet class (ZImage_Control) and uses the full Z-Image patch path: it sets both the noise-refiner and double-block patches, and handles the Fun union's inpaint mode with an optional inpaint_image and mask. The control image is encoded through the VAE (via Flux-style latent processing, since that's the latent format Z-Image uses). Each step's injection is scaled by strength times a multiplier derived from where the current sigma sits between start_percent and stop_percent.

The decay menu is the standard five: none (instant cutoff), linear, cosine, exponential (fast initial decay), inverse_exponential (slow initial decay).

Inputs and output

• model - your Z-Image model (Turbo or Base).
• model_patch - the Fun ControlNet weights, loaded as a MODEL_PATCH.
• vae - the Z-Image VAE, used to encode the control image.
• strength - −10 to 10, default 1. Yes, negatives are allowed.
• start_percent / stop_percent - 0–1. stop_percent is where the magic happens.
• decay - the curve.
• image (optional) - the control image for canny/depth/pose/etc.
• inpaint_image (optional) - the image for the union's inpaint mode.
• mask (optional) - defines the inpaint region; the node inverts it internally the way the native node expects.

Output is a single patched MODEL, into the sampler - or into another one of these nodes, because chaining works the same way it does for Qwen.

Installing

Part of the TK3R Extensions pack:

• ComfyUI Manager → search "TK3R Extensions" → Install, then restart.
• Or cd ComfyUI/custom_nodes && git clone https://github.com/TK3R/ComfyUI_TK3R_Ext and restart.

The node needs only rich. The models are on you: Z-Image checkpoint, VAE, and the Fun ControlNet union file from Alibaba PAI. One thing to watch if you're on Z-Image Base specifically - it has known trouble with Sage Attention, and that's a model-level issue that will also break these controlnet workflows; disable Sage Attention and use a per-workflow attention node if you hit it.

Where people get burned

The classic miss: trying to feed the controlnet into model instead of model_patch. Both are required inputs and they look similar on the canvas. Second, the union's published weights are lower than the old SD days - start around 0.7–0.8 rather than the 1.0 default, then set a stop_percent and decide if you even need a decay curve. If the effect is still overwhelming at the end, that's what the decay is for.