Character Creator to Substance Painter Workflow Automation

A complete workflow automation toolkit that streamlines the process of setting up Character Creator models in Adobe Substance 3D Painter.

Overview

This toolkit consists of two components that work together to automate the tedious process of importing, organizing, and assigning textures for Character Creator characters in Substance Painter:

1. CC_Texture_Setup - Analyzes Character Creator texture exports and generates configuration files
2. CC_Layer_Builder - Substance Painter plugin that automatically creates layers and assigns textures based on the configuration

Features

• Automatic Texture Analysis: Scans Character Creator's texture folder structure and organizes by material and UDIM tile
• Intelligent Layer Creation: Creates properly named fill layers for each texture type and UDIM tile
• Smart Channel Mapping: Automatically assigns textures to correct channels (BaseColor, Roughness, Normal, etc.)
• UDIM Support: Full support for multi-tile UDIM workflows with geometry masking
• Batch Processing: Processes all materials in a character simultaneously
• Massive Time Savings: Automates tedious manual layer creation and texture assignment

Requirements

Software

• Character Creator 4 (or compatible version that exports textures)
• Adobe Substance 3D Painter 11.1.0 or higher
• Python 3.x (for texture setup script)

System

• Windows (batch files provided; Mac/Linux users can run Python scripts directly)
• Substance Painter plugins directory access

Installation

Step 1: Install the Substance Painter Plugin

Option A: Automatic Installation (Windows)

1. Navigate to the CC_Layer_Builder folder
2. Double-click INSTALL.bat
3. Restart Substance 3D Painter

Option B: Manual Installation (All Platforms)

1. Locate your Substance Painter plugins directory:

   • Windows: C:\Users\<YourUsername>\Documents\Adobe\Adobe Substance 3D Painter\python\plugins\
   • Mac: ~/Documents/Adobe/Adobe Substance 3D Painter/python/plugins/
   • Linux: ~/.Adobe/Adobe Substance 3D Painter/python/plugins/

2. Create the directories if they don't exist:

   mkdir -p "Documents/Adobe/Adobe Substance 3D Painter/python/plugins"

3. Copy the entire CC_Layer_Builder folder to the plugins directory:

   plugins/
   └── CC_Layer_Builder/
       ├── plugin.json
       ├── __init__.py
       ├── cc_layer_builder.py
       └── README.md
   

4. Restart Substance 3D Painter

5. Verify installation by checking the Python log:

   • Open Python > Log in Substance Painter
   • Look for "CC Layer Builder plugin loaded successfully"

Step 2: Set Up Texture Setup Script

The texture setup script (texture_setup.py and CC_Texture_Setup.bat) can be placed anywhere convenient. Keep them together in the same folder.

Usage Workflow

Complete Workflow (Per Character)

Step 1: Export Textures from Character Creator

1. In Character Creator, select your character
2. Go to Plugins > Substance Painter Pipeline
3. In the export dialog:
   • Configure your export settings
   • Choose your export location
4. Export the character

Your folder structure should look like:

CharacterName/
├── CharacterName.obj (or .fbx)
└── CharacterName_subpainter/
    └── CharacterName_subpainter/
        ├── Std_Skin_Head/
        │   ├── Std_Skin_Head_1001_diffuse.png
        │   ├── Std_Skin_Head_1001_roughness.png
        │   ├── Std_Skin_Head_1001_normal.png
        │   └── ...
        ├── Std_Skin_Body/
        ├── Std_Eye/
        └── ... (other materials)

Step 2: Generate Configuration File

1. Locate the folder that contains your character's material folders (typically the innermost CharacterName_subpainter folder)
2. Drag and drop this folder onto CC_Texture_Setup.bat
3. The script will:
   • Analyze the texture folder structure
   • Detect all materials and UDIM tiles
   • Generate a JSON configuration file

Output: CharacterName_Painter_Setup.json in the same folder

Example output:

=== CC Texture Auto-Setup for MyCharacter ===
Textures: C:\Characters\MyCharacter\MyCharacter_subpainter\MyCharacter_subpainter
Output: C:\Characters\MyCharacter\MyCharacter_subpainter\MyCharacter_subpainter

Analyzing texture structure...
  Processing material: Std_Skin_Head
  Processing material: Std_Skin_Body
  Processing material: Std_Eye
  ...

SETUP COMPLETE!
Character: MyCharacter
Materials processed: 23
Total layers to create: 127

OUTPUT FILE:
  - Setup guide (JSON): MyCharacter_Painter_Setup.json

Step 3: Set Up Substance Painter Project

1. Create or open project:

   • File > New (or open existing .spp file)

2. Import character mesh:

   • File > Import (or drag and drop)
   • Select the .obj or .fbx file from Character Creator export
   • Wait for import to complete

3. Import ALL textures as resources:

   • Locate the innermost CharacterName_subpainter folder (the one containing material folders)
   • Drag the entire folder into Substance Painter's shelf area
   • In the import dialog:
     • Import as: Texture

4. Save the project:

   • File > Save or File > Save As

Step 4: Run the Plugin

1. Open the Python console and log:

   • Window > Views > Python (for the Python console)
   • Window > Views > Python Log (to monitor progress)

2. Preview what will be created (optional but recommended):

   import CC_Layer_Builder as clb
   clb.diagnose(r"C:\Path\To\YourCharacter_Painter_Setup.json")

   • Replace the path with your actual JSON configuration file path
   • Use raw string r"..." or forward slashes for the path
   • This shows what textures will be assigned without making changes
   • Check the Python Log to verify resources are found

3. Run the full build:

   import CC_Layer_Builder as clb
   clb.run(r"C:\Path\To\YourCharacter_Painter_Setup.json")

   • Replace the path with your actual JSON configuration file path

4. Monitor progress:

   • Watch the Python Log for detailed progress
   • The plugin will:
     • Process each material
     • Create layers for each UDIM tile
     • Assign textures to correct channels
     • Apply UV tile geometry masks

5. Verify results:

   • Check the layer stack for each material
   • Verify textures are assigned to correct channels
   • Check that UV tile masks are applied (layers should only affect their respective UDIM tiles)

Example log output:

==============================================================
CC Layer Builder - Starting
==============================================================
Character: MyCharacter
Materials to process: 23

==================================================
Processing material: Std_Skin_Head
==================================================
Found texture set: Std_Skin_Head
Creating layer for UDIM 1001 (Head) with 6 textures
Created fill layer: Std_Skin_Head_1001
  -> BaseColor: Std_Skin_Head_1001_diffuse.png
  -> Roughness: Std_Skin_Head_1001_roughness.png
  -> Normal: Std_Skin_Head_1001_normal.png
  -> Metallic: Std_Skin_Head_1001_metallic.png
  -> UDIM mask: 1001
Layer complete: 6/6 textures assigned
...

==============================================================
COMPLETE
==============================================================
Materials processed: 23/23
Total layers created: 127

UDIM Tile Mapping

Character Creator uses UDIM tiles for character UV layouts:

UDIM	Body Part	Common Materials
1001	Head	Skin_Head, Eye, Teeth, Tongue
1002	Body/Torso	Skin_Body, Clothing
1003	Legs	Skin_Leg, Pants
1004	Arms	Skin_Arm, Sleeves
1005	Nails	Fingernails, Toenails
1006	Eyelashes	Eyelash

Supported Texture Types

The plugin automatically maps Character Creator texture types to Substance Painter channels:

Texture Type	Substance Channel	Notes
diffuse, basecolor, color	BaseColor	Main color texture
roughness	Roughness	Surface roughness
metallic, metalic	Metallic	Metallic properties
normal, nomal	Normal	Normal/bump mapping
ao	Height	AO routed to Height to avoid channel errors
opacity	Opacity	Transparency
displacement, height	Height	Height/displacement

Project Structure

Character Creator to Substance Painter/
├── README.md                      # This file
├── CC_Texture_Setup.bat          # Windows batch file for texture analysis
├── texture_setup.py              # Python script for texture analysis
└── CC_Layer_Builder/             # Substance Painter plugin folder
    ├── plugin.json               # Plugin metadata
    ├── __init__.py              # Plugin entry point
    ├── cc_layer_builder.py      # Main plugin logic
    ├── README.md                # Plugin-specific documentation
    ├── QUICK_START.md           # Quick reference guide
    ├── INSTALL.bat              # Windows installer
    └── deploy_plugin.bat        # Development deployment script

How It Works

1. Texture Setup Script (texture_setup.py)

The texture setup script analyzes Character Creator's exported texture structure:

• Scans the texture folder hierarchy
• Parses texture filenames using regex pattern: MaterialName_UDIM_MapType.extension
• Organizes textures by material, UDIM tile, and map type
• Generates a JSON configuration file with all mapping information

Example JSON structure:

{
  "character": "MyCharacter",
  "materials": {
    "Std_Skin_Head": [
      {
        "udim": 1001,
        "label": "Head",
        "layers": [
          {
            "type": "diffuse",
            "file": "Std_Skin_Head_1001_diffuse.png",
            "path": "C:\\Characters\\MyCharacter\\..."
          },
          {
            "type": "roughness",
            "file": "Std_Skin_Head_1001_roughness.png",
            "path": "C:\\Characters\\MyCharacter\\..."
          }
        ]
      }
    ]
  }
}

2. Layer Builder Plugin (cc_layer_builder.py)

The Substance Painter plugin reads the JSON configuration and automates layer creation:

1. Loads the JSON configuration
2. Finds texture sets in the current project (matches material names)
3. For each UDIM tile in each material:
   • Creates a single fill layer named MaterialName_UDIM
   • Uses search-based resource finding to locate imported textures
   • Assigns each texture to its appropriate channel
   • Sets UV tile geometry mask to limit the layer to specific UDIM tiles
4. Logs detailed progress and results

Key technical features:

• Uses resource.search() for library-compatible texture finding
• Employs layerstack.insert_fill() for layer creation
• Utilizes layer.set_source(channel, resource_id) for texture assignment
• Implements layer.set_geometry_mask_enabled_uv_tiles() for UDIM masking

Troubleshooting

Plugin Installation Issues

Problem: Plugin doesn't appear in Substance Painter

Solutions:

• Verify the plugin folder is in the correct location
• Check folder structure matches exactly (see Installation section)
• Restart Substance Painter completely
• Check Python log (Python > Log) for error messages
• Ensure plugin.json is valid JSON (no syntax errors)

Texture Setup Issues

Problem: CC_Texture_Setup.bat reports "Could not find texture folder structure"

Solutions:

• Verify you exported with the Substance Painter preset in Character Creator
• Check that the folder structure matches the expected layout
• Try dragging the innermost charactername_subpainter folder instead
• On Mac/Linux, run the Python script directly:

  python texture_setup.py "CharacterName" "/path/to/textures/root"

Problem: JSON file not generated

Solutions:

• Check that texture files follow the naming pattern: MaterialName_UDIM_MapType.extension
• Verify textures are in individual material folders
• Run the batch file from a command prompt to see detailed error messages

Plugin Runtime Issues

Problem: "Resource not found" errors in log

Solutions:

• Make sure you imported ALL textures before running the plugin
• Verify textures are imported as "Textures" not "Images"
• Check that texture filenames in Substance Painter match the JSON configuration
• Try the diagnostic command to see which textures are missing:

  import CC_Layer_Builder as clb
  clb.diagnose(r"C:\Path\To\YourCharacter_Painter_Setup.json")

Problem: "Texture set not found" errors

Solutions:

• Ensure your mesh is imported and texture sets are created in Substance Painter
• Verify material names in Substance Painter exactly match the folder names from Character Creator
• Material names are case-sensitive - check for capitalization differences
• Check the layer stack panel to see what texture sets exist

Problem: Layers created but textures not assigned

Solutions:

• Verify textures were imported as resources (check shelf)
• Try manually dragging a texture onto a layer to verify it works
• Check the Python log for specific assignment error messages
• Re-import textures and ensure they're visible in the shelf

Problem: UV tile masks not working correctly

Solutions:

• This is an advanced feature that may not work with all mesh configurations
• Verify your mesh has proper UDIM UV layout
• Check that texture set includes the expected UDIM tiles
• You can manually adjust geometry masks after plugin completion if needed

Advanced Usage

Diagnostic Mode

Test configuration without creating layers:

import CC_Layer_Builder as clb
clb.diagnose(r"C:\Path\To\YourCharacter_Painter_Setup.json")

This will:

• Load the configuration
• Check which texture resources are found/missing
• Report statistics without making changes

Running the Plugin

Always specify the full path to your configuration file:

import CC_Layer_Builder as clb
clb.run(r"C:\Path\To\YourCharacter_Painter_Setup.json")

Manual Python Script Execution (Mac/Linux)

python texture_setup.py "CharacterName" "/path/to/charactername_subpainter/charactername_subpainter"

Performance

Scalability

The plugin handles:

• ✅ Single UDIM materials (e.g., props, accessories)
• ✅ Multi-UDIM materials (e.g., skin with 6 UDIM tiles)
• ✅ Complex characters (20+ materials, 100+ layers)
• ✅ Batch processing (all materials processed in one run)

Known Limitations

1. Platform-specific scripts: Batch files are Windows-only (Mac/Linux users can run Python scripts directly)
2. Material name matching: Material names must exactly match between Character Creator export and Substance Painter
3. No UI: Plugin runs from Python console (no graphical interface)
4. Substance Painter required: Requires Painter 11.1.0+ (uses modern Python API)

Development

Requirements

• Substance Painter 11.1.0+
• Python 3.x
• Substance Painter Python API knowledge

Testing

1. Use a simple test character first (e.g., character with 3-4 materials)
2. Verify plugin loads correctly
3. Test with single material before processing entire character
4. Check Python log for detailed progress
5. Verify texture assignments and UV masks

Deployment

For development, use deploy_plugin.bat to copy files to the plugins directory without manual copying.

Contributing

Contributions are welcome! Areas for improvement:

• Mac/Linux installation scripts
• GUI for plugin execution (file picker, progress bar)
• Support for additional texture types
• Preset configurations for different Character Creator versions
• Automated testing suite

License

This project is provided as-is for Character Creator and Substance Painter users to streamline their workflow.

Credits

Developed for automating Character Creator to Substance Painter workflows, specifically designed around Character Creator's UDIM-based texture export structure.

Support

For issues, questions, or feature requests:

1. Check the Troubleshooting section
2. Review the CC_Layer_Builder/README.md for plugin-specific details
3. Check the Substance Painter Python log for detailed error messages
4. Consult the Substance Painter Python API documentation

Changelog

Version 1.0.0 (Initial Release)

• Automated texture analysis from Character Creator exports
• JSON configuration generation
• Substance Painter plugin with layer creation automation
• Texture assignment to correct channels
• UDIM tile masking support
• Batch processing for entire characters
• Search-based resource finding for library support