blender-core-runtime

Enforce main-thread bpy access and undo-safe references in Blender Python addons.

30|4|Updated Mar 5, 2026
One-click install
npx skills add https://github.com/Impertio-Studio/Blender-Bonsai-ifcOpenshell-Sverchok-Claude-Skill-Package --skill blender-core-runtime-impertio-studio
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: blender-core-runtime
Source: https://github.com/Impertio-Studio/Blender-Bonsai-ifcOpenshell-Sverchok-Claude-Skill-Package/tree/main/skills/blender/core/blender-core-runtime
Command: npx skills add https://github.com/Impertio-Studio/Blender-Bonsai-ifcOpenshell-Sverchok-Claude-Skill-Package --skill blender-core-runtime-impertio-studio

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill prevents common Blender Python runtime failures that cause crashes, freezes, invalid references after undo/redo, and broken event handling when writing addon and automation code.

Core Features & Use Cases

  • Thread-safety guardrails: Ensures Blender API calls never run from background threads by routing bpy work through bpy.app.timers (worker threads may do pure computation only).
  • Undo/redo-safe reference patterns: Avoids ReferenceError and dangling pointers by storing names/identifiers instead of bpy.data object references across undo boundaries.
  • Correct event + callback usage: Uses @persistent handlers, proper handler cleanup on unregister(), safe msgbus subscriptions, and timer return conventions to keep addons stable across file loads.
  • Correct math + spatial queries: Enforces safe mathutils usage (@ for matrix multiplication, .length_squared for comparisons) and correct KDTree/BVHTree workflows (kd.balance(), evaluated depsgraph for BVHTree).
  • Use Case: Build a Blender addon that listens to depsgraph changes, offloads heavy computations to threads, and updates geometry safely without freezing or crashing after undo/redo.

Quick Start

Use the blender-core-runtime Skill when your Blender Python addon intermittently crashes, freezes, or errors after undo/redo, or when background-thread code must interact with bpy safely.

Frequently Asked Questions about blender-core-runtime

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Why does my Blender Python addon crash after undo/redo operations?

Blender Python crashes after undo/redo occur because storing direct bpy.data object references creates dangling pointers. Store names or identifiers instead of object references across undo boundaries to prevent ReferenceError and instability.

How do I safely call bpy from background threads in Blender addon development?

To safely call bpy from background threads, route all Blender API work through bpy.app.timers to ensure main-thread execution. Worker threads should perform pure computation only, avoiding direct bpy access to prevent runtime crashes.

What is the correct way to use KDTree and BVHTree for spatial queries in Blender Python?

Correct KDTree and BVHTree usage requires calling kd.balance() before queries and using an evaluated depsgraph for BVHTree geometry evaluation. Ensuring proper depsgraph behavior prevents invalid spatial query results during addon runtime.

How do I prevent Blender addons from freezing when using depsgraph handlers and msgbus subscriptions?

Prevent freezing by using @persistent handlers, performing proper handler cleanup on unregister(), and following safe msgbus subscription patterns. Correct timer return conventions keep addons stable across file loads without freezing.

Why does my Blender mathutils code produce incorrect matrix transformations?

Incorrect mathutils matrix transformations happen when using wrong multiplication operators. Use the @ operator for matrix multiplication and .length_squared for vector comparisons to ensure correct math operations and avoid runtime errors.

Can I use Blender Python timers with depsgraph updates without causing instability?

Yes, Blender Python timers can safely handle depsgraph updates by enforcing main-thread bpy access and proper timer return conventions. This approach avoids runtime crashes when listening to depsgraph changes and updating geometry.