Wildcard Cluster:
WildcardCluster builds varied image prompts by replacing keywords in a template with lines selected from wildcard text files. You can use it to combine choices such as a character’s appearance, clothing, and setting while keeping the rest of your prompt consistent. Each configured keyword draws from its own file, and you can choose between repeatable random selections and selections that advance through a file in order. The node replaces every occurrence of a configured keyword in the template, making it useful for generating prompt variations without rewriting the prompt by hand.
Wildcard Cluster Input Parameters:
prompt_template
The required prompt text in which you place keywords to be replaced. Its default is A _gender person with _hair wearing _clo sits on the beach. For example, if _hair is configured and its selected file line is curly hair, that text replaces every occurrence of _hair in the template. Keywords without a usable configured replacement remain unchanged. This is a multiline string field; the source specifies no minimum or maximum length.
wildcards_config
A required string containing a JSON array of wildcard slots. Each slot identifies a keyword, a file containing possible replacement lines, and a mode such as random or sequential; for example, [`{"keyword":"_hair","file":"hair.txt","mode":"random"}`]. The interface stores these slots in this field and indicates that the frontend manages them with add and remove controls. An invalid JSON value, or a valid JSON value that is not an array, results in no slots being processed. A slot with an empty keyword or a file value of none is skipped. The field has a source-defined default named _DEFAULT_CONFIG, but its contents are not included in the provided code; no minimum or maximum length is specified.
base_dir
The required folder location used to find the wildcard text files named in the slot configuration. Its default is an empty string, which uses the node’s own wildcards/ folder. You can enter an absolute folder path, or a relative path resolved from the node’s directory. A file must resolve within the chosen base folder to be eligible for replacement. This is a string field with no specified minimum or maximum length.
prompt_prefix
Optional text placed before the completed template, separated from it by a space. Its default is an empty string, which adds nothing. This is useful when you want to carry text from an earlier node into the final prompt. Leading and trailing whitespace in the prefix is removed before it is added. The source specifies no minimum or maximum length.
seed
An optional integer that controls reproducible selections for slots using random mode. Its default is 0, with a minimum of 0 and a maximum of 4294967295. With the same files, slot positions, and seed, random-mode slots make the same selections; changing the seed can change them. Each slot uses the seed plus its position in the configuration. The seed does not control sequential-mode selections, which advance through their files.
Wildcard Cluster Output Parameters:
prompt
A single string containing the completed prompt. It begins with the template, replaces configured keywords when a usable line is selected from their files, and then adds a nonempty prefix at the beginning if one was supplied. If a slot is skipped or produces no replacement, its keyword remains in the template. The output is prompt text, not an image or a collection of separate choices.
Wildcard Cluster Usage Tips:
- Put one possible replacement on each line of a wildcard text file, and make each slot’s
keywordmatch the spelling in your template exactly. For example, a_hairslot can point tohair.txtwhile your template sayswith _hair. - Leave
base_dirempty when your files are in the node’s defaultwildcards/folder. Set it to the correct folder when your files are elsewhere, and use filenames that resolve inside that folder. - Choose
randomwhen you want a reproducible choice from a file, and adjustseedto explore different combinations. Choosesequentialwhen you want a slot to move through its file line by line and cycle back to the start. - Keep related keywords distinct, such as
_hairand_hair_color. The node applies longer keywords first so the shorter one does not alter the longer keyword before it can be replaced. - Check the completed
promptfor keywords left unchanged. That is a practical sign to check the slot spelling, file selection, folder, and whether the file has usable lines.
Wildcard Cluster Common Errors and Solutions:
Keyword remains unchanged in the prompt
- Explanation: No usable replacement was collected for that keyword. The slot may have an empty keyword, use
noneas its file, point outside the base folder, or produce no line; the keyword may also be spelled differently in the template. - Solution: Match the slot’s keyword exactly to the template text, select a file inside
base_dir, and check that the file contains usable lines.
No keywords are replaced
- Explanation:
wildcards_configmay contain invalid JSON or a JSON value that is not an array. In either case, the node processes no slots and returns the template text, apart from any prefix. - Solution: Check that the configuration is a JSON array of slot objects, for example
[`{"keyword":"_hair","file":"hair.txt","mode":"random"}`]. If you use the frontend’s slot controls, review the slots shown there.
Selected file does not produce a replacement
- Explanation: A slot whose file is
noneis skipped. A file path that does not resolve within the selected base folder is also skipped. If file reading yields no usable lines, the node has nothing to insert. - Solution: Select the intended text file, confirm
base_dirpoints to its folder, and check that the file has lines available for selection. Keep the file path within that folder.
Random choices do not change when rerunning
- Explanation: Random mode uses the supplied seed and each slot’s position to make repeatable selections. Reusing the same setup can therefore produce the same prompt.
- Solution: Change
seedto explore other selections. Usesequentialinstead when you want a slot to advance through its file on successive executions.
Sequential choices differ from the seed setting
- Explanation: Sequential mode follows its saved position in the file and cycles through its lines; it does not use
seed. - Solution: Use
randommode if you need seed-controlled selections, or keepsequentialwhen cycling through the file is your goal.
AttributeError involving get
- Explanation: The slot-processing code calls
slot.get(...). A configuration array containing a value that is not a slot object, such as a plain string, can therefore raise an error. - Solution: Make every entry in the JSON array an object with a
keywordandfile, plus amodewhen you need to specify one.
