ComfyUI Extension: 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.
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
- ComfyUI: Latest version with custom node support
- Substance 3D Automation Toolkit: Required for command line tools
- Download from Adobe Substance 3D
- Ensure
sbscooker
andsbsrender
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
-
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
-
Install Python dependencies:
cd comfyui-substance-designer-integration pip install -r requirements.txt
-
Restart ComfyUI to load the new nodes
Method 2: ComfyUI Manager (if available)
- Open ComfyUI Manager
- Search for "Substance Designer Integration"
- 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
-
Add Substance Cooker Node
- Set
sbs_file_path
to your .sbs file - Set
output_directory
for .sbsar output - Configure optimization level (0-3)
- Set
-
Connect to Substance Renderer Node
- Connect the
sbsar_file_path
output from cooker - Set texture output directory
- Choose output format (PNG, TIFF, EXR, etc.)
- Connect the
-
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
-
Add Parameter Controller Node
- Connect to your .sbsar file
- Enable randomization or set specific parameters
- Use JSON format for parameter overrides
-
Connect to Renderer
- Use the parameter output to control rendering
- Generate multiple variations with different seeds
Batch Processing Workflow
-
Add Batch Processor Node
- Set input directory containing .sbs files
- Configure operation mode (cook, render, or both)
- Set parameter variations for multiple outputs
-
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 fileoutput_directory
(STRING): Directory for output .sbsar fileoutput_name
(STRING, optional): Custom output filenameoptimization_level
(INT): Cooking optimization (0-3)enable_icons
(BOOLEAN): Include graph iconsmerge_graphs
(BOOLEAN): Merge all graphs into one fileverbose
(BOOLEAN): Enable detailed logging
Outputs:
sbsar_file_path
(STRING): Path to generated .sbsar filecooking_log
(STRING): Command output and logsoutput_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 fileoutput_directory
(STRING): Directory for texture outputsoutput_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 patterngraph_selection
(STRING, optional): Specific graph to renderoutput_selection
(STRING, optional): Specific outputs to renderparameters
(STRING): JSON parameter overridespreset_name
(STRING, optional): Preset to applycpu_count
(INT): Maximum CPU cores (0 = auto)memory_budget
(INT): Memory limit in MBresolution
(INT): Output texture resolution (256-4096, default: 1024)return_images
(BOOLEAN): Load images as ComfyUI tensorsverbose
(BOOLEAN): Enable detailed logginginput_image_1
(IMAGE, optional): First input image for material parametersinput_image_1_param
(STRING): Parameter name for input_image_1input_image_2
(IMAGE, optional): Second input image for material parametersinput_image_2_param
(STRING): Parameter name for input_image_2input_image_3
(IMAGE, optional): Third input image for material parametersinput_image_3_param
(STRING): Parameter name for input_image_3input_image_4
(IMAGE, optional): Fourth input image for material parametersinput_image_4_param
(STRING): Parameter name for input_image_4
Outputs:
texture_paths
(STRING): JSON list of generated texture pathstexture_images
(IMAGE): ComfyUI image tensorsorganized_outputs
(STRING): JSON organized by texture typerender_log
(STRING): Command output and logsoutput_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 fileparameter_overrides
(STRING): JSON parameter name-value pairspreset_name
(STRING, optional): Preset name to applyrandom_seed
(INT): Seed for randomization (-1 for random)randomize_parameters
(BOOLEAN): Enable parameter randomizationrandomization_strength
(FLOAT): Randomization intensity (0.0-1.0)extract_info
(BOOLEAN): Extract material information
Outputs:
parameter_json
(STRING): Final parameter values as JSONapplied_parameters
(STRING): Complete parameter application infomaterial_info
(STRING): Extracted material metadatapreset_info
(STRING): Applied preset information
Substance Batch Processor
Processes multiple Substance files or generates multiple variations efficiently.
Inputs:
input_directory
(STRING): Directory containing input filesoutput_base_directory
(STRING): Base output directoryoperation_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 setsoutput_format
(COMBO): Output image formatbit_depth
(COMBO): Output bit depthoptimization_level
(INT): Cooking optimization levelmax_workers
(INT): Maximum parallel workersorganize_by_material
(BOOLEAN): Organize outputs by material nameverbose
(BOOLEAN): Enable detailed logging
Outputs:
processed_files
(STRING): JSON list of processing resultsbatch_summary
(STRING): Processing statistics and summaryerror_log
(STRING): JSON list of any errors encounteredoutput_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 fileextract_parameters
(BOOLEAN): Extract parameter informationextract_outputs
(BOOLEAN): Extract output informationextract_graphs
(BOOLEAN): Extract graph informationformat_output
(BOOLEAN): Format JSON for readabilityverbose
(BOOLEAN): Enable detailed logging
Outputs:
file_info
(STRING): Basic file information as JSONgraph_info
(STRING): Graph metadata as JSONparameter_info
(STRING): Parameter definitions as JSONoutput_info
(STRING): Output channel information as JSONformatted_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
- Check the error logs for specific error messages
- Verify your Substance files work with the command line tools directly
- Test with simple workflows before complex batch operations
- 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 conversionmaterial_rendering.json
: Complete material rendering workflowparameter_variations.json
: Generating material variationsbatch_processing.json
: Processing multiple materialsadvanced_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