MushroomFleet-ComfyUI-Variationator/docs/NODE_REFERENCE.md

Node Reference Guide - Technical Specifications

Complete technical reference for all Prompt Orchestration nodes in ComfyUI.

---

Node Specifications

1. PromptLightingModifier

Class: PromptLightingModifierNode
Display Name: "Lighting Modifier (Single)"
Category: "Prompt Orchestration"

Input Specification

INPUT_TYPES = {
    "required": {
        "text": ("STRING", {
            "multiline": True,
            "default": "Subject description here"
        }),
        "modifier_id": ("INT", {
            "default": 7,
            "min": 1,
            "max": 20,
            "step": 1
        }),
        "preserve_base": ("BOOLEAN", {
            "default": True
        })
    }
}

Output Specification

• RETURN_TYPES: ("STRING",)
• RETURN_NAMES: ("modified_prompt",)
• OUTPUT_IS_LIST: False

Function

• FUNCTION: "apply_modifier"
• Description: Applies single lighting modifier from ID 1-20

Parameters

• text (STRING): Base prompt to modify
• modifier_id (INT 1-20): Which lighting modifier to apply
• preserve_base (BOOLEAN):
  • True: Append modifier to text (recommended)
  • False: Replace lighting info in text

Usage Example

Input:
  text = "Sports car on highway"
  modifier_id = 7
  preserve_base = True

Output:
  "Sports car on highway, golden hour, warm low-angle side-light, clear sky"

---

2. PromptBatchVariation

Class: PromptBatchVariationNode
Display Name: "Batch Variation Generator"
Category: "Prompt Orchestration"

Input Specification

INPUT_TYPES = {
    "required": {
        "text": ("STRING", {
            "multiline": True,
            "default": "Subject description here"
        }),
        "category": (["all", "dry", "wet", "custom"],)
    },
    "optional": {
        "custom_ids": ("STRING", {
            "default": "1,7,18",
            "multiline": False
        })
    }
}

Output Specification

• RETURN_TYPES: 10x ("STRING",)
• RETURN_NAMES: ("var_1", "var_2", ..., "var_10")
• OUTPUT_IS_LIST: (True, True, ..., True) - 10 times

Function

• FUNCTION: "generate_variations"
• Description: Generates up to 10 prompt variations

Parameters

• text (STRING): Base prompt
• category (ENUM): "all" (1-20), "dry" (1-16), "wet" (17-20), "custom"
• custom_ids (STRING): Comma-separated IDs when category="custom"

Category Mapping

• "all": Modifiers 1-20 (all modifiers)
• "dry": Modifiers 1-16 (clear conditions)
• "wet": Modifiers 17-20 (wet conditions)
• "custom": User-specified IDs from custom_ids

Output Behavior

• Returns list outputs (can connect to batch nodes)
• Pads to 10 outputs if fewer variations
• Padding uses original text

---

3. PromptStyleTransform

Class: PromptStyleTransformNode
Display Name: "Style Transform"
Category: "Prompt Orchestration"

Input Specification

INPUT_TYPES = {
    "required": {
        "text": ("STRING", multiline=True),
        "style": ([
            "custom", "pop_art_1960s", "bauhaus", "art_deco",
            "cyberpunk", "minimalist", "impressionist", "noir",
            "futuristic", "vintage", "brutalist"
        ],),
        "maintain_composition": ("BOOLEAN", default=True)
    },
    "optional": {
        "custom_style": ("STRING", default="")
    }
}

Output Specification

• RETURN_TYPES: ("STRING",)
• RETURN_NAMES: ("styled_prompt",)

Function

• FUNCTION: "apply_style"

Parameters

• text: Base prompt
• style: Pre-defined style or "custom"
• maintain_composition:
  • True: Explicitly states to maintain composition
  • False: Appends style without composition note
• custom_style: Used when style="custom"

Built-in Styles

1. pop_art_1960s: "1960s pop art style with bright colors, bold graphics, and commercial aesthetics"
2. bauhaus: "Bauhaus style with geometric forms, primary colors, and modernist principles"
3. art_deco: "Art Deco style with geometric patterns, luxurious details, and streamlined forms"
4. cyberpunk: "cyberpunk aesthetic with neon lights, high-tech elements, and dystopian atmosphere"
5. minimalist: "minimalist style with clean lines, negative space, and essential elements only"
6. impressionist: "impressionist painting style with visible brushstrokes and emphasis on light"
7. noir: "film noir style with dramatic shadows, high contrast, and moody atmosphere"
8. futuristic: "futuristic design with sleek forms, advanced materials, and sci-fi elements"
9. vintage: "vintage aesthetic with retro colors, grain, and nostalgic atmosphere"
10. brutalist: "brutalist architecture style with raw concrete, geometric forms, and bold structure"

---

4. PromptSmartVariation

Class: PromptSmartVariationNode
Display Name: "Smart Variation (NLP)"
Category: "Prompt Orchestration"

Input Specification

INPUT_TYPES = {
    "required": {
        "text": ("STRING", multiline=True),
        "intent": ("STRING", {
            "multiline": False,
            "default": "make it golden hour"
        })
    }
}

Output Specification

• RETURN_TYPES: ("STRING",)
• RETURN_NAMES: ("smart_prompt",)

Function

• FUNCTION: "smart_vary"

Intent Recognition

System recognizes keywords in intent string:

Time-based intents:

• "morning" → modifiers 1, 2, 3
• "afternoon" → modifiers 5, 6, 14
• "golden hour" → modifier 7
• "sunset" → modifier 8
• "night" → modifiers 11, 12
• "blue hour" → modifiers 10, 17, 18
• "wet" → modifiers 17, 18, 19, 20

Style-based intents:

• Detects style keywords → applies style transformation
• Falls back to custom style if no match

---

5. PromptPresetCollection

Class: PromptPresetCollectionNode
Display Name: "Preset Collection"
Category: "Prompt Orchestration"

Input Specification

INPUT_TYPES = {
    "required": {
        "text": ("STRING", multiline=True),
        "preset": ([
            "key_moments", "commercial", "artistic",
            "full_day_cycle", "wet_night"
        ],)
    }
}

Output Specification

• RETURN_TYPES: 8x ("STRING",)
• RETURN_NAMES: ("var_1", ..., "var_8")
• OUTPUT_IS_LIST: (True, ..., True) - 8 times

Function

• FUNCTION: "apply_preset"

Preset Definitions

"key_moments":

• Modifier IDs: [1, 7, 8, 10, 18, 20]
• Count: 6 variations
• Use: Dramatic lighting variety

"commercial":

• Modifier IDs: [3, 4, 7, 11]
• Count: 4 variations
• Use: Product photography

"artistic":

• Modifier IDs: [7, 8, 9, 10]
• Styles: ["impressionist", "minimalist", "art_deco"]
• Count: 7 variations (4 lighting + 3 styles)
• Use: Creative projects

"full_day_cycle":

• Modifier IDs: 1-16 (all DRY)
• Count: 16 variations
• Use: Time-lapse visualization

"wet_night":

• Modifier IDs: 17-20 (all WET)
• Count: 4 variations
• Use: Dramatic urban/night scenes

---

6. PromptModifierInfo

Class: PromptModifierInfoNode
Display Name: "Modifier Info"
Category: "Prompt Orchestration"

Input Specification

INPUT_TYPES = {
    "required": {
        "modifier_id": ("INT", {
            "default": 7,
            "min": 1,
            "max": 20
        })
    }
}

Output Specification

• RETURN_TYPES: ("STRING", "STRING", "STRING")
• RETURN_NAMES: ("description", "category", "tags")

Function

• FUNCTION: "get_info"

Outputs

• description: Full modifier text (e.g., "golden hour, warm low-angle side-light, clear sky")
• category: "dry" or "wet"
• tags: Comma-separated tags (e.g., "golden-hour, warm, side-light, clear")

---

7. PromptCombiner

Class: PromptCombinerNode
Display Name: "Prompt Combiner"
Category: "Prompt Orchestration"

Input Specification

INPUT_TYPES = {
    "required": {
        "text_1": ("STRING", multiline=True)
    },
    "optional": {
        "text_2": ("STRING", multiline=True),
        "text_3": ("STRING", multiline=True),
        "text_4": ("STRING", multiline=True),
        "separator": ("STRING", {
            "default": ", ",
            "multiline": False
        })
    }
}

Output Specification

• RETURN_TYPES: ("STRING",)
• RETURN_NAMES: ("combined_text",)

Function

• FUNCTION: "combine"

Behavior

• Combines non-empty text inputs
• Joins with separator string
• Ignores empty inputs

---

8. PromptRandomModifier

Class: PromptRandomModifierNode
Display Name: "Random Modifier"
Category: "Prompt Orchestration"

Input Specification

INPUT_TYPES = {
    "required": {
        "text": ("STRING", multiline=True),
        "category": (["all", "dry", "wet"],),
        "seed": ("INT", {
            "default": 0,
            "min": 0,
            "max": 0xffffffffffffffff
        })
    }
}

Output Specification

• RETURN_TYPES: ("STRING", "INT")
• RETURN_NAMES: ("modified_prompt", "used_modifier_id")

Function

• FUNCTION: "apply_random"

Behavior

• Selects random modifier from category using seed
• Returns both modified prompt and which modifier was chosen
• Same seed = same modifier (reproducible)

---

9. PromptMultiStyle

Class: PromptMultiStyleNode
Display Name: "Multi-Style Layer"
Category: "Prompt Orchestration"

Input Specification

INPUT_TYPES = {
    "required": {
        "text": ("STRING", multiline=True),
        "style_1": ([style_list],)
    },
    "optional": {
        "style_2": ([style_list],),
        "style_3": ([style_list],)
    }
}

Output Specification

• RETURN_TYPES: ("STRING",)
• RETURN_NAMES: ("multi_styled_prompt",)

Function

• FUNCTION: "apply_multi_style"

Behavior

• Applies up to 3 styles sequentially
• Each style builds on previous
• Set to "none" to skip a style slot

---

Data Types

STRING

• Multiline text input/output
• Used for prompts and descriptions
• Can be connected to CLIP Text Encode

INT

• Integer values
• Used for modifier IDs (1-20) and seeds
• Can be connected to math/logic nodes

BOOLEAN

• True/False toggle
• Used for behavior switches
• Displayed as checkbox in UI

ENUM (Dropdown)

• Fixed list of options
• Used for categories, styles, presets
• Displayed as dropdown menu

---

Connection Patterns

String → String

Most common: Text flows through nodes

[Text Input] → [Node] → [CLIP Text Encode]

String → Multiple Strings (Batch)

List outputs from batch nodes

[Text] → [Batch Node] → [var_1] → [CLIP 1]
                      → [var_2] → [CLIP 2]
                      → [var_3] → [CLIP 3]

Multiple → Single (Combiner)

[Text 1] ─┐
[Text 2] ─┤→ [Combiner] → [Output]
[Text 3] ─┘

Info Display

[Modifier ID] → [Info Node] → [description] → [Show Text]
                            → [category] → [Display]
                            → [tags] → [Display]

---

Node Compatibility

Compatible Input Nodes

• Primitive (String)
• Text Input
• Load Text
• Any node outputting STRING type

Compatible Output Nodes

• CLIP Text Encode
• Save Text
• Show Text
• Any node accepting STRING input

Batch Processing Compatible

• Batch Variation Generator
• Preset Collection
• Any node with OUTPUT_IS_LIST=True

---

Performance Characteristics

Execution Speed

• All nodes: <10ms typically
• No network calls
• In-memory processing only

Memory Usage

• Minimal: ~1-2MB per node
• Scales linearly with text length
• No persistent state between executions

Caching

• Nodes don't cache results
• Re-execute on each workflow run
• ComfyUI handles workflow-level caching

---

Error Handling

Invalid Modifier ID

• Returns error message in output
• Does not break workflow
• Check console for details

Empty Inputs

• Returns original/default text
• Continues execution
• No workflow interruption

Invalid Custom IDs

• Skips invalid IDs
• Uses valid ones only
• Falls back to default if all invalid

---

Thread Safety

• All nodes are thread-safe
• Can run in parallel workflows
• No shared state between instances

---

Version Compatibility

• ComfyUI: Latest version recommended
• Python: 3.7+ required
• Backward Compatible: Yes (JSON workflows)
• Forward Compatible: Should be (minimal dependencies)

---

Extension Points

Custom Modifiers

Add to prompt_orchestrator.py:

custom = LightingModifier(
    id=21,
    description="your modifier",
    category=ModifierCategory.DRY,
    tags=["tag1", "tag2"]
)
orchestrator.modifiers[21] = custom

Custom Styles

Add to style templates:

orchestrator.custom_style_templates["my_style"] = "description"

---

Debugging

Enable Console Logging

Check ComfyUI console for:

• Node initialization messages
• Error messages
• Input/output values (if debugging enabled)

Test Nodes Individually

1. Create minimal workflow
2. Add single node
3. Connect Show Text to output
4. Verify results

Validate Inputs

Use Modifier Info node to check modifier descriptions before using.

---

API Reference

All nodes implement ComfyUI's standard node interface:

class CustomNode:
    @classmethod
    def INPUT_TYPES(cls):
        # Define inputs
        
    RETURN_TYPES = ()
    RETURN_NAMES = ()
    FUNCTION = "method_name"
    CATEGORY = "category"
    
    def method_name(self, **kwargs):
        # Implementation
        return outputs

---

License

MIT License - Same as core system

---

Last Updated: v1.0.0
For: ComfyUI Custom Nodes
Compatibility: ComfyUI Latest