substance-3d-texturing

What this skill does

# Substance 3D Texturing

## Overview

Master PBR (Physically Based Rendering) texture creation and export workflows for web and real-time engines. This skill covers Substance 3D Painter workflows from material creation through web-optimized texture export, with Python automation for batch processing and integration with WebGL/WebGPU engines.

**Key capabilities:**
- PBR material authoring (metallic/roughness workflow)
- Web-optimized texture export (glTF, Three.js, Babylon.js)
- Python API automation for batch export
- Texture compression and optimization for real-time rendering

## Core Concepts

### PBR Workflow

Substance 3D Painter uses the **metallic/roughness** PBR workflow with these core channels:

**Base Texture Maps:**
- `baseColor` (Albedo) - RGB diffuse color, no lighting information
- `normal` - RGB normal map (tangent space)
- `metallic` - Grayscale metalness (0 = dielectric, 1 = metal)
- `roughness` - Grayscale surface roughness (0 = smooth/glossy, 1 = rough/matte)

**Additional Maps:**
- `ambientOcclusion` (AO) - Grayscale cavity/occlusion
- `height` - Grayscale displacement/height
- `emissive` - RGB self-illumination
- `opacity` - Grayscale transparency

### Export Presets

Substance 3D Painter includes built-in export presets for common engines:
- **PBR Metallic Roughness** - Standard glTF/WebGL format
- **Unity HDRP/URP** - Unity pipelines
- **Unreal Engine** - UE4/UE5 format
- **Arnold (AiStandard)** - Renderer-specific

For web engines, **PBR Metallic Roughness** is the universal standard.

### Texture Resolution

Common resolutions for web (powers of 2):
- 512×512 - Low detail props, mobile
- 1024×1024 - Standard props, characters
- 2048×2048 - Hero assets, close-ups
- 4096×4096 - Showcase quality (use sparingly)

**Web optimization rule:** Start at 1024×1024, scale up only when texture detail is visible.

## Common Patterns

### 1. Basic Web Export (Three.js/Babylon.js)

Manual export workflow for single texture set:

**Steps:**
1. **File → Export Textures**
2. **Select preset:** "PBR Metallic Roughness"
3. **Configure export:**
   - Output directory: Choose target folder
   - File format: PNG (8-bit) for web
   - Padding: "Infinite" (prevents seams)
   - Resolution: 1024×1024 (adjust per asset)
4. **Export**

**Result files:**
```
MyAsset_baseColor.png
MyAsset_normal.png
MyAsset_metallicRoughness.png  // Packed: R=nothing, G=roughness, B=metallic
MyAsset_emissive.png           // Optional
```

**Three.js usage:**
```javascript
import * as THREE from 'three';

const textureLoader = new THREE.TextureLoader();

const material = new THREE.MeshStandardMaterial({
  map: textureLoader.load('MyAsset_baseColor.png'),
  normalMap: textureLoader.load('MyAsset_normal.png'),
  metalnessMap: textureLoader.load('MyAsset_metallicRoughness.png'),
  roughnessMap: textureLoader.load('MyAsset_metallicRoughness.png'),
  aoMap: textureLoader.load('MyAsset_ambientOcclusion.png'),
});
```

### 2. Batch Export with Python API

Automate export for multiple texture sets:

```python
import substance_painter.export
import substance_painter.resource
import substance_painter.textureset

# Define export preset
export_preset = substance_painter.resource.ResourceID(
    context="starter_assets",
    name="PBR Metallic Roughness"
)

# Configure export for all texture sets
config = {
    "exportShaderParams": False,
    "exportPath": "C:/export/web_textures",
    "defaultExportPreset": export_preset.url(),
    "exportList": [],
    "exportParameters": [{
        "parameters": {
            "fileFormat": "png",
            "bitDepth": "8",
            "dithering": True,
            "paddingAlgorithm": "infinite",
            "sizeLog2": 10  // 1024×1024
        }
    }]
}

# Add all texture sets to export list
for texture_set in substance_painter.textureset.all_texture_sets():
    config["exportList"].append({
        "rootPath": texture_set.name()
    })

# Execute export
result = substance_painter.export.export_project_textures(config)

if result.status == substance_painter.export.ExportStatus.Success:
    for stack, files in result.textures.items():
        print(f"Exported {stack}: {len(files)} textures")
else:
    print(f"Export failed: {result.message}")
```

### 3. Resolution Override per Asset

Export different resolutions for different assets (e.g., hero vs. background):

```python
config = {
    "exportPath": "C:/export",
    "defaultExportPreset": export_preset.url(),
    "exportList": [
        {"rootPath": "HeroCharacter"},   # Will use 2048 (override below)
        {"rootPath": "BackgroundProp"}   # Will use 512 (override below)
    ],
    "exportParameters": [
        {
            "filter": {"dataPaths": ["HeroCharacter"]},
            "parameters": {"sizeLog2": 11}  # 2048×2048
        },
        {
            "filter": {"dataPaths": ["BackgroundProp"]},
            "parameters": {"sizeLog2": 9}   # 512×512
        }
    ]
}
```

### 4. Custom Export Preset (Separate Channels)

Create custom preset to export metallic and roughness as separate files:

```python
custom_preset = {
    "exportPresets": [{
        "name": "WebGL_Separated",
        "maps": [
            {
                "fileName": "$textureSet_baseColor",
                "channels": [
                    {"destChannel": "R", "srcChannel": "R", "srcMapType": "documentMap", "srcMapName": "baseColor"},
                    {"destChannel": "G", "srcChannel": "G", "srcMapType": "documentMap", "srcMapName": "baseColor"},
                    {"destChannel": "B", "srcChannel": "B", "srcMapType": "documentMap", "srcMapName": "baseColor"}
                ]
            },
            {
                "fileName": "$textureSet_normal",
                "channels": [
                    {"destChannel": "R", "srcChannel": "R", "srcMapType": "documentMap", "srcMapName": "normal"},
                    {"destChannel": "G", "srcChannel": "G", "srcMapType": "documentMap", "srcMapName": "normal"},
                    {"destChannel": "B", "srcChannel": "B", "srcMapType": "documentMap", "srcMapName": "normal"}
                ]
            },
            {
                "fileName": "$textureSet_metallic",
                "channels": [
                    {"destChannel": "R", "srcChannel": "R", "srcMapType": "documentMap", "srcMapName": "metallic"}
                ],
                "parameters": {"fileFormat": "png", "bitDepth": "8"}
            },
            {
                "fileName": "$textureSet_roughness",
                "channels": [
                    {"destChannel": "R", "srcChannel": "R", "srcMapType": "documentMap", "srcMapName": "roughness"}
                ],
                "parameters": {"fileFormat": "png", "bitDepth": "8"}
            }
        ]
    }]
}

config = {
    "exportPath": "C:/export",
    "exportPresets": custom_preset["exportPresets"],
    "exportList": [{"rootPath": "MyAsset", "exportPreset": "WebGL_Separated"}]
}
```

### 5. Mobile-Optimized Export

Aggressive compression for mobile WebGL:

```python
mobile_config = {
    "exportPath": "C:/export/mobile",
    "defaultExportPreset": export_preset.url(),
    "exportList": [{"rootPath": texture_set.name()}],
    "exportParameters": [{
        "parameters": {
            "fileFormat": "jpeg",        # JPEG for baseColor (lossy but smaller)
            "bitDepth": "8",
            "sizeLog2": 9,               # 512×512 maximum
            "paddingAlgorithm": "infinite"
        }
    }, {
        "filter": {"outputMaps": ["$textureSet_normal", "$textureSet_metallicRoughness"]},
        "parameters": {
            "fileFormat": "png"          # PNG for data maps (need lossless)
        }
    }]
}
```

**Post-export:** Use tools like `pngquant` or `tinypng` for further compression.

### 6. glTF/GLB Integration

Export textures for glTF 2.0 format:

```python
gltf_config = {
    "exportPath": "C:/export/gltf",
    "defaultExportPreset": substance_painter.resource.ResourceID(
        context="starter_assets",
        name="