ComfyUI Extension: ComfyUI Substance Designer Integration Plugin

Authored by jasonjgardner

Created

Updated

1 stars

A comprehensive ComfyUI plugin that enables seamless integration with Substance 3D Designer workflows through command line automation. This plugin provides custom nodes for cooking .sbs files, rendering .sbsar archives, controlling material parameters, and batch processing Substance materials within ComfyUI workflows.

Custom Nodes (0)

    README

    ComfyUI Substance Designer Integration Plugin

    A comprehensive ComfyUI plugin that enables seamless integration with Substance 3D Designer workflows through command line automation. This plugin provides custom nodes for cooking .sbs files, rendering .sbsar archives, controlling material parameters, and batch processing Substance materials within ComfyUI workflows.

    Features

    Core Functionality

    • Substance Cooker Node: Convert .sbs files to .sbsar archives with configurable optimization levels
    • Substance Renderer Node: Render .sbsar files to texture maps with full parameter control
    • Parameter Controller Node: Dynamically manipulate material parameters and generate variations
    • Batch Processor Node: Process multiple files or generate multiple variations efficiently
    • Info Extractor Node: Extract metadata and parameter information from .sbsar files

    Advanced Capabilities

    • Parallel Processing: Multi-threaded batch operations for improved performance
    • Parameter Randomization: Generate material variations with controlled randomization
    • Intelligent Caching: Avoid redundant operations with smart caching system
    • Comprehensive Error Handling: Robust error management with detailed logging
    • Flexible Configuration: Customizable settings for tools, performance, and behavior

    Prerequisites

    Required Software

    1. ComfyUI: Latest version with custom node support
    2. Substance 3D Automation Toolkit: Required for command line tools
      • Download from Adobe Substance 3D
      • Ensure sbscooker and sbsrender are accessible in your system PATH

    System Requirements

    • Operating System: Windows 10/11, macOS 10.15+, or Linux (Ubuntu 18.04+)
    • Memory: 8GB RAM minimum, 16GB recommended for batch processing
    • Storage: 2GB free space for plugin and cache
    • CPU: Multi-core processor recommended for parallel processing

    Installation

    Method 1: Direct Installation

    1. Clone or download this repository to your ComfyUI custom nodes directory:

      cd /path/to/ComfyUI/custom_nodes/
git clone https://github.com/jasonjgardner/comfyui-substance-designer-integration.git

    2. Install Python dependencies:

      cd comfyui-substance-designer-integration
pip install -r requirements.txt

    3. Restart ComfyUI to load the new nodes

    Method 2: ComfyUI Manager (if available)

    1. Open ComfyUI Manager
    2. Search for "Substance Designer Integration"
    3. Click Install and restart ComfyUI

    Verification

    After installation, you should see the following nodes in the "substance" category:

    • Substance Cooker
    • Substance Renderer
    • Substance Parameter Controller
    • Substance Batch Processor
    • Substance Info Extractor

    Configuration

    Automatic Tool Detection

    The plugin automatically detects Substance 3D Automation Toolkit installations in common locations:

    • Windows: C:\\Program Files\\Adobe\\Adobe Substance 3D Automation Toolkit\\bin
    • macOS: /Applications/Adobe Substance 3D Automation Toolkit/bin
    • Linux: /opt/Adobe/Adobe_Substance_3D_Automation_Toolkit/bin

    Manual Configuration

    If automatic detection fails, you can manually configure tool paths by creating a configuration file:

    {
  "tool_paths": {
    "sbscooker": "/path/to/sbscooker",
    "sbsrender": "/path/to/sbsrender"
  },
  "defaults": {
    "cooking": {
      "optimization_level": 1,
      "timeout": 300
    },
    "rendering": {
      "output_format": "png",
      "bit_depth": "8",
      "memory_budget": 2000
    }
  }
}

    Save this as config.json in your ComfyUI configuration directory under substance_designer/config.json.

    Quick Start Guide

    Basic Workflow: Cook and Render

    1. Add Substance Cooker Node

      • Set sbs_file_path to your .sbs file
      • Set output_directory for .sbsar output
      • Configure optimization level (0-3)

    2. Connect to Substance Renderer Node

      • Connect the sbsar_file_path output from cooker
      • Set texture output directory
      • Choose output format (PNG, TIFF, EXR, etc.)

    3. Execute Workflow

      • The cooker will convert .sbs to .sbsar
      • The renderer will generate texture maps
      • Images are automatically loaded as ComfyUI tensors

    Parameter Variation Workflow

    1. Add Parameter Controller Node

      • Connect to your .sbsar file
      • Enable randomization or set specific parameters
      • Use JSON format for parameter overrides

    2. Connect to Renderer

      • Use the parameter output to control rendering
      • Generate multiple variations with different seeds

    Batch Processing Workflow

    1. Add Batch Processor Node

      • Set input directory containing .sbs files
      • Configure operation mode (cook, render, or both)
      • Set parameter variations for multiple outputs

    2. Monitor Progress

      • Check batch summary for processing status
      • Review error log for any failed operations

    Node Reference

    Substance Cooker

    Converts Substance Designer .sbs files to .sbsar archives.

    Inputs:

    • sbs_file_path (STRING): Path to input .sbs file
    • output_directory (STRING): Directory for output .sbsar file
    • output_name (STRING, optional): Custom output filename
    • optimization_level (INT): Cooking optimization (0-3)
    • enable_icons (BOOLEAN): Include graph icons
    • merge_graphs (BOOLEAN): Merge all graphs into one file
    • verbose (BOOLEAN): Enable detailed logging

    Outputs:

    • sbsar_file_path (STRING): Path to generated .sbsar file
    • cooking_log (STRING): Command output and logs
    • output_directory (STRING): Actual output directory used

    Substance Renderer

    Renders .sbsar files to texture maps with full control over output settings and support for dynamic image inputs.

    Inputs:

    • sbsar_file_path (STRING): Path to input .sbsar file
    • output_directory (STRING): Directory for texture outputs
    • output_format (COMBO): Image format (PNG, TIFF, EXR, JPG, TGA, HDR)
    • bit_depth (COMBO): Bit depth (8, 16, 16f, 32f)
    • output_name (STRING, optional): Custom output name pattern
    • graph_selection (STRING, optional): Specific graph to render
    • output_selection (STRING, optional): Specific outputs to render
    • parameters (STRING): JSON parameter overrides
    • preset_name (STRING, optional): Preset to apply
    • cpu_count (INT): Maximum CPU cores (0 = auto)
    • memory_budget (INT): Memory limit in MB
    • resolution (INT): Output texture resolution (256-4096, default: 1024)
    • return_images (BOOLEAN): Load images as ComfyUI tensors
    • verbose (BOOLEAN): Enable detailed logging
    • input_image_1 (IMAGE, optional): First input image for material parameters
    • input_image_1_param (STRING): Parameter name for input_image_1
    • input_image_2 (IMAGE, optional): Second input image for material parameters
    • input_image_2_param (STRING): Parameter name for input_image_2
    • input_image_3 (IMAGE, optional): Third input image for material parameters
    • input_image_3_param (STRING): Parameter name for input_image_3
    • input_image_4 (IMAGE, optional): Fourth input image for material parameters
    • input_image_4_param (STRING): Parameter name for input_image_4

    Outputs:

    • texture_paths (STRING): JSON list of generated texture paths
    • texture_images (IMAGE): ComfyUI image tensors
    • organized_outputs (STRING): JSON organized by texture type
    • render_log (STRING): Command output and logs
    • output_directory (STRING): Actual output directory used

    Image Input Feature: The Substance Renderer now supports dynamic image inputs from ComfyUI workflows. You can connect generated images, processed textures, or any ComfyUI IMAGE output to the input_image slots and specify the corresponding Substance parameter names. This enables dynamic material creation where AI-generated content can be used as input textures for procedural materials.

    Substance Parameter Controller

    Controls and manipulates Substance material parameters for variation generation.

    Inputs:

    • sbsar_file_path (STRING): Path to input .sbsar file
    • parameter_overrides (STRING): JSON parameter name-value pairs
    • preset_name (STRING, optional): Preset name to apply
    • random_seed (INT): Seed for randomization (-1 for random)
    • randomize_parameters (BOOLEAN): Enable parameter randomization
    • randomization_strength (FLOAT): Randomization intensity (0.0-1.0)
    • extract_info (BOOLEAN): Extract material information

    Outputs:

    • parameter_json (STRING): Final parameter values as JSON
    • applied_parameters (STRING): Complete parameter application info
    • material_info (STRING): Extracted material metadata
    • preset_info (STRING): Applied preset information

    Substance Batch Processor

    Processes multiple Substance files or generates multiple variations efficiently.

    Inputs:

    • input_directory (STRING): Directory containing input files
    • output_base_directory (STRING): Base output directory
    • operation_mode (COMBO): Processing mode (cook_only, render_only, cook_and_render)
    • file_pattern (STRING): File filtering pattern (default: "*.sbs")
    • batch_parameters (STRING): JSON array of parameter sets
    • output_format (COMBO): Output image format
    • bit_depth (COMBO): Output bit depth
    • optimization_level (INT): Cooking optimization level
    • max_workers (INT): Maximum parallel workers
    • organize_by_material (BOOLEAN): Organize outputs by material name
    • verbose (BOOLEAN): Enable detailed logging

    Outputs:

    • processed_files (STRING): JSON list of processing results
    • batch_summary (STRING): Processing statistics and summary
    • error_log (STRING): JSON list of any errors encountered
    • output_structure (STRING): JSON organization of output files

    Substance Info Extractor

    Extracts comprehensive metadata and parameter information from .sbsar files.

    Inputs:

    • sbsar_file_path (STRING): Path to input .sbsar file
    • extract_parameters (BOOLEAN): Extract parameter information
    • extract_outputs (BOOLEAN): Extract output information
    • extract_graphs (BOOLEAN): Extract graph information
    • format_output (BOOLEAN): Format JSON for readability
    • verbose (BOOLEAN): Enable detailed logging

    Outputs:

    • file_info (STRING): Basic file information as JSON
    • graph_info (STRING): Graph metadata as JSON
    • parameter_info (STRING): Parameter definitions as JSON
    • output_info (STRING): Output channel information as JSON
    • formatted_summary (STRING): Human-readable summary

    Advanced Usage

    Parameter Control

    Parameters can be controlled using JSON format in the Parameter Controller or Renderer nodes:

    {
  "basecolor_r": 0.8,
  "basecolor_g": 0.6,
  "basecolor_b": 0.4,
  "roughness": 0.7,
  "metallic": 0.0,
  "tiling": 2.0,
  "random_seed": 42
}

    Batch Parameter Variations

    For batch processing with multiple parameter sets:

    [
  {
    "roughness": 0.2,
    "metallic": 0.9,
    "random_seed": 1
  },
  {
    "roughness": 0.8,
    "metallic": 0.1,
    "random_seed": 2
  },
  {
    "roughness": 0.5,
    "metallic": 0.5,
    "random_seed": 3
  }
]

    Output Organization

    The renderer automatically organizes outputs by texture type:

    • diffuse: Albedo/base color maps
    • normal: Normal maps
    • roughness: Roughness maps
    • metallic: Metallic maps
    • height: Height/displacement maps
    • ambient_occlusion: AO maps
    • emission: Emissive maps
    • opacity: Alpha/transparency maps

    Performance Optimization

    Memory Management

    • Set appropriate memory_budget values based on your system
    • Use lower bit depths (8-bit) for faster processing when high precision isn't needed
    • Enable caching to avoid reprocessing unchanged files

    Parallel Processing

    • Adjust max_workers in batch processing based on your CPU cores
    • Consider I/O limitations when setting high worker counts
    • Monitor system resources during large batch operations

    Optimization Levels

    • Level 0: Fastest cooking, larger file sizes
    • Level 1: Balanced performance and size (recommended)
    • Level 2: Better compression, slower cooking
    • Level 3: Maximum compression, slowest cooking

    Troubleshooting

    Common Issues

    "Tool not found" errors:

    • Verify Substance 3D Automation Toolkit is installed
    • Check that tools are in your system PATH
    • Manually configure tool paths in config.json

    Memory errors during rendering:

    • Reduce memory_budget setting
    • Lower output resolution or bit depth
    • Process files individually instead of batch

    Slow performance:

    • Reduce max_workers for batch processing
    • Enable caching in configuration
    • Use appropriate optimization levels

    Parameter errors:

    • Verify JSON syntax in parameter inputs
    • Check parameter names match those in the .sbsar file
    • Use Info Extractor to discover available parameters

    Logging and Debugging

    Enable verbose logging in any node to get detailed information about the processing steps. Logs include:

    • Command line arguments used
    • Processing times
    • File paths and sizes
    • Error details and stack traces

    Getting Help

    1. Check the error logs for specific error messages
    2. Verify your Substance files work with the command line tools directly
    3. Test with simple workflows before complex batch operations
    4. Review the configuration settings for any conflicts

    Examples and Workflows

    See the examples/ directory for complete workflow examples:

    • basic_cooking.json: Simple .sbs to .sbsar conversion
    • material_rendering.json: Complete material rendering workflow
    • parameter_variations.json: Generating material variations
    • batch_processing.json: Processing multiple materials
    • advanced_pipeline.json: Complex multi-step workflow

    Contributing

    Contributions are welcome! Please see the development documentation for:

    • Code style guidelines
    • Testing procedures
    • Submission process

    License

    This project is licensed under the MIT License. See LICENSE file for details.

    Acknowledgments

    • Adobe for the Substance 3D Automation Toolkit
    • ComfyUI community for the excellent framework
    • Contributors and testers who helped improve this plugin

    Version History

    v1.0.0 (Current)

    • Initial release with core functionality
    • Support for cooking, rendering, and parameter control
    • Batch processing capabilities
    • Comprehensive error handling and logging