Assets Tools

Substance 3D Painter 插件，窗口显示 Assets 工具 By-贰壹，包含画布、素材库和图层功能。

安装

Windows 用户双击发布页的 Assets-Tools-Setup-v版本号.exe，按界面完成“准备 → 安装 → 完成”三个步骤，无需选择目录、解压或另外安装 Python。安装器识别系统文档目录（含重定向或 OneDrive）、Painter 安装信息、自定义 SUBSTANCE_PAINTER_PLUGINS_PATH 和既有插件；保留设置、备份旧代码，迁移旧 ai_view_to_paint 包，避免重复加载。只有文件写入并校验通过才显示“安装成功”；此时可直接启动 Painter，插件会自动启用。

首次安装时如 Painter 已运行，准备界面先提示“请先保存并关闭 Painter”。点击“等待关闭后安装”后，界面醒目显示“尚未安装，请关闭 Painter”，进度保持为零。保存项目并退出 Painter，保留安装器窗口，安装会自动继续。等待时可取消；失败时可查看错误并重试。已经安装的用户直接使用插件内“升级”，会自动定位当前插件目录、安装并重载，无需退出软件。

画布登录记录独立保存在 %LOCALAPPDATA%/AIViewToPaint/loomic-session.bin，使用当前 Windows 用户的 DPAPI 加密，仅保存会话，不保存密码。删除插件或重新安装会保留本机登录；点击画布中的“退出”会删除该记录。安装包不包含登录记录或账号，其他电脑安装后需要自行登录。

启动脚本优先加载实际安装目录，避免同名源码目录覆盖插件。Painter 主窗口显示稳定后自动启用并打开工具，同时同步 Python 菜单的勾选状态，无需手动刷新插件文件夹。等待只发生在启动阶段，成功后停止检查；通过插件内升级也会自动修复旧启动脚本。

手动安装仍可使用发布 ZIP：将其中的 Assets Tools 文件夹放入 Painter 的 python/plugins，从 Python 菜单启用。文件夹名支持空格。

默认输出为 ~/Pictures/Assets_outputs。旧默认目录会在首次读取设置时迁移，图片内容保持不变，JSON 记录中的绝对路径同步更新。自定义输出目录沿用原设置；如果新旧默认目录同时存在，保留旧目录以避免覆盖已有文件。

升级

版本由公开 Forgejo 仓库 haoze/Assets-Tools 的正式 Release 管理。所有用户都可以直接检查和下载升级，无需 Forgejo 账号或令牌。窗口标题栏的“升级”可查看更新内容及手动检查。

每次启动插件在后台检查一次，运行期间每 30 分钟静默检查一次；发现带完整升级包的新正式版本才弹出提示。同一版本在本次运行只自动提醒一次，选择“稍后”后可随时从“升级”打开。网络不可用或没有更新时不打断使用。点击“立即升级”才会下载和安装；生成、截图、映射或素材操作进行时暂停安装。

升级包只更新插件代码和说明，保留本机 settings.json、输出图片和独立登录会话。安装前备份代码到 %LOCALAPPDATA%/AssetsTools/backups；新版加载失败时自动恢复代码。升级后直接重载插件，恢复主输入、参考图、生成模式、截图/结果选择和页签，无需重启 Painter。

发布维护

1. 修改 config.py 的 PLUGIN_PATCH_VERSION，使用 主版本.次版本.修订号。
2. 更新 更新记录.md，运行 python -m unittest discover -s tests -v 和 Painter Qt 验证。 使用 Painter 自带的 resources/pythonsdk/python.exe 执行 tests/qt_startup_smoke.py，检查实际插件管理器、菜单发现、窗口显示时机、去重、取消及启动脚本修复；不打开工程或请求生成服务。
3. 运行 python scripts/build_release.py，生成 outputs/Assets-Tools-v版本号.zip。 Windows 安装器再运行 powershell -File scripts/build_installer.ps1，将同一 ZIP 嵌入单个 EXE，使用 Windows 自带 .NET，无需终端用户安装 Python。 运行 powershell -File scripts/test_installer.ps1 验证安装校验、回滚、等待取消、自动继续、重复操作和失败重试；测试只使用独立临时目录。
4. 提交源码和更新记录，推送到 Forgejo 仓库。
5. 创建 v版本号 的正式 Release，填写更新说明并附加对应 ZIP 和 Setup EXE。草稿、预发布、只有 tag 或缺少 ZIP 的版本不会触发插件升级。

源码与发布包不包含账号密码、访问令牌、本机设置和生成图片。发布 ZIP 是插件可安装包，Forgejo 默认源码归档用于查看源码。