README.md

Blender Developer Tools

---

Skills, rules, snippets, templates, and runnable examples for Blender Python development

12 skills  •  6 rules  •  2 templates  •  17 snippets  •  12 examples

---

Overview

This repository ships 12 skills, 6 rules, 2 templates, 17 snippets, and 12 runnable examples for Blender Python development targeting Blender 5.1 (current stable) with Blender 4.5 LTS fallback support.

The content is consumed by AI coding agents (Cursor, Claude Code, any MCP-capable client) when working on Blender add-ons, geometry nodes scripts, batch pipelines, or animation tooling. There is no build step. Edit the markdown and Python files directly.

Layer	Role
Skills	Guided workflows: scaffolding, operators, panels, properties, mesh and bmesh, headless batch, slotted actions, geometry nodes, procedural materials, depsgraph queries, drivers and handlers, bl_info migration
Rules	Guardrails for the most common AI mistakes: ops-in-loops, bmesh leaks, legacy bl_info only, prop assignments, deprecated context-copy override, per-element loops over bulk mesh data
Templates	A working Extensions Platform add-on starter and a headless batch script starter
Snippets	17 small standalone Python files demonstrating canonical patterns

Supported Blender versions

Version	Status
Blender 5.1.x	Primary target (all examples assume 5.1)
Blender 4.5 LTS	Fallback supported (skills show both code paths where 4.x and 5.x APIs diverge)
Blender 5.2 LTS	Sweep planned for July 2026 (see ROADMAP.md)

Examples

Runnable, smoke-gated demos live in examples/ — each is executed headless on both Blender 4.5 LTS and 5.1 by the blender-smoke workflow, so the screenshots reflect code that actually runs. Browse them in the examples gallery.

	swatch-grid A procedural-materials swatch grid — Principled metal and dielectric, the emission pattern, and the cross-version set_specular shim. Doubles as a live proof of the EEVEE engine-id mapping (BLENDER_EEVEE on 5.x, BLENDER_EEVEE_NEXT on 4.2-4.5).
	turntable A slotted-actions Z-rotation turntable keyed through the cross-version channelbag path (get_channelbag_for_slot). Witnesses the slotted-actions fix: ensure-helper channelbag on 5.x, strip.channelbag on 4.4/4.5.
	gn-sdf-remesh A Geometry Nodes SDF remesh (MeshToSDFGrid → GridToMesh at the SDF zero-level). Witnesses the fix that an SDF grid is meshed with Grid to Mesh, not Volume to Mesh, and that a Set Material node carries the material through the remesh.
	depsgraph-export A depsgraph-evaluated export — builds a cube with SUBSURF, measures the evaluated mesh via evaluated_get().to_mesh() / to_mesh_clear(), and asserts wm.obj_export ships the modifier-applied geometry (exported vertex count == evaluated > base).
	wave-displace Bulk vertex IO at real scale — 9,409 vertices displaced into a standing wave with one foreach_get and one foreach_set, no per-vertex access. Asserts the count is unchanged, the Z span matches the amplitude, and a probe vertex matches the closed-form wave.
	driver-wave A driver_namespace function driving sixteen column heights through SCRIPTED drivers. Witnesses the evaluation contract: driven values appear after a view-layer update on the evaluated copy and the flushed-back original, and both must match the closed form.
	bmesh-gear A 14-tooth gear built entirely with bmesh — with bm.free() in a try/finally, as the ownership contract demands. Asserts the closed-form vert/edge/face counts and that the result is watertight (every edge borders exactly two faces).
	shader-node-group One reusable TintedGloss group declared via tree.interface.new_socket, instanced in two materials with different Tint values. Witnesses the grouping contract: shared datablock (users == 2), parameters on the group node — two spheres, one group, two colors.
	temp-override-join Three unit cubes joined into a staircase under bpy.context.temp_override — the supported replacement for the removed context.copy() dict-pass form. Asserts one mesh remains, sources are gone, and local Z spans all three steps.
	gn-instance-grid A generative Geometry Nodes tree — Mesh Grid → Instance on Points → Realize Instances — attached as a NODES modifier with no Group Input. Asserts evaluated topology is verts = 72, faces = 54, and Set Material carries the lime accent.
	shape-key-blend A relative Tall shape key that lifts and flares the top face — authored through shape_key_add / key_blocks / .value. Witnesses that shape keys do not rewrite mesh.vertices: every evaluated vert matches basis + value × (key − basis).
	curve-bevel-arc A beveled Bezier semicircle authored on bpy.types.Curve — splines.new('BEZIER'), bezier_points, bevel_depth, use_fill_caps — so the curve renders as a solid tube without a prior mesh conversion. Asserts eight points, bevel_depth == 0.15, and evaluated topology 1044 verts / 1028 faces.

How content is organized

skills/<name>/SKILL.md   - 12 skill files, YAML frontmatter, one canonical pattern each
rules/<name>.mdc         - 6 rule files, anti-pattern + correction
templates/<name>/        - 2 template directories (extension-addon-template, headless-batch-script-template)
snippets/<name>.py       - 17 standalone Python snippets, 5 to 50 lines each

Using rules in Cursor

The .mdc files in rules/ apply automatically when Cursor opens a Blender Python project, scoped by the globs in each rule's frontmatter. The six rules are:

• prefer-data-over-ops-in-loops: flags bpy.ops.* calls inside object iteration
• always-free-bmesh: flags bmesh.new() without paired bm.free() in try/finally
• target-extensions-platform-format: flags add-ons missing blender_manifest.toml
• type-annotate-props-and-defend-context: flags bpy.props assignment form and unguarded context.active_object
• prefer-temp-override-over-context-copy: flags bpy.context.copy() passed to operators (deprecated 4.x, removed 5.x)
• use-foreach-set-for-bulk-data: flags Python loops over mesh.vertices setting co, normals, or other per-element bulk data

Symlink or clone this repo, then point Cursor at it as a skills/rules source.

Using the templates

templates/extension-addon-template/ is a working Blender extension. Copy the directory, edit blender_manifest.toml (id, version, name, maintainer), and install via Edit > Preferences > Get Extensions > Install From Disk. The template registers an Operator, a Panel, and a PropertyGroup, and demonstrates the register_classes_factory pattern with symmetric register() and unregister().

templates/headless-batch-script-template/ is a working starter for unattended Blender batch jobs. It opens a .blend, optionally adds and applies a modifier to every mesh, and exports to glTF, with explicit exit codes for CI integration. Run with blender --background <input.blend> --python script.py -- --output ....

Snippets

Each snippet is a standalone Python file under snippets/. They are not loaded as a package. Open one, copy the relevant lines into your script, and adapt the names. Each file's header comment cites the Blender doc URL or research section the pattern came from.

Canonical references

Resource	Use it for
Blender 5.1 Python API	Authoritative reference for current stable APIs
Blender 4.5 LTS Python API	LTS reference when targeting 4.5
Extensions Platform manual	blender_manifest.toml schema, hosting, install flow
developer.blender.org	Release notes, breaking change tracking, design docs

When community content (Stack Overflow, older add-on source) conflicts with the official docs, prefer the docs. The 2.x to 4.x to 5.x churn around Actions, Extensions, and property handling has invalidated a lot of older material.

Roadmap

See ROADMAP.md. v0.2.0 shipped procedural materials, depsgraph queries, drivers and app handlers, bl_info to manifest migration, two new rules, and the headless batch script template. v0.3.0 candidates include modal operators, USD pipelines, and mathutils patterns.

License

Copyright (c) 2026 TM Hospitality Strategies. Licensed under CC-BY-NC-ND-4.0.