mcpField
B
blender-pipeline-automation

blender-pipeline-automation

github.com/el4cteo创意与媒体56995 次安装2 周前更新
代码仓库

关于 blender-pipeline-automation

面向技术美术和资产团队的 Blender 流水线自动化技能，介绍无界面批处理、JSON 结果、并行分片和可复现脚本实践。

主要功能

  1. 01无界面批量转换与报告
  2. 02对多个资产文件运行脚本
  3. 03JSON 结果与失败汇总
  4. 04使用分片标志并行处理
  5. 05CI 与 bpy 使用指南

适用场景

  1. 01批量将 FBX 资产转换为 GLB
  2. 02生成资产库清单报告
  3. 03对多个文件运行 QA 或 LOD 脚本
  4. 04在 CI 中自动执行 Blender 任务

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/el4cteo/blender-skills --skill blender-pipeline-automation

安装后在 Claude Code 中输入/blender-pipeline-automation确认已加载。

附带文件scripts/_bpyx.pyscripts/batch_process.py

详细介绍

管线自动化

执行模型位于 blender-core 中（run_in_blender.py 会查找 Blender，并且只打印 JSON 结果）。

批量单行命令

blender -b -P scripts/batch_process.py -- --in "assets/**/*.fbx" --op convert --to glb --out export/
blender -b -P scripts/batch_process.py -- --in library/ --op report                      # inventory JSON lines
blender -b -P scripts/batch_process.py -- --in "src/*.blend" --op script \
    --script ../blender-asset-qa/scripts/qa_check.py --kwargs '{"profile":"game"}'       # QA a whole library
blender -b -P scripts/batch_process.py -- --in src/ --op script --script ../blender-game-optimization/scripts/make_lods.py \
    --kwargs '{"rename":true}' --save-to processed/                                      # LODs for every file

每个文件都会以一行 JSON 的形式流式输出，其中包含 ok、耗时和结果。失败不会中止批处理，摘要会列出失败项。并行：使用 --shard 0/N … --shard N-1/N 启动 N 个进程（Blender 的 Python 只使用一个核心，因此进程数量可随 CPU/GPU 数量扩展）。

无头 CLI 要点

标志含义
-b后台运行，不显示 UI。放在最前面
file.blend运行脚本前先打开文件。顺序很重要：参数按从左到右的顺序执行
-P script.py / --python-expr "..."运行 Python
--python-exit-code 1脚本引发异常时返回非零退出码（CI）
--factory-startup忽略用户偏好设置/插件（保证可复现）。仍会加载捆绑的插件
--addons rigify,io_scene_fbx启用指定插件
-E CYCLES -o //out/#### -F PNG -s 1 -e 10 -a / -f 5渲染（blender-rendering）
--command extension build/validate/install-file扩展工具（blender-addon-development）
-- --my args-- 后的所有内容都会传递给脚本（sys.argv[sys.argv.index("--")+1:]）
--log "*", --debug-python调试。5.0 更改了日志格式，因此不要用正则表达式匹配进度行
环境变量：BLENDER_USER_SCRIPTS、BLENDER_USER_EXTENSIONS、BLENDER_SYSTEM_PYTHON。自定义颜色配置请使用 OCIO。

将 bpy 用作 Python 模块

pip install bpy==5.2.*（Python 3.13，与 Blender 发行版匹配）可在普通 Python 中使用 import bpy，适用于 pytest/CI/网络服务。它没有 UI，默认也没有 GPU 模块，而且体积较大（约 300 MB）。请将其版本锁定为目标 Blender 的版本。bpy wheel 在数据 API 操作方面与 CLI 的行为相同。

库模式

  • 追加/链接：bpy.data.libraries.load(path, link=...)（参见 blender-core/references/bpy-patterns.md）。5.2：加载时，data_from.libraries 会公开嵌套库路径。
  • 写入部分数据：bpy.data.libraries.write(path, {datablocks}, fake_user=True, path_remap="RELATIVE_ALL") 会根据会话构建资产/库文件。
  • 查找文件：bpy.data.file_path_foreach(...)（5.2 标志：UDIM 使用 EXPAND_TOKENS，另有 EXPAND_SEQUENCES、EXPAND_CACHES），而 bpy.utils.blend_paths(absolute=True) 会列出每个外部路径。
  • 重映射/迁移：bpy.ops.file.find_missing_files(directory=...)、make_paths_relative、pack_all。库：lib.filepath = new; lib.reload()。
  • 遍历每个 ID：使用 bpy.data.all_ids（5.2），并使用 bpy.data.orphans_purge(do_recursive=True) 清理。

稳健性规则

  • 尽可能每个进程只执行一个任务。长时间运行的 Blender 会泄漏资源（图像、撤销数据）。batch_process.py 会复用进程，但通过 read_factory_settings(use_empty=True) / open_mainfile 重置。
  • 默认不要写入源文件夹。使用单独的 --out/--save-to，并以 copy=True 写入。
  • 让脚本具备幂等性：重新运行时替换其自身的输出（使用命名的前缀、exist_ok）。
  • 记录 JSON，而非散文：每个文件/作业对应一个对象，方便 Agent 和 CI 解析。
  • 为项目固定 Blender 版本（5.2 LTS）。在输出中记录 bpy.app.version_string + 哈希值（bpy.app.build_hash）。
  • 路径：bpy.path.abspath("//x") 相对于已打开的 .blend。在无头批处理中使用绝对路径，或在 open_mainfile 后设置路径。
  • 容器中的 GPU：Cycles CUDA/OptiX 需要 NVIDIA 容器运行时。否则请使用 CPU。即使在无头模式下，EEVEE 也需要 GPU/EGL。

CI 配置示例（GitHub Actions）

下载 Linux tarball（https://download.blender.org/release/Blender5.2/blender-5.2.2-linux-x64.tar.xz），将其缓存，然后运行 blender -b --factory-startup --python-exit-code 1 -P tests/run_all.py。此仓库的 .github/workflows/ci.yml 是一个可运行的示例。

评论

支持 Markdown