KIE • Load Character Variant

What it is

KIE • Load Character Variant pulls back one saved look - a day outfit, a costume, a scarring make-up pass - that's attached to a Character Pack. It returns the approved image, a prompt that splices that look onto the pack's identity anchors, and a CHARACTER_VARIANT handle.

The design idea worth stealing: identity and wardrobe are separate objects. The pack is the face and the continuity rules, and it's immutable. The variant is a child record that points at a specific pack version. You can add twelve outfits without ever touching the identity, and you can never accidentally overwrite it.

How it works

Variants live in the pack's user-data area under character_variants/<pack_id>/<slug(variant_name)>__v<slug(version)>/. The node resolves that folder from variant_name and version - which are plain text widgets, not dropdowns, so exact strings matter.

Then it checks, in order: the manifest names the same parent_pack_id; the recorded parent_content_sha256 still matches the pack you loaded; the name and version fields match what you typed; the approved.png exists inside its own folder; and its hash matches what was recorded at save time.

Any mismatch is a refusal, not a warning. That's deliberate - the failure mode it's preventing is a workflow that silently renders the wrong look, or the same look against a re-saved pack whose identity notes changed underneath it.

The prompt it builds is the interesting output. It concatenates the parent's identity description, its visual style, its continuity rules, then "Approved look {name} v{version}: {appearance}", then "Scene allowance: …" if the variant has one. So a single wire carries "this person, this face, this wardrobe, and here's how far you're allowed to push the scene."

Inputs and outputs

• character_pack - required. Comes from KIE • Load Character Pack.
• variant_name and version - required, defaulting to Day look and 1. These are the lookup keys.
• Outputs: approved_image (IMAGE), variant_prompt (STRING), character_variant (handle, for anything downstream that wants the record).

Wire approved_image into a model that documents image-reference support - an edit model, or a reference-image generation mode. Wire variant_prompt into the prompt. That pairing is the whole consistency play: the model sees the face and reads the anchors.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/felipederosilva/ComfyUI-KIE-Nodes-Next
python -m pip install -r ComfyUI-KIE-Nodes-Next/requirements.txt

Variants are stored in ComfyUI's user data folder, outside the extension install, so updating the pack doesn't wipe your library. Nothing here calls KIE and nothing costs credits.

Where people get burned

• No dropdown, no hints. variant_name is a free-text field. Day look and day look and Day Look are different keys. Copy the name from the Save node's widget rather than retyping it.
• "Character variant does not match the selected identity and version." You typed a name/version that doesn't exist under that pack, or the pack you loaded isn't the parent. Worth knowing: this error is also what you get when the folder doesn't exist, since the parse fails first.
• "Character Pack identity changed since this workflow was built." The pack was re-saved between building the graph and running it. Re-add the Load Character Pack node.
• Re-saving is safe, changing isn't. Saving identical content again is a no-op; a different image with the same name and version is refused. Bump the version instead - that's the whole immutability bargain.
• Not a universal identity lock. The README says it plainly: a reference image plus a prompt is not a guarantee. How well the face holds depends on the model you send it to.