Variable Folder (SBTools)

The SBTools variable system is handy for prompt text, but the interesting workflows also change images based on what the variables resolved to. That's Variable Folder's job: it's Variable Prompt's sibling, but instead of a list of text values, it defines a mapping of image folders - and which folder gets used depends on the current variable context.

The use case that makes this click: you're generating character variations with reference images. If the variable resolved to "man," you want body-reference images from body_man; if it resolved to "man + casual wear," you want body_man_casual; if "woman," body_woman. Variable Folder encodes exactly that, so the reference image follows the prompt instead of you swapping folders by hand. It's the image half of the conditional system, and it's what turns a prompt matrix into a full batch pipeline with matching visuals.

How it works

You write a folder_map - a block of condition headers followed by folder paths, one per line, in the same conditional syntax as Variable Prompt:

[man]
C:\images\body_man

[man&&casual wear]
C:\images\body_man_casual --subfolder

[woman]
C:\images\body_woman --pattern=*.png --fill-bg=#FFFFFF

[*]
C:\images\body_common

variable_name (default IMAGE1) tags the variable so the Builder knows which image slot it fills. Connect var_list from your Variable Prompt chain (the same conditions-and-order rules apply), and the output var_list carries the folder mapping onward.

Conditions support the full syntax: AND (&&), OR (||), NOT (!), tag specification, wildcard [*], plus --only and --value in recent versions. Folder-specific options come as flags after the condition or path:

• --random / --sequential - how images are chosen within this context.
• --subfolder - include subfolders in the search.
• --pattern=*.png - file pattern per folder.
• --fill-bg=#FFFFFF / --no-fill-bg - fill transparency or keep RGBA.
• --extension / --no-extension - include the extension in the filename output.

The wiring rule that trips everyone up

Variable Folder must be connected to a Variable Image Loader to do anything. It doesn't load images itself - it defines the folder mapping, and the Loader executes it. When connected, the Loader ignores its own folder_path entirely and uses the Variable Folder mapping; disconnect or bypass the Folder and the Loader's own path takes over again. Get the connection wrong and you'll be staring at a folder_path that's doing nothing, wondering why your conditions don't apply.

One more behavior to know: if a condition matches but no images exist in the folder, that combination outputs an empty 64×64 black image rather than failing. That's a silent-ish failure - check your folder paths before you blame the node.

Installing it

Standard pack install. ComfyUI Manager → search "ComfyUI-SBTools" → Install, or:

cd ComfyUI/custom_nodes
git clone https://github.com/Amatsukast/ComfyUI-SBTools.git
cd ComfyUI-SBTools
pip install -r requirements.txt

Restart ComfyUI. No model downloads.

Troubleshooting

• Nothing changes when variables change - the var_list connection is missing (or the Loader isn't connected downstream). Both must be wired.
• Conditions never match - values are case-sensitive and must exactly match what the previous variable produced.
• Black images appearing - a condition matched a folder with no matching files. Use --pattern to check what's being globbed.
• Folder order matters - put specific conditions first ([man&&casual] before [man]), and use [*] to fall back to the common folder after conditional sections.

It's a "configuration as text" node, so the syntax takes a minute to absorb - but once you've got a conditional folder map working, you've automated the most tedious part of character-variation batch runs.