用途:指导使用 bpy API 开发 Blender 插件,覆盖插件结构、操作符、面板、属性、场景安全操作与跨版本测试。
主要能力:搭建以 init.py 为入口的插件包,使用 blender_manifest.toml(Blender 4.2+ 扩展)或 bl_info(旧版)描述元数据;用 PropertyGroup 定义分组设置并注册到相应 ID 类型;继承 bpy.types.Operator 实现用户操作,含 poll() 可用性检查、invoke() 交互设置、execute() 实际执行;继承 bpy.types.Panel 构建 UI;在 register()/unregister() 中成对注册与注销类及属性指针。
使用方式:将类列入 classes 元组,register() 逐个注册,unregister() 逆序注销;操作符需显式定义 bl_idname(小写 category.action 格式)、bl_label、bl_options;成功返回 {'FINISHED'},失败或用户取消返回 {'CANCELLED'};读取含修改器的最终场景状态时用 bpy.context.evaluated_depsgraph_get() 与 object.evaluated_get(depsgraph)。
适用场景:为 Blender 添加自定义操作、面板与持久化设置,打包为 zip 或扩展包分发。
限制与注意:unregister() 必须清理自定义属性、bpy.app.handlers、定时器与快捷键;不得在 Panel.draw() 中修改数据;避免在 draw() 中重复扫描大场景;模态操作符不要阻塞 UI 线程,长任务用 event_timer_add() 配合状态机;批量网格编辑用 bmesh;路径用 bpy.path.abspath 等工具解析而非硬编码;测试用 blender --factory-startup 干净配置并验证注销后无残留。