用途:面向 Blender Python(bpy)开发,梳理运行时行为的正确用法,重点是避免常见崩溃与失效问题。
主要能力与要点:
- 线程安全:禁止在后台线程调用任何 bpy API;纯 Python 与 mathutils 可在线程中运行;bpy.data、bpy.ops、bpy.context 相关调用需通过 bpy.app.timers 排队到主线程。
- 撤销/重做:不得跨撤销边界保存 bpy.data 引用,应保存对象名称后按名称重新获取。
- handlers:注册时须加 @persistent,并在 addon 的 unregister() 中移除。
- timers:回调在主线程执行,返回 None 为一次性,返回浮点数为重复执行;避免放入重计算。
- mathutils:矩阵乘法必须用 @ 运算符;KDTree 插入全部点后须调用 kd.balance();BVHTree.FromObject() 须传入 depsgraph。
- msgbus:属性变更订阅为 POSTPONED 且每周期仅触发一次,除非设置 PERSISTENT 否则文件加载后清除。
- 空间查询选择:最近点用 KDTree,射线/表面求交用 BVHTree,简单距离用 Vector 运算。
- 版本差异:Blender 5.0+ 移除 bgl(改用 gpu)、移除 RNA 属性的 del obj["prop"](改用 property_unset)、移除 img.bindcode 与 img.gl_load()。
使用方式:可作为 Blender 脚本/插件开发的运行时检查清单与模式参考,配合后台模式 blender --background -P script.py 运行。
限制:内容为运行时行为参考,不涉及具体建模或渲染流程;不同 Blender 版本存在 API 差异,需按版本核对。