unh1nge-comfyui-character-composer

# ComfyUI Character Composer **Version:** 2.0 • **Release Date:** 2026-05-18 • **License:** Apache-2.0 Structured, JSON-driven character prompt system for ComfyUI. Designed for consistent, controllable character generation with Qwen-style workflows, replacing random prompt chaos with a more deterministic composition layer. <img src="preview/ComfyUI_01625_.png" width="100%" /> ## New / Advanced UI & Prompt generation (v2.0) - Character creation node now prints the final prompt it generates for easier debugging. - Character creation node now accepts up to 3 input images at the same time ## New / Advanced toggles (v1.2) - `preserve_input_position` (BOOLEAN, advanced): If True and a reference image is supplied, injects a short preserve-position hint into the prompt (or replace `{preserve_position}` if present). - `preserve_character_look` (BOOLEAN, advanced): Strictly preserve known look traits from UI selections or prompt inference, and from the reference image if supplied. When active, unknown character look traits are no longer auto-filled so the same person identity remains stable. Only traits with actual values are locked so `fill_auto_traits` can still populate non-look fields like pose, setting, and props. - `outfit_mode` (COMBO): `auto` / `keep` / `random` — keeps or randomizes the `outfit` trait when used with `preserve_character_look` and/or `fill_auto_traits`. --- ## Recommended Stack - Model: `Qwen-Image-Edit-Rapid-AIO` - Workflow: `QWEN AIO CC 3X WORKFLOW.json` - Node: `ComfyUI Character Composer` This setup combines: - Qwen spatial reasoning - structured prompt composition - controllable character generation --- ### Text-to-image Use `QWEN AIO CC 3X WORKFLOW.json` with the image sockets left disconnected or just bypass them for normal prompt-driven generation. <img src="preview/text-to-image.png" width="100%" /> ### 3-image image-to-image Use `QWEN AIO CC 3X WORKFLOW.json` when you want to feed three reference images into the Qwen image-edit encoder. <img src="preview/3-image-to-image.png" width="100%" /> --- ## Why This Node Exists Most character-generation pipelines: - rely on random prompts - produce inconsistent characters - become hard to reproduce - break down when too many pose, style, and scene tags pile up This node provides: - structured trait composition - seed-based deterministic behavior - prompt cleanup and conflict handling - JSON-driven customization without rewriting Python --- ## Current Features - JSON-driven trait libraries via `tags.json` and `tags_NSFW.json` - Selectable tag source file with merged UI dropdowns - Smart prompt assembly with weighted core traits - Wildcard support such as `{hair_color}` or `{interaction}` - Backward compatibility for legacy `{pose_x}` placeholders - Workflow-level smart presets - Composition-aware defaults and conflict handling - Scene sanitization for unstable interaction / pose / camera combinations - Complexity guard that trims low-priority details when prompts get overloaded - Alias matching from JSON, such as `blond -> blonde` - Tag conflict rules from JSON, such as `kokoshnik` vs `ushanka` - Detail budgets and category weights from JSON - A compact output surface: final prompt, negative prompt, and image passthroughs <img src="preview/ComfyUI_01543_.png" width="100%" /> --- ## Main Controls ### Core inputs - `input_prompt` - `seed` - `tag_file` - `extra_modifiers` ### High-level steering - `smart_preset` - `none` - `safe portrait` - `high detail character` - `winter fashion` - `paired cinematic` - `simple anatomy-safe` - `composition_mode` - `auto` - `solo portrait` - `fashion` - `paired` - `close-up` - `full body` - `winter` - `fantasy` - `subject_count` - `auto` (recommended) — node will infer 1/2/3/4/group from prompt/interaction/pose - `1` - `2` - `3` - `4` - `group` - `detail_level` - `minimal` - `balanced` - `rich` - `style_strength` - `subtle` - `balanced` - `strong` ### Utility toggles - `fill_auto_traits` - fills unresolved `auto` fields from the active tag file - `reset_overrides` - pushes trait dropdowns back to `auto` for the current generation - `bypass_generator` - returns the raw `input_prompt` unchanged ### Trait sections The node UI is grouped into: - `CORE CREATIVE` - `CHARACTER LOOK` - `CAMERA & FRAMING` - `STYLE & SCENE` - `OPTIONAL EXTRAS` Notable rename: - `pose_x` is now `interaction` --- ## Example Input: ```text {hair_color} {hair_style} woman in {setting} ``` Possible output: ```text gravure, photorealistic, soft lighting, 8k, (1woman:1.20), model blonde beach waves hair, shot on 35mm film grain, modern portrait, wearing bikini minimal fabric, shot as a three-quarter shot natural perspective, at the tropical beach open horizon ``` --- ## Installation 1. Clone into your `ComfyUI/custom_nodes` directory: ```bash cd ComfyUI/custom_nodes git clone https://github.com/unh1nge/comfyui-character-composer ``` 2. Restart ComfyUI. 3. Add the node: `ComfyUICharacterComposer` Category: `Prompt` For the fastest setup, load `QWEN AIO CC 3X WORKFLOW.json`. It works for text-to-image when the image inputs are disconnected, and for three-reference image editing when `image1`, `image2`, and `image3` are connected. <img src="preview/ComfyUI_01645_.png" width="100%" /> --- ## Usage 1. Start with an optional natural-language base prompt. 2. Pick a `tag_file`. 3. Set a `smart_preset` or `composition_mode` if you want the node to bias defaults for you. 4. Choose `subject_count`, `detail_level`, and `style_strength`. 5. Leave most dropdowns on `auto` unless you need exact overrides. 6. Use `fill_auto_traits` when you want the node to complete unresolved traits. 7. Use `{tags}` inside `input_prompt` if you want explicit wildcard injection. 8. Check the final prompt preview after each run. <img src="preview/ComfyUI_01877_.png" width="100%" /> --- ## JSON Customization The node is intentionally data-driven. Most tuning can now happen in JSON. ### Trait lists The standard visible dropdown values still live in keys such as: - `hair_color` - `outfit` - `interaction` - `setting` - `prop` `interaction` will also load from legacy `pose_x` arrays if needed. ### `_composer_rules` Optional rule block for prompt behavior and scene stability. Examples: - `interaction_scene_families` - `scene_compatible_pose_hints` - `complexity_level_terms` - `extreme_focus_terms` - `extreme_camera_terms` - `accessory_drop_terms` - `setting_drop_terms` - `setting_restricted_scenes` - `camera_downgrade` - `detail_budgets` - `category_weights` - `complexity_thresholds` ### `_tag_aliases` Optional synonym mapping for prompt detection without bloating the UI. Examples: - `blond -> blonde` - `fur hat -> ushanka fur hat` - `snow maiden outfit -> snegurochka costume` ### `_tag_conflicts` Optional conflict map for incompatible selections. Examples: - `kokoshnik headdress` conflicts with `ushanka fur hat` - `cat ears` conflicts with `bunny ears` - `winter boots` conflicts with `high heels` --- ## Prompt Behavior Notes - Core traits are weighted more strongly than decorative traits. - Composition mode can auto-bias camera, focus, scene, and style defaults. - Smart presets can override default `detail_level`, `style_strength`, `subject_count`, and composition intent. - Complex interaction scenes may automatically drop risky focus, props, accessories, or settings. - The complexity guard trims low-priority traits when the prompt becomes too crowded. This is meant to improve stability, not produce perfectly identical prompts for every setup or model. --- ## Outputs - `positive_prompt` - final assembled prompt - `negative_prompt` - built-in negative terms - `image1` - passthrough image input - `image2` - second passthrough image input for multi-reference Qwen image-edit workflows - `image3` - third passthrough image input for multi-reference Qwen image-edit workflows --- ## Included Workflows This repository includes workflow JSON files adapted from the Qwen ecosystem and adjusted for structured prompt composition. - [QWEN AIO CC 3X WORKFLOW.json](QWEN%20AIO%20CC%203X%20WORKFLOW.json) - recommended all-in-one workflow for `Qwen-Image-Edit-Rapid-AIO` and `ComfyUICharacterComposer`. Leave the composer image inputs disconnected for text-to-image, or connect `image1`, `image2`, and `image3` for three-reference image-to-image. If you want text-to-image, leave `image1`, `image2`, and `image3` disconnected or bypass the input images in the Qwen workflow. The included workflows are useful as starting points for: - text-to-image - character-consistent edits --- ## What This Is Not - Not a LoRA trainer - Not a ControlNet pipeline - Not a full workflow engine This is a prompt composition layer. --- ## Acknowledgements Built on top of: Phr00t - Qwen Image Edit ecosystem https://huggingface.co/Phr00t/Qwen-Image-Edit-Rapid-AIO --- ## Keywords ComfyUI, prompt engineering, structured prompts, character generation, Qwen workflow --- ## License Free to use and modify.