User Guide

Overview

This plugin exports materials and optional geometry from Adobe Substance Painter to USD. It supports multiple render engines (USD Preview Surface, MaterialX Standard Surface, MaterialX OpenPBR, Arnold) and writes a layered, component-style USD publish that follows the ASWF Asset Structure.

Compatibility

  • Substance Painter: 8.3.0+ (older versions will not load the plugin).

  • USD: usd-core must be available in the Substance Painter Python environment.

  • Layout: Component asset layout consistent with ASWF Asset Structure.

Installation (End Users)

  1. Download the packaged release zip (axe_usd_plugin.zip) from GitHub Releases.

  2. Unzip it into your Substance Painter plugins folder:

    • <DOCUMENTS>/Adobe/Adobe Substance 3D Painter/python/plugins/

    This should create axe_usd_plugin/ directly inside the plugins folder.

  3. Restart Substance Painter.

Important

If you previously installed AxeFX_usd_plugin.py, sp_usd_creator/, axe_usd/, or an older axe_usd_plugin.py, delete them before copying the new build to avoid duplicate plugins.

Usage

  1. Open Substance Painter.

  2. Menu: Plugins → USD Exporter.

  3. Configure:

    • Render Engines: USD Preview, MaterialX (Standard Surface), OpenPBR (MaterialX), Arnold.

    • Export Options: enable Include Mesh Geometry to export a mesh layer.

    • USD Preview Options: optional texture format override (Auto/JPEG/PNG) and max resolution.

    • Publish Folder: the plugin writes USD next to your texture export folder (no UI field).

    • Primitive Path: currently fixed to /Asset (used for the component asset name and prims).

    • Save Geometry: exports mesh into <AssetName>/geo.usdc if enabled.

    • Advanced → Log Level: controls logging verbosity.

  4. Export textures normally in Substance Painter. After export finishes, the plugin writes USD files.

Output Layout (ASWF Component)

When you export textures to a directory like C:\Projects\Exports\my_asset, the plugin writes into <export_dir>/<AssetName>/ (AssetName comes from the primitive path, default Asset):

  • <AssetName>/<AssetName>.usd (main entry point)

  • <AssetName>/payload.usdc (references geometry + materials)

  • <AssetName>/geo.usdc (geometry layer when enabled)

  • <AssetName>/mtl.usdc (materials layer)

  • <AssetName>/textures/ (all exported textures, moved from the export folder)

  • <AssetName>/textures/previewTextures/ (USD Preview textures when enabled)

USD Prims (Component Layout)

  • /__class__/<AssetName> class prim for inheritance

  • /<AssetName> root prim (Kind=component, payloads payload.usdc)

  • /<AssetName>/mtl material scope.

  • /<AssetName>/geo scope with /render and /proxy scopes when geometry is exported

Texture Naming Conventions

The plugin looks for tokens in exported texture file names:

  • base_color, basecolor, albedo, diffuse → base color

  • metallic, metalness → metalness

  • roughness → roughness

  • normal → normal

  • opacity, alpha → opacity

  • emission, emissive, glow → emission

  • occlusion, ao → occlusion

  • height, displacement → displacement

Tokens are matched as standalone words (non-alphanumeric boundaries), so unrelated substrings like road do not match ao. Unknown texture files are ignored, and materials are still authored when only a subset of maps is available.

Notes

  • USD Preview uses metallic, Arnold/MaterialX use metalness. The plugin normalizes this for you.

  • The publish folder is derived from the texture export directory (USD is written alongside it).

  • When OpenPBR is enabled, the exporter skips MaterialX Standard Surface to avoid duplicate outputs.

  • By default, non-USDPreview renderers use png texture overrides unless customized via the API.

  • Advanced: per-renderer texture format overrides (usd_preview, arnold, mtlx, openpbr) are available via the API (see Developer Guide).

Troubleshooting

Plugin not showing up:

  • Ensure you are on Substance Painter 8.3.0 or later.

  • Ensure axe_usd_plugin/ is directly inside the Substance Painter plugins directory.

  • Restart Substance Painter.

  • If it still fails, Create a GitHub issue with details about your Substance Painter version, OS and logs.

No USD files written:

  • Make sure texture export succeeded and produced files.

  • Confirm publish directory is valid and writable.

Missing metalness or displacement:

  • Check texture filenames include metallic/metalness or height/displacement tokens.

USD import errors:

  • Verify usd-core is available in your Python environment if testing outside Substance Painter.