Every render here is code that runs.
These aren't mockups. Each example runs headless on Blender 5.2 LTS and 4.5 LTS in the smoke workflow, asserts its own correctness, and exits non-zero if the API drifted. Each still was rendered by that same script.
69 examples: 56 rendered · 13 check-only (data contracts with nothing to see). List the check-only examples
Install it in your agent.
- Claude Code:
/plugin marketplace add TMHSDigital/Blender-Developer-Tools@plugin-distthen/plugin install blender-developer-tools@blender-developer-tools. The 26 skills load when a task matches; the rules come along as theblender-rulesskill - Cursor:
git clone --branch plugin-dist --single-branch https://github.com/TMHSDigital/Blender-Developer-Tools.git ~/.cursor/plugins/local/blender-developer-tools, then reload the window; Customize lists the 26 skills and 16 rules, and the plugin applies the rules for you. This clones only the 0.3 MB plugin build, notmain - Other agents (Codex, Copilot, Windsurf): clone the same slim build (
git clone --branch plugin-dist --single-branch https://github.com/TMHSDigital/Blender-Developer-Tools.git) and copy itsskills/*into.agents/skills/, appendexports/AGENTS.mdto your project'sAGENTS.mdfor the rules, and for Copilot copyexports/copilot/blender-python.instructions.mdinto.github/instructions/ - Optional, live session:
/plugin install blender-live-session@blender-developer-toolsadds the official Blender Lab MCP server (needsuvand Blender 5.1+ with its add-on) so the agent can inspect and drive your open scene, plus a skill that has it read before it mutates and prove changes headless. See the README's Live Blender session - Grab
snippets/andtemplates/as starting points for add-ons and headless batch jobs
Budget-conformance props, not API contracts.
Showcase pieces compose shipped skills into a recognizable asset and assert declared budgets — triangle counts, materials, UVs, LODs, colliders, exports. They are not examples. A still that merely rendered is not an assertion.
Recently shipped.
Latest release v0.159.0 · 2026-11-03 Release notes → Changelog →
render.engine = 'BLENDER_EEVEE_NEXT' or = 'BLENDER_EEVEE' written without a version branch.
rules/no-legacy-action-fcurves.mdcFlag action.fcurves, action.groups and action.id_root on an Action.
rules/no-nodes-modifier-idprop-inputs.mdcFlag writing a Geometry Nodes modifier input as an ID property (mod["Socket_2"] = value, mod[identifier] = value) without a version branch.
rules/principled-v2-socket-names.mdcFlag Principled BSDF inputs looked up by their 3.x names (inputs["Emission"], ["Specular"], ["Clearcoat"], ["Subsurface"]…
skills/compositor-nodesBuild and render through the scene compositor from Python across the 4.5 LTS to 5.x split: scene.use_nodes plus scene.node_tree and a Composite node…
Workflows the AI loads by name.
Each skill is the canonical pattern for one job — operators, panels, bmesh, geometry nodes, slotted actions — plus the mistakes AI assistants actually make there. Where 4.5 LTS and 5.x diverge, both code paths are shown.
When to use (4)
- Wants to start a new Blender add-on
- Mentions
bl_info,blender_manifest.toml, "extension", "register_classes_factory" - Is migrating an existing add-on from the legacy
bl_infoformat to the Extensions Platform - Is unsure which file layout or registration pattern to use for Blender 4.5+ or 5.x
When to use (4)
- Has a generated or scanned GLB/glTF/FBX that is not engine-ready
- Mentions unit scale, unapplied transforms, triangle budget, LOD, or a collision hull
- Wants a headless cleanup pass (import in, cleaned mesh out)
- Is about to run mesh operators on an import without checking scale
When to use (4)
- Wants a tangent-space normal map from a dense source onto a game-resolution mesh
- Mentions cage bake,
use_selected_to_active,cage_extrusion, orbpy.ops.object.bake - Has an LOD from
DECIMATE COLLAPSE(or a retopo) and needs the missing surface detail in a map - Is about to call bake from EEVEE, on GPU in CI, or with
bake_type=
When to use (5)
- Has an existing add-on with a
bl_info = {...}dictionary at the top of__init__.py - Wants to publish to extensions.blender.org or distribute as a
.zipfor the Extensions Platform - Asks "is bl_info dead?" or "do I have to migrate?"
- Sees a deprecation warning at install time about legacy add-ons
- Mentions
blender_manifest.toml, "Install legacy Add-on", or "the new extension system"
When to use (5)
- Builds, edits or inspects compositor nodes from a script
- Mentions
scene.node_tree,scene.use_nodes,compositing_node_group,CompositorNodeTree,CompositorNodeGlare,CompositorNodeRLayers, orCompositorNodeComposite - Hits
AttributeErroronscene.node_treeafter moving to 5.x - Sets
glare.glare_type/glare.quality/glare.sizeon 5.x and getsAttributeError - Wants bloom and reaches for
scene.eevee.use_bloom(removed in 4.2, absent on 4.5 and 5.x)
When to use (6)
- Parents objects from Python with
child.parent = ...and the child jumps - Mentions
matrix_parent_inverse,matrix_world,matrix_basis, ormatrix_local - Reads
matrix_worldright after editinglocation/rotation_eulerand gets old numbers - Adds constraints (
DAMPED_TRACK,TRACK_TO) or callsbpy.ops.object.constraint_addin a loop - Builds named socket empties (
SKT_*) that a game engine or spawn system attaches modules to - Freezes a rig with
transform_applyand the children's local transforms change
When to use (5)
- Creates a curve or 3D text object from a script (
bpy.data.curves.new,type='CURVE'ortype='FONT') - Mentions
splines,bezier_points,bevel_depth,bevel_resolution,use_fill_caps,extrude,TextCurve,body,align_x, or Bfont - Needs the vertex positions, bounds or face count of a beveled curve or extruded text
- Reports that a tube renders as a hollow pipe, or that text dimensions do not match the numbers they set
- Hits
ReferenceErrorreading a mesh afterto_mesh_clear()
When to use (4)
- Wants to attach data to objects, scenes, or other Blender datablocks that survives save and load
- Mentions
bpy.props,PropertyGroup,PointerProperty, "custom properties" - Is unsure where to store add-on settings
- Sees a deprecation warning about property assignment
When to use (5)
- Is writing an exporter, measurement script, or inspection tool
- Reports that "modifiers are missing from my export" or "the vertex positions don't match what I see"
- Mentions
evaluated_depsgraph_get,evaluated_get,to_mesh,to_mesh_clear - Reads from
obj.data.verticesand gets unexpectedly raw geometry - Needs final positions after armature deformation, shape keys, modifiers, or geometry nodes
When to use (5)
- 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
When to use (4)
- Needs a Unity, Godot, or Unreal export from Blender Python
- Mentions Y-up, Z-up, centimeter scale,
export_yup,axis_forward, oraxis_up - Is about to pass FBX axis kwargs to
bpy.ops.export_scene.gltf - Wants a headless preset the later
ai-asset-pipeline-templatecan call
When to use (5)
- Needs a third-party Python package inside an extension (
requests,numpy,Pillow) - Writes settings, caches or downloads from an add-on and asks where they should go
- Makes network calls from an add-on, or asks about the
networkpermission - Builds, validates or publishes extension zips, locally or in CI
- Hits
ValueError: The "package" does not name an extension, or imports that work in a folder add-on but break once installed as an extension
When to use (4)
- Wants to build a Geometry Nodes tree from a script rather than the editor
- Mentions
GeometryNodeTree,node_groups.new,tree.interface,tree.links.new - Needs to apply a generated GN tree as a modifier on an object
- Asks about Bundles, Repeat Zones, or for-each Element zones from Python
When to use (4)
- Wants to draw lines, points, shapes or text over the 3D viewport or an image editor from an add-on
- Has add-on code with
import bgl,bgl.glEnable,bgl.glLineWidth, or getsModuleNotFoundError: No module named 'bgl'on 5.x - Wants to render something with the GPU into an image from a script, including headless
- Sees
SystemError: GPU functions for drawing are not available in background mode
When to use (5)
- Creates Grease Pencil objects, layers, frames, or strokes from a script
- Mentions
grease_pencils,grease_pencils_v3,GreasePencil,GPencilStroke,drawing,add_strokes, or theLINEARTmodifier - Ports pre-4.3 GPencil code (frames that carry
.strokesdirectly) to 4.5 LTS or 5.x - Hits
AttributeErroronbpy.data.grease_pencils_v3(5.x), onframe.drawing(legacy data on 4.5), or on the Line Art modifier'sthickness(5.x) - Gets zero Line Art strokes and does not know why
When to use (4)
- Wants to render, export, or process .blend files from a CLI or CI pipeline
- Mentions
blender --background,--python, "headless", "batch render", "no UI" - Has an operator script that fails with
RuntimeError: Operator bpy.ops.X.Y.poll() failed, context is incorrect - Needs to pass arguments to a Blender Python script
When to use (5)
- Creates an image with
bpy.data.images.newand fills it from code (test cards, masks, lookup textures, bake targets) - Reads or writes
Image.pixels, or mentionsforeach_get/foreach_set,float_buffer,is_float,channels - Hits
TypeErrorfrompixels.foreach_set/foreach_get(wrong length: RGB stride, or a buffer sized beforeImage.scale()) - Sees an image land upside down in the saved file, or pixels that changed after
Image.save() - Saves PNG or OpenEXR and loses alpha, gets low-alpha pixels clamped to white, or finds
save_renderwrote a PNG despiteimage.file_format = "OPEN_EXR"
When to use (6)
- Wants to create, modify, or read mesh geometry from Python
- Mentions
bmesh,mesh.vertices,foreach_set,from_pydata,evaluated_get - Has a script that's slow and uses
bpy.ops.mesh.*in a loop - Needs the mesh after modifiers (subdivision surface, mirror, geometry nodes) have been applied
- Asks why their bmesh script crashes on the second run
- Reads or writes sculpt automasking (
use_automasking_*,mesh_automasking_settings) and hitsAttributeErroron 5.2
When to use (4)
- Wants to create a new
bpy.types.Operator - Mentions
bl_idname,bl_label,bl_options, "redo panel", "F6 panel", "operator props" - Needs an action triggered from a button, menu, keymap, or chat command
- Asks why their operator's properties don't show up in the redo panel
When to use (3)
- Asks to "port", "upgrade", "update" or "make compatible" an add-on or script for Blender 5.x
- Gets
AttributeError,KeyError,TypeErrororModuleNotFoundErrorfrom code that worked on an older Blender - Wants one codebase that runs on both 4.5 LTS and 5.2 LTS
When to use (6)
- Wants to create or edit materials from Python rather than the shader editor
- Mentions
bpy.data.materials,node_tree,ShaderNodeBsdfPrincipled,inputs[...].default_value - Needs to generate many materials parametrically (asset libraries, batch import, color variations)
- Asks about EEVEE Next vs Cycles material differences
- Restricts which objects a light illuminates (light linking,
receiver_collection,blocker_collection) - Asks about "Layered Textures" or "the new shader system" (see version-correctness section)
When to use (4)
- Wants to create or edit animation from Python in Blender 5.x
- Mentions
Action,slot,channelbag,keyframe_insert,fcurves - Has older 4.x animation code (
action.fcurves.new(...)) that no longer works in 5.x - Asks how to insert keyframes programmatically and have them persist
When to use (6)
- Wants something to happen later or repeatedly (polling, autosave, a progress readout)
- Runs slow work (network, file processing, a solver) and the UI freezes
- Calls
bpyfrom athreading.Threadand gets crashes or corrupted data - Writes a modal operator, or one that never stops
- Registers a timer in
blender --backgroundand it never runs - Loses a timer after File → Open or
wm.read_homefile
When to use (4)
- Wants a sidebar tab in the 3D viewport, properties editor, or any other space
- Mentions
bpy.types.Panel,bl_space_type,bl_region_type, "N panel", "sidebar" - Needs to expose properties or operators in a custom UI
- Asks why a property is showing without a label or in the wrong column
When to use (7)
- Creates or edits UVs from a script (
mesh.uv_layers,bm.loops.layers.uv,calc_uvs=True) - Builds a second UV channel for baked lighting, or runs
uv.lightmap_pack/uv.smart_projecton it - Computes tangents for a normal-mapped game asset (
calc_tangents,bitangent_sign) - Writes vertex colors (
color_attributes, the deprecatedvertex_colors) - Authors shape keys or reads a blended shape
- Caps skin weights at four influences per vertex for a game engine
- Reports a textured mesh that renders as one flat color, a UV op that wrecked channel 0, a crash or garbage values after
calc_tangents, or weights that sum short of one
When to use (5)
- Builds or inspects a VSE / sequencer timeline from a script
- Mentions
sequence_editor,strips,sequences,new_effect, COLOR strips, orStripTransform - Hits
AttributeError: 'SequenceEditor' object has no attribute 'sequences'on 5.x - Hits
TypeErroronnew_effectkwargs (frame_endvslength) - Renders a sequencer composite whose COLOR cells ignore
transform.scale_*after a resolution change
No skill matches that filter.
Anti-patterns, caught before they ship.
Guardrails that load whenever a matching file is open, for the failure modes that make Blender Python look right and run wrong: ops in loops, leaked bmesh, deprecated context dicts, per-vertex Python loops.
| Rule | Scope | Flags |
|---|---|---|
| always-free-bmesh | **/*.py | Flag bmesh.new() calls without a paired bm.free() in a try/finally block. Blender frees an unreferenced BMesh only when its Python wrapper dies, which a traceback, global, closure or modal operator can delay for the whole session; an explicit free() in finally releases it deterministically. |
| branch-eevee-engine-id | **/*.py | Flag render.engine = 'BLENDER_EEVEE_NEXT' or = 'BLENDER_EEVEE' written without a version branch. EEVEE Next used the id 'BLENDER_EEVEE_NEXT' on 4.2 through 4.5 LTS and took back 'BLENDER_EEVEE' in 5.0; each id raises TypeError (enum not found) on the other side. Branch on bpy.app.version >= (5, 0, 0). |
| no-bgl | **/*.py | Flag import bgl and any bgl. call. The bgl OpenGL wrapper was deprecated in 3.x and is gone in Blender 5.x (importlib.util.find_spec('bgl') is None on 5.0, 5.1 and 5.2), so an add-on that imports it fails to register. Draw with the gpu module, gpu.state and gpu_extras.batch instead; see the gpu-drawing-and-overlays skill. |
| no-legacy-action-fcurves | **/*.py | Flag action.fcurves, action.groups and action.id_root on an Action. Blender 5.0 removed the flat legacy Action API (AttributeError on 5.x); F-curves live in a channelbag per slot. On 4.4/4.5 LTS the legacy path still runs but is a trap on a fresh Action (it creates a slot without binding it). |
| no-legacy-vse-sequences | **/*.py | Flag sequence_editor.sequences and .sequences_all. Both are gone in Blender 5.x (AttributeError on 5.0, 5.1 and 5.2), while .strips and .strips_all already exist on 4.5 LTS, so use those everywhere with no version branch. See the vse-python skill. |
| no-nodes-modifier-idprop-inputs | **/*.py | Flag writing a Geometry Nodes modifier input as an ID property (mod["Socket_2"] = value, mod[identifier] = value) without a version branch. |
| no-removed-normals-api | **/*.py | Flag the mesh normals API removed in Blender 4.1 — use_auto_smooth, auto_smooth_angle, calc_normals_split(), free_normals_split(), create_normals_split(). Each raises AttributeError on 4.5 LTS and 5.x. Use Mesh.set_sharp_from_angle, object.shade_auto_smooth, and Mesh.corner_normals (always current) instead. |
| no-unapplied-modifiers-on-export | **/*.py | Flag an export call on objects that still carry unapplied modifiers when the export arguments do not request evaluated geometry. The engine then receives the authored cage, not the modifier result. |
| prefer-data-over-ops-in-loops | **/*.py | Flag bpy.ops.* calls inside iteration over many objects, meshes, or frames. Each bpy.ops call triggers a full depsgraph evaluation and UI redraw; loops slow down by orders of magnitude. Use bpy.data.* and bmesh instead. |
| prefer-temp-override-over-context-copy | **/*.py | Flag uses of bpy.context.copy() to override context for an operator call. Passing a context dict to an operator was deprecated in Blender 3.2 and removed in 4.0, so it already fails on the 4.5 LTS fallback. Use bpy.context.temp_override(**overrides) as a context manager instead. |
| principled-v2-socket-names | **/*.py | Flag Principled BSDF inputs looked up by their 3.x names (inputs["Emission"], ["Specular"], ["Clearcoat"], ["Subsurface"], ["Transmission"], ["Sheen"]) or by index. Principled v2 (Blender 4.0) renamed them, so they raise KeyError on 4.5 LTS and 5.x. |
| target-extensions-platform-format | **/__init__.py, **/blender_manifest.toml | Flag new Blender add-ons that ship only a legacy bl_info dict without a blender_manifest.toml. New add-ons must use the Extensions Platform format. bl_info may appear alongside as a fallback for backward compatibility, but the manifest is the source of truth. |
| type-annotate-props-and-defend-context | **/*.py | Flag two related anti-patterns. (1) bpy.props defined as class-level assignments instead of type annotations (deprecated since 2.8). (2) Code that touches bpy.context.active_object without guarding for None, or that assumes the active object is selected. |
| use-correct-axis-rna-per-exporter | **/*.py | Flag export_scene.gltf calls that pass FBX axis_forward or axis_up, and export_scene.fbx calls that pass glTF export_yup. The two exporters do not share axis RNA. |
| use-foreach-set-for-bulk-data | **/*.py | Flag Python loops that set vertex coordinates, normals, UVs, or other bulk per-element data one element at a time. For meshes of more than a few thousand elements, this is 100x to 1000x slower than mesh.vertices.foreach_set("co", flat_array), which writes through to C-level storage in one pass. |
| validate-imported-mesh-scale | **/*.py | Flag a glTF or FBX import followed by mesh operations with no transform_apply and no unit-scale check. Generated files often arrive with non-identity object scale or a non-meter scene scale; mesh edits then bake the wrong size. |
No rule matches that filter.
Canonical patterns, five to seventy-five lines.
Standalone, paste-ready answers to the questions that come up every session: the right way to create and delete objects, read bulk vertex data, bind properties, bridge the 4.x/5.x API boundary.
Plus 3 starter templates: ai-asset-pipeline-template, extension-addon-template, and headless-batch-script-template.