Blender Developer Tools

Skills, rules, snippets, and a starter template for Blender Python development

12 skills  •  6 rules  •  2 templates  •  17 snippets

Overview

This repository ships 12 skills, 6 rules, 2 templates, and 17 snippets 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.

Supported Blender versions

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.

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

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.