Substance Painter Python API 集成

常规
, ,
1

Substance Painter Python API 集成

概述

NexusLauncher 现在使用 Substance Painter 的 Python API 来自动管理库（Shelves）。

工作原理

1. 启动流程

NexusLauncher 启动 SP
    ↓
设置环境变量
    ├─ NEXUS_SP_LIBRARY_NAME (项目名称)
    ├─ NEXUS_SP_LIBRARY_PATH (库路径)
    └─ SUBSTANCE_PAINTER_PLUGINS_PATH (插件目录)
    ↓
SP 启动并自动加载插件
    ↓
setup_library.py 插件执行
    ├─ 读取环境变量
    ├─ 调用 substance_painter.resource API
    ├─ 添加/更新项目库
    └─ 刷新资源
    ↓
库配置完成

2. Python API 使用

import substance_painter.resource

# 获取所有库
shelves = substance_painter.resource.Shelves.all()

# 添加新库
new_shelf = substance_painter.resource.Shelf.add("ProjectName", "/path/to/library")

# 刷新资源
substance_painter.resource.Shelves.refresh()

# 删除库
substance_painter.resource.Shelf.remove(shelf)

文件结构

template/plugins/substancepainter/
├── setup_library.py          # SP Python 插件（自动执行）
└── SPShelf/                  # 库目录（示例）
    ├── alphas/
    ├── brushes/
    ├── materials/
    ├── smart-materials/
    └── ...（14 个标准文件夹）

配置方法

方案 A：自动配置（推荐）:star:

  1. 在 NexusLauncher 中配置

    {
  "projects": {
    "MyProject": {
      "task_settings": {
        "sp_shelf_path": "H:/Projects/MyProject/SP/Library"
      }
    }
  }
}

  2. 启动 SP

    • 通过 NexusLauncher 启动 SP
    • 插件会自动执行
    • 库会自动添加

  3. 验证

    • 打开 Edit → Settings → Libraries
    • 应该能看到项目库已添加

方案 B：手动运行插件

如果自动配置失败，可以手动运行插件：

  1. 启动 SP（通过 NexusLauncher）

  2. 打开 Python 编辑器

    • Python → Show Editor

  3. 运行插件脚本

    import sys
sys.path.append("E:/Zoroot/Dev/NexusLauncher/template/plugins/substancepainter")
import setup_library
setup_library.main()

方案 C：手动配置

参考 SubstancePainter库手动配置指南.md

环境变量

变量名 说明 示例
NEXUS_SP_LIBRARY_NAME 项目库名称 Project_01
NEXUS_SP_LIBRARY_PATH 库路径 E:/Projects/MyProject/SP/Library
SUBSTANCE_PAINTER_PLUGINS_PATH SP 插件目录 E:/NexusLauncher/template/plugins/substancepainter

API 参考

substance_painter.resource.Shelf

添加库

Shelf.add(name: str, path: str) -> Shelf
  • name: 库名称（不支持空格和特殊字符）
  • path: 库路径（绝对路径）
  • 返回: Shelf 对象

删除库

Shelf.remove(shelf: Shelf) -> None
  • 注意：不能删除默认库（Your Assets）

获取库信息

shelf.name() -> str          # 库名称
shelf.path() -> str          # 库路径
shelf.can_import_resources() -> bool  # 是否可导入资源

substance_painter.resource.Shelves

获取所有库

Shelves.all() -> List[Shelf]

刷新资源

Shelves.refresh() -> None
  • 重新扫描所有库中的资源
  • 更新缩略图

启动日志

成功启动时的日志：

[SubstancePainter] ========================================
[SubstancePainter] Launching Substance Painter
[SubstancePainter] ========================================
[SubstancePainter] Project: Project_01
[SubstancePainter] Shelf Path: E:\...\SPShelf

[SubstancePainter] Created 14 standard folders
[SubstancePainter] ✓ Library structure ready
[SubstancePainter] Set NEXUS_SP_LIBRARY_NAME: Project_01
[SubstancePainter] Set NEXUS_SP_LIBRARY_PATH: E:\...\SPShelf
[SubstancePainter] Set SUBSTANCE_PAINTER_PLUGINS_PATH: E:\...\substancepainter

[SubstancePainter] Starting application...
[SubstancePainter] ✓ Substance Painter launched successfully
[SubstancePainter] ========================================

# SP 启动后，在 Python 控制台中：
[NexusLauncher] ========================================
[NexusLauncher] Substance Painter Library Setup
[NexusLauncher] ========================================
[NexusLauncher] Setting up library: Project_01
[NexusLauncher] Path: E:\...\SPShelf
[NexusLauncher] Found 2 existing shelves
[NexusLauncher] Adding new library...
[NexusLauncher] ✓ Library added successfully
[NexusLauncher] ✓ Resources refreshed
[NexusLauncher] ========================================
[NexusLauncher] ✓ Library setup complete
[NexusLauncher] ========================================

故障排查

Q: 插件没有自动执行？

A: 检查：

  1. SUBSTANCE_PAINTER_PLUGINS_PATH 是否正确设置
  2. setup_library.py 是否存在
  3. SP 是否有权限读取插件目录
  4. 查看 SP 的日志文件

Q: 库添加失败？

A: 可能原因：

  1. 库路径不存在
  2. 库路径没有读写权限
  3. SP 项目已打开（添加库需要关闭项目）
  4. 库名称包含空格或特殊字符

Q: 如何查看 SP 的 Python 日志？

A:

  1. 打开 Python → Show Editor
  2. 查看控制台输出
  3. 或查看 SP 日志文件：
    • Windows: %LOCALAPPDATA%\Adobe\Adobe Substance 3D Painter\log.txt

Q: 如何禁用自动配置？

A:

  1. 删除或重命名 setup_library.py
  2. 或不设置 SUBSTANCE_PAINTER_PLUGINS_PATH

优势

相比配置文件方式：

特性 配置文件 Python API
可靠性 :warning: 格式可能变化 :white_check_mark: 官方 API
实时性 :warning: 需要重启 :white_check_mark: 即时生效
兼容性 :warning: 版本相关 :white_check_mark: 向后兼容
错误处理 :x: 难以检测 :white_check_mark: 异常处理
维护性 :warning: 需要跟踪格式 :white_check_mark: API 稳定

参考资料