blender-addon-development

插件（扩展）开发

执行模型位于 blender-core 中。请从 assets/addon_template/ 开始（已在 CI 中验证、构建和注册）：blender_manifest.toml、__init__.py、operators.py、ui.py。

流程

1. 复制模板，然后设置 id（小写字母加下划线，永久不变）、name、tagline（末尾不加句号，≤ 64 个字符）、maintainer、version（semver）、license（SPDX；使用 bpy 的代码须采用 GPL-3.0-or-later），以及 blender_version_min = "4.2.0"；如果使用更新的 API，则设为更高版本（例如，使用 GN properties.inputs API 时设为 "5.2.0"）。
2. 按照前缀约定为类命名：MYTOOL_OT_x（操作器）、_PT_（面板）、_MT_（菜单）、_PG_（属性组）、_AP_（首选项）、_UL_（UI 列表）。操作器的 bl_idname 格式为 my_tool.verb_noun。
3. 验证并构建：

   blender --command extension validate ./my_tool
   blender --command extension build --source-dir ./my_tool --output-dir ./dist
   blender --command extension install-file -r user_default -e ./dist/my_tool-1.0.0.zip
   

4. 进行无头测试：在进程内注册该包，使用 temp_override 调用操作器，并断言数据（参见本仓库中的 tests/test_addon.py）。

规则（扩展时代，5.x）

• 仅使用相对导入（from . import ops）。包名由 Blender 决定，因此首选项应使用 bl_idname = __package__。
• 不要使用 bl_info（扩展会忽略它）。所有信息都应放入清单中。
• 导入／注册时不得访问网络或文件。 声明 [permissions]（files、network、clipboard、camera、microphone）并说明原因。进行任何网络调用前，先检查 bpy.app.online_access。
• 第三方 Python 包：将 .whl 文件放入 ./wheels/，并在 wheels = [...] 中列出。运行时不得使用 pip install。平台专用 wheel 需要设置 platforms = [...]。
• 属性（5.0+）：bpy.props 值是属性，而不是字典条目（scene["my_prop"] 不再能访问这些值）。只读属性请使用 options={'READ_ONLY'}。get_transform/set_transform 在保留存储方式的同时转换值。通过 ID 类型上的 PointerProperty(type=PG) 注册，并在注销时将其 del 掉。
• 操作器：设置 bl_options={"REGISTER","UNDO"}，以支持撤销和重做面板。使用 poll() 检查上下文。返回 {"FINISHED"}/{"CANCELLED"}。使用 self.report({"WARNING"}, msg) 向用户反馈。如果存在数据 API，不要在循环中调用其他操作器。
• UI：layout.use_property_split = True 可实现现代化对齐。N 面板中的面板使用 bl_region_type="UI" + bl_category。使用 VIEW3D_MT_*.append(func) 添加菜单项，并在注销时移除。
• 按相反顺序注销所有内容（类、属性、菜单、处理器、计时器、快捷键映射、绘制处理器）。泄漏会导致重新加载失败。
• 绘制（叠加层）：使用 gpu 模块和 gpu_extras.batch。bgl 已在 5.0 中移除。纹理通过 gpu.texture.from_image(img) 获取。对于场景线性图像，使用 draw_texture_2d(..., is_scene_linear_with_rec709_srgb_target=True)。
• 长时间任务：使用带计时器的模态操作器（wm.event_timer_add），或使用 bpy.app.timers.register 分块处理。不要让 UI 卡顿数秒。
• 处理器：为持久处理器添加 @bpy.app.handlers.persistent 装饰器。保持处理器开销低（它们会在每帧／每次 depsgraph 更新时运行）。
• 快捷键映射：将其添加到 wm.keyconfigs.addon，保存 (km, kmi) 对，并在注销时移除。
• 翻译／国际化：bpy.app.translations.register(__package__, dict)。

发布（extensions.blender.org）

Blender ID 账户会上传构建好的 zip。要求：清单有效、许可证与 GPL 兼容、代码未混淆、不捆绑无来源的二进制文件，并且已声明权限。截图／README 放在网站列表页面上。更新时使用更高的 version。

注意事项

• 在某些编辑器中，绘制函数里的 context.scene 可能是 None。请进行保护。
• 在 Python 全局变量中存储 Blender 数据引用（bpy.types.ID）会在撤销操作或加载文件后导致崩溃。请存储名称或 session_uid，并在需要时重新查找。
• 如果属性注解使用 = 而非 :，bpy.utils.register_class 会失败。
• 5.0 将若干捆绑模块设为私有模块（rna_info、bl_ui_utils 等）。不要导入它们。
• 5.1 起，默认不再加载用户的 site-packages。请捆绑 wheels，而不要依赖用户安装的包。
• 5.2：PreferencesFilePaths.active_asset_library 的索引存在偏移（会先列出“All”／“Essentials”条目）。UILayout.template_palette(color=) 已移除。新增：UILayout.link、UILayout.textbox、bpy.data.all_ids、Window.screenshot。