ComfyUI-MoonNodes Introduction
ComfyUI-MoonNodes is a collection of nodes for building more flexible image-making workflows in ComfyUI. Its main focus is regional prompting: giving different parts of an image their own prompts. It also includes tools for drawing masks, experimenting with multi-pass sampling, generating prompt variations, and adding text or Gemini-powered interactions to a workflow.
For example, you could describe the overall mood of a scene in one prompt, then give the foreground character and the background separate descriptions. MoonNodes helps you define where those descriptions apply and connect them to the image-generation process. This can be useful when a single prompt causes details from different parts of a composition to mix together.
The author notes that the repository was developed collaboratively with AI. The regional attention approach builds on MultiMaskCouple and ComfyCouple; the greedy text-encoding option was inspired by Omost through ComfyUI_omost.
How ComfyUI-MoonNodes Works
Think of a regional workflow as placing transparent guides over a canvas. A mask identifies an area, while a regional prompt describes what you want in that area. MoonNodes provides nodes for creating those masks, preparing the prompts, and applying them while the image is generated.
A typical workflow has three parts:
- Describe the image. Write an overall prompt and separate regional prompts. With Moon Indexed Encoder, the
BREAKkeyword divides them into numbered sections. - Define the areas. Create numbered regions with Moon Mask Maker Simple, or draw layers in Moon Mask Maker GUI. Keep the region order aligned with the corresponding prompts.
- Generate the image. Moon Regional Sampler uses the masks and encoded prompts with the model. The experimental Moon Multi-Pass Sampler offers another approach: it works on individual regions and the whole image in alternating steps.
A mask is a guide, not a guarantee that every edge or detail will land exactly where you drew it. The prompts, masks, model, and sampling choices all contribute to the result.
ComfyUI-MoonNodes Features
Regional prompts and sampling
Moon Indexed Encoder lets you write several prompts in one text box. Put the general prompt first, then separate the regional prompts with BREAK:
general prompt goes here
BREAK
prompt for area 0 goes here
BREAK
prompt for area 1 goes here
The order matters: the prompt for area 0 should correspond to mask region 0, and so on. Its greedy toggle packs comma-separated prompt fragments into CLIP’s 77-token blocks more efficiently, helping avoid unnecessary truncation when prompts are long.
Moon Regional Sampler connects the regional masks and encoded prompts to the model. Its mode setting changes how regional instructions are combined:
Concatappends regional prompts to the base prompt.Mergeblends the regional attention maps.
The head_start_percent setting limits self-attention during the early part of generation. This can help reduce visual features bleeding from one region into another while the initial layout takes shape. Try changing it when the composition is correct in broad strokes but subjects or attributes keep mixing across regions.
Anima Regional Patcher provides regional prompting support for Anima models, using a workflow similar to SDXL regional prompting. Anima Regional Patcher Advanced extends it for more involved regional workflows. The repository’s workflows directory contains examples. The patchers were inspired by Comfyui-Anima-Regional-Conditioning.
Moon Multi-Pass Sampler is an experimental alternative to a standard KSampler. During isolated steps, it denoises each masked region and the background separately, then combines them in the latent image. During global steps, it works on the full canvas with regional attention to help the parts fit together. local_pass_percent controls how much of the generation uses this alternating process. During isolated passes, the sampler also offsets the seed by the current step so it does not repeatedly introduce the same noise. Its output can go directly to VAE Decode; it does not require a downstream KSampler.
Moon Multi-Pass Sampler workflow
Mask creation
Moon Mask Maker Simple creates masks from a text grid of region numbers. It is suited to compositions you can describe as a straightforward grid, such as distinct left and right areas.
Moon Mask Maker Simple workflow
Moon Mask Maker GUI provides a drawing editor inside the node for layouts that are easier to sketch than describe with numbers. You can:
- Open Edit Masks from the node or its context menu.
- Add a reference image as an underlay without changing the image itself. Adjust its opacity and choose
contain,cover, orstretchto control how it fits the canvas. - Use the reference image’s native aspect ratio, or set the canvas width and height independently.
- Draw on multiple layers. Other layers remain visible semi-transparently while you edit.
- Use Subtract to remove an upper layer’s occupied area from layers beneath it without erasing the original editable strokes.
- See a multicolored mask preview on the node.
The node outputs an indexed MASK list, a colored IMAGE preview, and the canvas width and height. Connect those dimension outputs to the latent-size node in your workflow so the generated image follows the mask editor’s canvas size. You can choose a black or white composite background; white may be useful for Regional ControlNet conditioning.
In the editor, left-click and drag to draw, and right-click and drag to erase. Use the Up and Down arrow keys to switch layers. Pressing Down on the last layer creates a new one.
Gemini and text workflow tools
Gemini Persistent Chat connects a workflow to the Google Gemini API. Conversation history is associated with the current seed, and the node can receive images directly from the workflow. Available Gemini models are read from a local models.txt file.
Clearable Text Input clears its contents after execution. It is useful for a chat message that you do not want to remove manually before the next run.
LLM Submit Input provides a multiline prompt box with a Submit Prompt action that sends the text downstream and queues the workflow. Auto-Clear is enabled by default and clears the input after a successful execution. For selective execution, connect its trigger output to enable_ai_processing: a normal queue run from ComfyUI’s main sidebar can then run the workflow without submitting the text to the LLM.
Markdown Output displays formatted text, including responses generated by Gemini.
Other workflow conveniences
Moon Simple Wildcards adds seed-deterministic variation to prompts. Write [wildcard] or __wildcard__ where a choice should be inserted. It supports nested wildcards and custom .txt files in the wildcards/ directory, including subdirectories such as [folder/name]. This is useful when you want prompt variations that remain repeatable for a given seed.
Quickstart generates a random integer seed and queues the workflow when clicked. Quickstart Advanced adds choices for image resolution and aspect ratio.
🌗 Moon Text Concat combines text from up to 10 inputs, helping you assemble a prompt from separate pieces. A multi-input toggle switch is also included for switching among inputs in a workflow.
ComfyUI-MoonNodes Models
MoonNodes is a collection of workflow nodes, not a set of bundled image-generation models. The models mentioned in the documentation have different roles:
- Anima models: Use the Anima Regional Patcher or its Advanced version when building an Anima regional-prompting workflow.
- SDXL: Mentioned as the comparable regional-prompting workflow for the Anima patcher; the provided documentation does not specify particular SDXL model files.
- Gemini models: Used through Gemini Persistent Chat for chat and image-aware interactions. The choices available to that node come from its local
models.txtfile, so the documentation does not identify a fixed list of Gemini models.
The provided documentation does not compare individual model outputs or performance. For image composition, the documented controls are the regional prompts, masks, and sampler settings described above.
What’s New with ComfyUI-MoonNodes
The supplied documentation marks two additions as new, but does not provide version numbers or a dated changelog:
- 🌗 Moon Text Concat: Combines up to 10 text inputs, making it easier to build a prompt from reusable parts.
- Multi-input toggle switch: Adds a way to switch among multiple inputs in a workflow.
Other features described here should not be assumed to have arrived in a particular version.
Troubleshooting ComfyUI-MoonNodes
Regional details appear in the wrong areas
- Check the order of prompts after each
BREAKin Moon Indexed Encoder. - Compare that order with the numbered mask regions. Area
0should match the prompt intended for area0. - Preview the masks before generating again, especially if you have changed layers or the layout.
Features from different regions mix together
- Check whether the masks cover the intended areas.
- Try the Moon Regional Sampler’s
head_start_percentsetting, which is intended to limit early self-attention and reduce bleeding during layout. - Compare
ConcatandMergeto see which combination better suits your composition.
The mask and generated image have different proportions
- Check the canvas width and height in Moon Mask Maker GUI.
- Connect its
widthandheightoutputs to the latent-size node used by the workflow. - If you are drawing over a reference image, use Use Reference Size when you want the canvas to follow that image’s native aspect ratio. The
contain,cover, andstretchoptions change how the reference appears in the editor, so check the underlay before drawing.
A Gemini message is submitted when you only meant to run the workflow
Connect LLM Submit Input’s trigger output to enable_ai_processing. Use Submit Prompt when you intend to send the text to the LLM; a normal run from ComfyUI’s main sidebar can execute without submitting it.
Frequently asked questions
Do I need a separate KSampler after Moon Multi-Pass Sampler?
No. The documented workflow sends its output directly to VAE Decode.
Will erasing an area with Subtract permanently remove my strokes on lower layers?
No. Subtract removes an upper layer’s occupied area from the layers beneath it without changing the original editable strokes.
Can I reuse the same wildcard result?
Moon Simple Wildcards is seed-deterministic, so its choices are tied to the seed.
Why are some words missing from a long regional prompt?
CLIP uses 77-token blocks. Try the Moon Indexed Encoder’s greedy toggle, which is designed to pack comma-separated prompt fragments into those blocks more efficiently.
Learn More about ComfyUI-MoonNodes
- Explore the repository’s
workflowsdirectory for examples, particularly the Anima regional-prompting workflow. - See MultiMaskCouple and ComfyCouple for the projects behind MoonNodes’ regional attention approach.
- See Omost and ComfyUI_omost for the inspiration behind greedy text encoding.
- See Comfyui-Anima-Regional-Conditioning for the project that inspired the Anima regional patcher.
