blender-core-runtime

Quick Reference

Critical Warnings

NEVER call ANY bpy API from a background thread — Blender's C/C++ core is NOT thread-safe. Crashes are immediate and unrecoverable.

NEVER store bpy.data references (objects, meshes, materials) across undo/redo boundaries — undo rebuilds the entire data model, invalidating ALL Python pointers.

NEVER omit @persistent on handlers in addons — without it, handlers are silently removed on file load.

NEVER do heavy computation inside bpy.app.timers callbacks — they run on the main thread and freeze the UI.

NEVER use matrix1 * matrix2 for matrix multiplication — the * operator is element-wise. ALWAYS use @ operator.

NEVER use bgl module in Blender 5.0+ — fully removed. Use gpu module.

ALWAYS call kd.balance() after inserting all points into a KDTree — queries return incorrect results without it.