Como usar
- Copie o comando e verifique o pacote antes de instalar no seu ambiente de agente.
- Consulte no original as ferramentas, credenciais e ambientes necessários.
- Descreva os dados de entrada e a entrega esperada; confira a saída com as fontes.
npx skills add https://github.com/tmhsdigital/blender-developer-tools --skill drivers-and-app-handlersAntes de começar
- A instalação não inclui assinatura de modelo, franquia API ou acesso aos seus arquivos.
- Estrelas e instalações indicam atividade, não um teste independente de qualidade ou segurança.
Renderizado do repositório de origem, preservando títulos, exemplos, código, tabelas, links e imagens.
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
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 fcurvedriver_add(data_path, index):
data_pathis the RNA path of the property, like"location"or"scale". A user custom (ID) property set withobj["my_custom_prop"] = 1.0is'["my_custom_prop"]'; a registeredbpy.propsproperty is its plain name,"my_prop". On 5.0+'["my_prop"]'no longer resolves a registered property (ValueError), though it did on 4.x.indexis the array index for vector or color properties (0 = X, 1 = Y, 2 = Z), or-1for scalar properties.- Returns the
FCurvewhose.driveris 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.
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. Settargets[0].id = some_idandtargets[0].data_path = 'some.path'. The target id pointer defaults to theOBJECTtype; to point at a non-object datablock (a Scene, Material, etc.) settargets[0].id_typefirst, e.g.targets[0].id_type = 'SCENE', otherwise theid =assignment raisesTypeError.'TRANSFORMS': read a transform channel. Settransform_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:
- Simple expressions always run. Blender evaluates the documented simple subset (arithmetic, comparisons, driver variables,
frame, and whitelisted math such assin,cos,sqrt,pi,radians,min,max) without Python, so they run even with script auto-execution off. - 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_executeisFalseon a factory 4.5.11 and 5.2.1). A user who opens your.blendin 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:
| Expression | is_simple_expression |
|---|---|
1.4 + sin(3 * 0.6), frame / 10, max(1, 2), 1.0 | True |
wave_scale(0) (a driver_namespace function) | False |
bpy.context.scene.frame_current | False |
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:
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:
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
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
| Handler | Signature | Fires 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
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:
- Make handlers fast or asynchronous. A 10ms handler on
depsgraph_update_postslows playback noticeably. - Guard against recursion. A
depsgraph_update_postthat modifies the scene re-triggers the handler. Use a module-level flag orbpy.app.handlers.depsgraph_update_postremoval to break loops. - 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.
- 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
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+)
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_namespaceis reset on file load, so the driver dies withNameErroron the first file the user opens and stays disabled. Re-register and resetdriver.is_validfrom a@persistentload_posthandler. - 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 viabpy.context.scene/bpy.data.scenes. A membership test like'key' in arg0against the path string is silently wrong, anddel arg0['key']raisesTypeError. - Doing exit cleanup in the script body instead of `exit_pre`. A
--background --pythonscript cansys.exit(0)without the handler firing if you never registered it. The witness is a sidecar written fromexit_pre, asserted after the process dies.
Version correctness
| Topic | 4.5 LTS | 5.1 / 5.2 LTS |
|---|---|---|
exit_pre handler | Not available | New in 5.1; use atexit fallback for 4.x |
save_pre / save_post signature | (filepath) — a string | (filepath) — a string (unchanged) |
driver_namespace | Available; reset on file load | Same (re-register from load_post) |
| Driver security | Already restrictive | Same |
See also
- Snippet
driver-with-custom-function.pyfor the driver_namespace pattern. - Snippet
app-handler-registration.pyfor save_pre with proper unregister. - Example
exit-pre-sidecarforexit_prewriting a post-exit sidecar (5.1+; skip 4.5). - Skill
custom-propertiesfor 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_prewrites$BDT_SMOKE_SIDECARas 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.htmlbpy.types.Driver: https://docs.blender.org/api/current/bpy.types.Driver.htmlbpy.types.FCurve.driver: https://docs.blender.org/api/current/bpy.types.FCurve.htmlbpy.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/