Blender 插件开发

技能文档

---
name: blender-plugin-dev
title: Blender 插件开发
category: 开发工具
description: 开发、调试与升级 Blender 插件（add-on）及 bpy 脚本，兼容 Blender 4.x 与 5.x API 差异。生成新插件代码、搭建 operator/panel 脚手架、迁移废弃 Python API、修复 Blender 版本升级导致的报错、校验脚本对 4/5 的兼容性时使用。当用户提到 Blender 插件、bpy 脚本、operator、panel、插件迁移、API 废弃报错时触发。触发词：Blender、插件、bpy、operator、API 迁移。
---

# Blender 插件开发

## 适用场景

- 从零生成一个 Blender 4/5 兼容的插件包
- 编写独立的 bpy 脚本
- 将旧版插件迁移到 Blender 5.x
- 排查 Blender 版本升级引发的 API 中断

## 技能工作流

### 步骤1：明确任务范围

- 提取目标行为、UI 位置、operator 名称与数据模型。
- 用户未说明版本范围时询问；默认按 `>= 4.0` 处理并兼顾 5.x。
- 确定交付形态：
  - 完整插件包；
  - 独立 `bpy` 脚本；
  - 针对既有代码的迁移补丁。

### 步骤2：新建插件时生成基线脚手架

运行：

```bash
python3 scripts/scaffold_addon.py --name "<Addon Name>" --output <target-dir>
```

按需求定制生成的 `__init__.py`、`operators.py`、`ui.py` 与 `compat.py`。`bl_info["blender"]` 保持为最低支持版本（通常 `(4, 0, 0)` 或更高）。

### 步骤3：编写兼容性安全的代码

- 仅在行为真正分叉时使用 `bpy.app.version` 判断。
- 兼容封装统一放 `compat.py`，避免到处散落版本检查。
- 不使用 `references/blender4_to_5_compat.md` 中标记为移除/废弃的 API。
- operator 上下文覆盖使用 `context.temp_override(...)`。
- 资产访问优先 `context.asset` 与 `AssetRepresentation`。
- 5.x 的 GPU 绘制不使用 `bgl`，迁移到 `gpu`。

### 步骤4：交付前校验

- 对改动的 Python 文件运行 `python3 -m py_compile`。
- 本机有 Blender 时执行无头冒烟测试：

```bash
blender --background --factory-startup --python <smoke_test.py>
```

- 检查 register/unregister 顺序与 operator `bl_idname` 格式。
- 确认生成代码中不含已移除的 API 名称。

## 脚本生成模式

- 生成小而可组合的文件：
  - `operators.py` 放 operator；
  - `ui.py` 放面板/菜单；
  - `compat.py` 放版本垫片；
  - `__init__.py` 放 `bl_info` 与注册入口。
- register/unregister 必须幂等。
- 类列表显式声明（类元组），按逆序注销。
- operator 内部用 `self.report({"ERROR"}, "...")` 上报可操作的失败信息。
- `poll()` 与 `execute()` 中避免硬编码上下文假设。

## 必守兼容规则

- 5.0 中访问插件自定义数据的运行时 RNA 属性时，禁止字典式访问；使用 Blender 5.0 发行说明记载的受支持属性访问方式。
- 不导入 5.0 起转为私有的内置模块（如 `bl_ui_utils`、`rna_info`）。
- 视 `scene.use_nodes` 为已废弃，新代码不再使用。
- 新代码避免 `UILayout.template_asset_view()`；改用资产架（asset shelf）兼容 API。
- 主动处理 5.0 已记载的废弃项，为 6.0 的移除提前做好准备。

## 参考资料

- `scripts/scaffold_addon.py`：生成 Blender 4/5 就绪的插件包骨架。
- `references/blender4_to_5_compat.md`：Blender 4.0 → 5.0 兼容对照与官方出处。
- `references/script_generation_patterns.md`：operator、面板与后台脚本的复用模板。

使用说明

# Blender 插件开发

开发、调试与升级 Blender 4.x/5.x 插件及 bpy 脚本，内置版本兼容对照与脚手架生成器。

## 使用

```text
帮我写一个 Blender 插件，在 3D 视图侧边栏加一个带按钮的面板
```

```text
把这个 Blender 4.x 插件迁移到 5.0，处理 API 废弃报错
```

一键生成插件骨架：

```bash
python3 scripts/scaffold_addon.py --name "My Addon" --output .
```

## 工作原理

技能按「明确范围 → 生成脚手架 → 写兼容安全代码 → 交付前校验」四步工作：先生成含 `__init__.py`/`operators.py`/`ui.py`/`compat.py` 的插件包，再按 Blender 4→5 兼容对照表编写代码（避免已移除 API、集中管理版本垫片），最后用 `py_compile` 与 Blender 无头模式冒烟测试验证注册流程。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。