Skip to content

alivirgo/Major-AI-Skills / plugins/mas-3d-games/skills/substance-painter

substance-painter

Verified

Automate Substance 3D Painter texturing with the Python API, bake mesh maps safely, pack PBR exports for Unreal/Unity, and debug UDIM, TDR, and color-space failures agents routinely miss.

Adobe Substance 3D Painter AI Skill Guide (Claude)

Overview & Engine Architecture

Adobe Substance 3D Painter is a PBR texture-painting DCC. Agents should treat .spp projects as layer stacks bound to texture sets / UDIMs, bakes as high→low ray contracts (_low/_high or cages), and exports as engine-specific channel packs with explicit color spaces (sRGB vs linear). Automation runs through the in-app substance_painter Python API and, for Designer graphs, the Substance Automation Toolkit (sbscooker / sbsrender)—not the same binary.

┌─────────────────────────────────────────────────────────────┐
│                 Painter bake → paint → export               │
│                                                             │
│  Mesh I/O                                                   │
│  ├── Texture sets from materials / UDIMs                    │
│  └── Low / high / cage naming for baker                     │
│                                                             │
│  Authoring                                                  │
│  ├── Fill / Paint layers, masks, anchor points              │
│  └── Triplanar / UV / Projection                            │
│                                                             │
│  Pipeline                                                   │
│  ├── substance_painter Python (in-app)                      │
│  ├── Export presets (UE5 packed, Unity, Arnold, USD)        │
│  └── SAT: sbscooker / sbsrender (Designer .sbs/.sbsar)      │
└─────────────────────────────────────────────────────────────┘

Version pins: document Painter major version and export preset name in the asset README. Preset URLs and Python module shapes drift—resolve presets by search, do not hardcode fragile internal IDs when a name lookup exists.


When to use / when not to

Use when

  • Baking mesh maps, painting PBR stacks, packing ORM/MRA maps for Unreal/Unity.
  • Scripting project open/export, resolution changes, or batch export of texture sets.
  • Diagnosing normal Y-flip, UDIM gaps, or baker ray misses.

Do not use when

  • Authoring procedural .sbs graphs end-to-end without Painter → Designer + SAT (sbsrender) is primary.
  • High-res sculpt primary → @zbrush then retopo/UV before Painter.
  • Full lookdev lighting in-engine → Unreal/Unity material skills after export.

Operational Capabilities & Agent Directives

  1. Color roles: BaseColor/Emissive → sRGB; Normal/Roughness/Metallic/Height/AO → linear/raw.
  2. Normal convention: DirectX (Y−) for Unreal; OpenGL (Y+) for Unity/Blender—set project + preset together.
  3. Bake naming: *_low / *_high + Match by Mesh Name; or supply an explicit cage.
  4. Export scripts: require an open project; resolve presets via ResourceSearch; check ExportStatus.
  5. Padding: infinite padding for mip-friendly game exports unless packing atlases deliberately.
  6. TDR on Windows: long 4K/8K bakes can trip GPU TDR—bake maps individually or raise delay via authorized IT policy (do not invent registry credentials; document the DWORD only when the user asks for the known OS knob).
  7. Never invent Adobe IDs, license tokens, or cloud credentials.

Production Example: batch export via Python API

Run inside Painter’s Python environment (Plugins / Scripts):

"""Export all texture sets with a named preset."""
from __future__ import annotations

import os

import substance_painter.export
import substance_painter.project
import substance_painter.resource
import substance_painter.textureset


def batch_export(
    output_dir: str,
    preset_name: str = "Unreal Engine 5 (Packed)",
    resolution: int = 2048,
) -> None:
    if not substance_painter.project.is_open():
        raise RuntimeError("PAINTER_PIPELINE_FAIL: no project open")

    os.makedirs(output_dir, exist_ok=True)
    search = substance_painter.resource.ResourceSearch(preset_name)
    preset = next(search, None)
    if preset is None:
        raise RuntimeError(f"PAINTER_PIPELINE_FAIL: preset not found: {preset_name}")

    preset_url = preset.as_url()
    export_list = []
    for texture_set in substance_painter.textureset.all():
        export_list.append(
            {
                "rootPath": texture_set.name(),
                "exportPreset": preset_url,
                "exportParameters": [
                    {
                        "parameters": {
                            "padding": "infinite",
                            "dithering": True,
                            "resolution": [resolution, resolution],
                        }
                    }
                ],
            }
        )

    config = {
        "exportShaderParams": False,
        "exportPath": output_dir,
        "defaultExportPreset": preset_url,
        "exportList": export_list,
    }
    result = substance_painter.export.export_project_textures(config)
    if result.status != substance_painter.export.ExportStatus.Success:
        raise RuntimeError(f"PAINTER_PIPELINE_FAIL: {result.message}")
    print(f"exported {len(result.textures)} maps → {output_dir}")


# Example call — paths supplied by artist/pipeline, not invented secrets
# batch_export(r"D:\Project\Exported_Textures", resolution=4096)

SAT (Designer assets, separate toolkit):

sbscooker --inputs "D:\Materials\metal_damaged.sbs" --output-path "D:\Materials\Compiled" --output-name "metal_damaged"
sbsrender render --input "D:\Materials\Compiled\metal_damaged.sbsar" --output-path "D:\Textures\Batch" --set-value "$outputsize@11,11"

Technical Troubleshooting Matrix

SignatureLikely causeFix path
Normal bake seams / ray missesRay distance or name mismatchMatch by Mesh Name; raise frontal/rear; add cage
UE normals look invertedOpenGL vs DirectXProject normal format DirectX; invert G in preset if needed
Unity looks too glossy/metallicWrong pack / sRGB on data mapsLinear for R/M/AO; verify ORM swizzles
Texture set missing after reimportMaterial slot renamePreserve slot names; Re-project Layer Stack
GPU TDR mid-bakeLong kernel vs Windows TDRBake per-map; lower AA; IT-approved TdrDelay if needed
UDIM gapsMissing tiles / wrong UVVerify UDIM layout in DCC; per-tile texture sets

Best Practices

  1. Lock texel density and resolution per asset class (hero 4K, prop 2K) in the naming README.
  2. Bake once, paint on stable mesh maps; re-bake only when geo changes.
  3. Keep export presets in version control (JSON) for studio-standard packs.
  4. Name exports {asset}_{set}_{channel} for engine importers.
  5. Document engine target (UE5 Packed vs Unity) on the .spp shot note.

Limitations

  • In-app Python is not a headless farm daemon; batch still expects Painter (or SAT for .sbsar).
  • Baker quality depends on cage/UV integrity from the upstream DCC.
  • Stop and ask if Adobe login, floating license servers, or proprietary presets are missing.

Related Skills

  • @zbrush — sculpt source for high poly
  • @blender / @cinema-4d / @houdini — mesh/UV upstream
  • @unreal-engine / @unity — consume packed maps

Agent Operational Directive

MANDATORY: Match normal map API (DirectX vs OpenGL) to the target engine. Export non-color data as linear. Resolve export presets by name and fail loudly on ExportStatus errors. Never invent Adobe credentials or unauthorized registry changes.


Source anchors (research)

finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall