tmhsdigital/blender-developer-tools

drivers-and-app-handlers

Drive properties from expressions with the Driver API (driveradd, drivernamespace for custom Python functions) and react to events with bpy.app.handlers (loadpost, savepre, framechangepost, depsgraphupdatepost, exitpre in 5.1+).

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/tmhsdigital/blender-developer-tools --skill drivers-and-app-handlers

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

Drivers and Application Handlers

Trigger

Use this skill when the user:

  • Wants property A to follow property B with some math (driver)
  • Asks about driver_add, FCurve.driver, driver.expression, driver_namespace
  • Wants to run code on file save, file load, frame change, depsgraph update, or process exit
  • Mentions bpy.app.handlers, save_pre, load_post, depsgraph_update_post, exit_pre
  • Has a driver expression that fails security checks because it tries to call a Python function

This skill bundles two related "reactive" patterns. They show up together often (a driver that calls a function registered on a handler), so they share one skill.

Part 1: Drivers

What a driver is

A driver replaces a static animation curve with a real-time-evaluated expression. It is attached to one property (the target) and reads zero or more other properties (the variables), then evaluates a string expression to compute the target's value on each frame.

Concretely: an FCurve whose .driver field is set is a driver. The animation system evaluates driver.expression instead of sampling the curve.

The Driver API

python
import bpy


def add_simple_driver(obj, data_path, index, expression):
    """Attach a driver to obj.data_path[index] that evaluates `expression`.

    Returns the FCurve so the caller can add variables.
    """
    fcurve = obj.driver_add(data_path, index)
    fcurve.driver.type = 'SCRIPTED'
    fcurve.driver.expression = expression
    return fcurve

driver_add(data_path, index):

  • data_path is the RNA path of the property, like "location" or "scale". A user custom (ID) property set with obj["my_custom_prop"] = 1.0 is '["my_custom_prop"]'; a registered bpy.props property is its plain name, "my_prop". On 5.0+ '["my_prop"]' no longer resolves a registered property (ValueError), though it did on 4.x.
  • index is the array index for vector or color properties (0 = X, 1 = Y, 2 = Z), or -1 for scalar properties.
  • Returns the FCurve whose .driver is now active.

Adding variables to a driver

Drivers reference other properties by adding variables to their driver.variables collection. Each variable has a name (used in the expression) and one or two property targets.

python
fcurve = obj.driver_add("location", 0)
fcurve.driver.type = 'SCRIPTED'

var = fcurve.driver.variables.new()
var.name = 'src_x'
var.type = 'TRANSFORMS'
var.targets[0].id = source_obj
var.targets[0].transform_type = 'LOC_X'
var.targets[0].transform_space = 'WORLD_SPACE'

fcurve.driver.expression = 'src_x * 2.0'

Common variable types:

  • 'SINGLE_PROP': read any RNA property. Set targets[0].id = some_id and targets[0].data_path = 'some.path'. The target id pointer defaults to the OBJECT type; to point at a non-object datablock (a Scene, Material, etc.) set targets[0].id_type first, e.g. targets[0].id_type = 'SCENE', otherwise the id = assignment raises TypeError.
  • 'TRANSFORMS': read a transform channel. Set transform_type (LOC_X, ROT_Y, SCALE_Z, etc.).
  • 'ROTATION_DIFF': angle between two bones in radians.
  • 'LOC_DIFF': distance between two object locations.

The expression security model

Driver expressions run on every depsgraph evaluation. A SCRIPTED expression is one of two kinds, and they are trusted differently:

  1. Simple expressions always run. Blender evaluates the documented simple subset (arithmetic, comparisons, driver variables, frame, and whitelisted math such as sin, cos, sqrt, pi, radians, min, max) without Python, so they run even with script auto-execution off.
  2. Everything else needs Python auto-execution. That includes every call to a `bpy.app.driver_namespace` function and any attribute access such as bpy.context.scene.frame_current. Blender ships with auto-execution off (preferences.filepaths.use_scripts_auto_execute is False on a factory 4.5.11 and 5.2.1). A user who opens your .blend in a normal GUI session gets dead drivers unless they open it as Trusted Source, enable Preferences > Save & Load > Auto Run Python Scripts, or launch with --enable-autoexec / -y. See the manual's Drivers > Troubleshooting: a scripted expression outside the simple subset needs Trusted Source or Auto Run Python Scripts.

driver_namespace does not make a function safe or trusted. It only makes the name resolvable once Python is allowed to run. The gate is auto-execution.

Check which kind you wrote with driver.is_simple_expression. Measured on 4.5.11 and 5.2.1:

Expressionis_simple_expression
1.4 + sin(3 * 0.6), frame / 10, max(1, 2), 1.0True
wave_scale(0) (a driver_namespace function)False
bpy.context.scene.frame_currentFalse

Prefer simple expressions and driver variables when the `.blend` will be shared. Read data through variables (SINGLE_PROP, TRANSFORMS) and keep the expression in the simple subset. Reach for a namespace function only when the add-on that registers it will be installed wherever the file is opened, and tell the user the file needs Auto Run.

Headless tests cannot see this failure. --background runs still evaluated a reopened file's namespace driver (so a save-and-reopen check passes). Assert is_simple_expression instead of trusting a background evaluation.

The driver_namespace escape hatch

When a driver needs custom Python logic, register the function in bpy.app.driver_namespace:

python
import bpy
import math


def smooth_step(t):
    """Smoothstep easing: 3t^2 - 2t^3 on [0, 1]."""
    t = max(0.0, min(1.0, t))
    return t * t * (3.0 - 2.0 * t)


bpy.app.driver_namespace['smooth_step'] = smooth_step

fcurve = obj.driver_add("location", 2)
fcurve.driver.type = 'SCRIPTED'

var = fcurve.driver.variables.new()
var.name = 't'
var.type = 'SINGLE_PROP'
var.targets[0].id_type = 'SCENE'  # required before assigning a non-Object id
var.targets[0].id = bpy.context.scene
var.targets[0].data_path = 'frame_current'

fcurve.driver.expression = 'smooth_step((t - 1.0) / 100.0) * 5.0'

The function name in driver_namespace must match the call in the expression.

driver_namespace is reset on every file load. Registering only in register() works until the user opens a file: the drivers then evaluate with the function missing, raise NameError: name 'smooth_step' is not defined, and are disabled (driver.is_valid = False). They stay disabled even after the function is added back. Re-register from a @persistent load_post handler and re-enable the drivers there:

python
import bpy
from bpy.app.handlers import persistent


@persistent
def restore_driver_functions(_filepath=None):
    bpy.app.driver_namespace['smooth_step'] = smooth_step
    # Drivers that failed during load stay off until re-enabled.
    for ids in (bpy.data.objects, bpy.data.shape_keys, bpy.data.materials):
        for id_data in ids:
            anim = id_data.animation_data
            for fcurve in (anim.drivers if anim else ()):
                fcurve.driver.is_valid = True


def register():
    bpy.app.driver_namespace['smooth_step'] = smooth_step
    bpy.app.handlers.load_post.append(restore_driver_functions)


def unregister():
    if restore_driver_functions in bpy.app.handlers.load_post:
        bpy.app.handlers.load_post.remove(restore_driver_functions)
    bpy.app.driver_namespace.pop('smooth_step', None)

Extend the ID collections to wherever your add-on puts drivers (node groups, scenes, cameras). Measured on 4.5.11 and 5.2.1: without the handler, a saved and reopened file leaves the driver dead; with it, the driver evaluates again.

Removing drivers

python
obj.driver_remove("location", 0)
obj.driver_remove("location", -1)

The first form removes the driver on a specific channel. The second (with -1) removes drivers on all channels of a vector property.

Part 2: Application Handlers

What a handler is

A handler is a Python callable registered against a Blender event. When the event fires, every callable in the handler's list is called with a documented signature. Handlers run in registration order and exceptions in one do not stop the others (Blender catches and logs).

The handlers live as lists at bpy.app.handlers.<event>. To register, append; to unregister, remove.

Common handlers and their signatures

HandlerSignatureFires when
save_pre(filepath: str)Before the .blend is written. The argument is the file being saved (empty string for the startup file), not a Scene. Use to clean up data you don't want serialized.
save_post(filepath: str)After the .blend is written. Same single filepath argument.
load_pre(filepath: str)Before a .blend is loaded. The argument is the file being loaded.
load_post(filepath: str)After a .blend is loaded. Use to validate or migrate add-on data.
depsgraph_update_pre(scene, None)Before a depsgraph evaluation pass. The second argument is None, not a Depsgraph.
depsgraph_update_post(scene, depsgraph)After a depsgraph evaluation pass. Fires very frequently; must be O(1) or near-O(1).
frame_change_pre(scene, None)Before frame is set. The second argument is None; the depsgraph is not available yet.
frame_change_post(scene, depsgraph)After frame is set.
exit_pre (new in 5.1)(interactive: bool)Before Blender shuts down. Use for resource cleanup, telemetry flush, etc. The argument is True for an interactive (GUI) exit and False in --background. A handler written as (*args) receives (bool, None).

The save/load handlers (save_pre, save_post, load_pre, load_post) all receive the file path as a string as their single argument, not a Scene. (Verified empirically on 4.5.10 LTS and 5.1.1. The `bpy.app.handlers` docs type these as Callable[[str], None]; save_pre is described as "on saving a blend file (before). Accepts one argument: the file being saved, an empty string for the startup-file." — the load handlers use the same wording with "the file being loaded".) Only the _post depsgraph/frame-change handlers receive (scene, depsgraph). The _pre ones get (scene, None), so a handler that calls depsgraph.<anything> there raises AttributeError: 'NoneType' object has no attribute .... Measured on 4.5.11 and 5.2.1: frame_change_pre and depsgraph_update_pre get ['Scene', 'NoneType'], the _post variants ['Scene', 'Depsgraph']. If a pre handler truly needs evaluated data, call bpy.context.evaluated_depsgraph_get(), and not from inside a depsgraph handler, where it can trigger the evaluation the handler is part of. Usually the right fix is to move the work to the _post handler.

exit_pre was measured on 5.2.1: a --background exit passes False, a windowed wm.quit_blender() passes True.

The exit_pre handler in 5.1 is particularly useful for add-ons that need to release external resources (sockets, log files, child processes) deterministically before the process terminates.

The canonical handler pattern

python
import bpy
from bpy.app.handlers import persistent


@persistent
def on_save_pre(filepath):
    """Clear temporary cache data before save so it doesn't bloat the .blend.

    The handler argument is the path being saved (a string), not a Scene, so
    reach the scene(s) through bpy.data.
    """
    for scene in bpy.data.scenes:
        if 'my_addon_cache' in scene:
            del scene['my_addon_cache']


def register():
    bpy.app.handlers.save_pre.append(on_save_pre)


def unregister():
    if on_save_pre in bpy.app.handlers.save_pre:
        bpy.app.handlers.save_pre.remove(on_save_pre)

The @persistent decorator

By default, handlers are removed when a new .blend loads (so each file gets a clean handler list). Decorate with @persistent to keep your handler attached across file loads. This is what add-ons almost always want.

Performance contract

Handlers run on the main thread, synchronously, on every event. The user feels every millisecond. Rules:

  1. Make handlers fast or asynchronous. A 10ms handler on depsgraph_update_post slows playback noticeably.
  2. Guard against recursion. A depsgraph_update_post that modifies the scene re-triggers the handler. Use a module-level flag or bpy.app.handlers.depsgraph_update_post removal to break loops.
  3. Defend against missing data. Handlers run before your add-on may have fully initialized (load_post fires while UI is still rebuilding). Check membership before dereferencing.
  4. Always pair register/unregister. Forgetting to remove a handler on add-on disable leaves a zombie callback that fires forever.

Worked example: track save count per file

python
import bpy
from bpy.app.handlers import persistent


@persistent
def increment_save_count(filepath):
    # save_pre runs before the write, so the new count lands in the file being
    # saved (a save_post write would only reach the next save). It receives the
    # target path. ID-property keys are limited to 63 characters, so key by the
    # file name, never the full path, which raises KeyError when longer.
    scene = bpy.context.scene
    key = bpy.path.basename(filepath)[:63] or "untitled"
    counts = scene.get('save_counts', {})
    counts[key] = counts.get(key, 0) + 1
    scene['save_counts'] = counts


def register():
    bpy.app.handlers.save_pre.append(increment_save_count)


def unregister():
    if increment_save_count in bpy.app.handlers.save_pre:
        bpy.app.handlers.save_pre.remove(increment_save_count)

Worked example: cleanup on exit (5.1+)

python
import bpy
from bpy.app.handlers import persistent


@persistent
def cleanup_on_exit(*args):
    """Release the external log file handle before the process terminates.

    exit_pre's argument is unused here; accept *args to stay signature-proof.
    """
    global _log_handle
    if _log_handle is not None:
        _log_handle.close()
        _log_handle = None


def register():
    bpy.app.handlers.exit_pre.append(cleanup_on_exit)


def unregister():
    if cleanup_on_exit in bpy.app.handlers.exit_pre:
        bpy.app.handlers.exit_pre.remove(cleanup_on_exit)

The exit_pre handler list is new in Blender 5.1. On 4.5 LTS, fall back to OS-level atexit registration, which fires later and has fewer guarantees about access to bpy state.

Common AI mistakes

  • Calling Python functions in a driver expression without registering them. Hits the security block. Either rewrite as math, or register via bpy.app.driver_namespace.
  • Registering a driver function only in `register()`. driver_namespace is reset on file load, so the driver dies with NameError on the first file the user opens and stays disabled. Re-register and reset driver.is_valid from a @persistent load_post handler.
  • Forgetting `@persistent` on handlers. The handler vanishes on the next file load and the user thinks the add-on broke.
  • Doing real work inside `depsgraph_update_post`. This handler fires on every depsgraph evaluation, which is many times per second during playback or interaction. Anything more than O(1) bookkeeping causes user-visible slowdown.
  • Recursively modifying the scene from a depsgraph handler. The modification triggers another depsgraph evaluation, which calls the handler, which modifies the scene. Infinite loop, often manifesting as a hang.
  • Asymmetric register/unregister. The handler is appended on register but not removed on unregister. Disabling the add-on leaves the callback in place. After enable/disable cycles, the callback runs N times per event.
  • Treating the `save_pre` argument as a Scene. The save/load handlers receive the file path string (empty for the startup file), not a Scene. Name the parameter filepath (or take *args), and reach scenes via bpy.context.scene / bpy.data.scenes. A membership test like 'key' in arg0 against the path string is silently wrong, and del arg0['key'] raises TypeError.
  • Doing exit cleanup in the script body instead of `exit_pre`. A --background --python script can sys.exit(0) without the handler firing if you never registered it. The witness is a sidecar written from exit_pre, asserted after the process dies.

Version correctness

Topic4.5 LTS5.1 / 5.2 LTS
exit_pre handlerNot availableNew in 5.1; use atexit fallback for 4.x
save_pre / save_post signature(filepath) — a string(filepath) — a string (unchanged)
driver_namespaceAvailable; reset on file loadSame (re-register from load_post)
Driver securityAlready restrictiveSame

See also

  • Snippet driver-with-custom-function.py for the driver_namespace pattern.
  • Snippet app-handler-registration.py for save_pre with proper unregister.
  • Example exit-pre-sidecar for exit_pre writing a post-exit sidecar (5.1+; skip 4.5).
  • Skill custom-properties for the data the driver might be reading.

<!-- examples:begin (generated by scripts/buildexamplesindex.py from examples/skills.json; do not edit) -->

Runnable examples

Each example runs headless, asserts the contract, and exits non-zero when it breaks. Run one with blender --background --python <script> --; pass a falsifier flag to watch the check fail.

  • `driver-wave`: A driver_namespace function driving sixteen organ-pipe heights through SCRIPTED drivers — the sine skyline of the pipe tops is entirely driver-evaluated. Falsify: --flat-expr (exit 3).
  • `exit-pre-sidecar`: bpy.app.handlers.exit_pre writes $BDT_SMOKE_SIDECAR as Blender dies. Blender 5.1+. Falsify: --atexit-instead (harness fails the sidecar).

Snippets

Short standalone patterns to copy. Each one runs in CI on 5.2 and 4.5 with a check and a falsifier.

<!-- examples:end -->

References

  • bpy.app.handlers: https://docs.blender.org/api/current/bpy.app.handlers.html
  • bpy.types.Driver: https://docs.blender.org/api/current/bpy.types.Driver.html
  • bpy.types.FCurve.driver: https://docs.blender.org/api/current/bpy.types.FCurve.html
  • bpy.app.driver_namespace: https://docs.blender.org/api/current/bpy.app.html
  • Blender 5.1 release notes: https://developer.blender.org/docs/release_notes/5.1/
from this repository

More skills

All skills
tmhsdigital
Community

bake-high-to-low

Cage-bake high-poly surface detail onto a low-poly target as a tangent-space normal map with bpy.ops.object.bake (Cycles, selected-to-active, active Image Texture node, UV layer, saverender). Use when the user wants a normal map from a dense mesh onto a game-resolution or decimated LOD, mentions cageextrusion or useselectedtoactive, or gets a bake that returns CANCELLED, comes out black or flat, or fails with 'No active UV layer found'. Targets 5.2 LTS with 4.5 LTS fallback.

1h installs
1
GitHub stars
20
Updated
Nov 3
tmhsdigital
Community

bl-info-migration

Migrate a legacy blinfo add-on to the Extensions Platform in three steps, with a before/after diff and the dual-format pattern. Use when the user has a blinfo dictionary in init.py, asks whether blinfo is deprecated or still supported, wants to publish to extensions.blender.org or ship an extension .zip, or sees warnings about legacy add-ons at install time. Targets 5.2 LTS; manifests work from 4.2.

1h installs
1
GitHub stars
20
Updated
Nov 3
tmhsdigital
Community

engine-export-presets

Export presets for Unity, Godot and Unreal. glTF is +Y up and meters by spec, so every engine gets exportyup=True with no scale bake (Unreal converts to centimeters on import); FBX takes axisforward/axisup plus globalscale. Use when the user exports for a game engine, mentions exportyup, axisforward, axisup, globalscale, Y-up or centimeters, passes FBX axis kwargs to exportscene.gltf, or gets a model that imports lying on its back or 100x too large. Targets 5.2 LTS with 4.5 LTS fallback.

1h installs
1
GitHub stars
20
Updated
Nov 3