https://github.com/tmhsdigital/blender-developer-tools
Skills, rules, snippets, and a starter template for Blender Python development. 8 skills, 4 rules, 1 template, 10 snippets targeting Blender 5.1 with 4.5 LTS fallback.
https://github.com/tmhsdigital/blender-developer-tools
ai-coding-agents blender blender-addon blender-python bmesh bpy claude-code cursor developer-tools extensions-platform geometry-nodes python
Last synced: 10 days ago
JSON representation
Skills, rules, snippets, and a starter template for Blender Python development. 8 skills, 4 rules, 1 template, 10 snippets targeting Blender 5.1 with 4.5 LTS fallback.
- Host: GitHub
- URL: https://github.com/tmhsdigital/blender-developer-tools
- Owner: TMHSDigital
- License: other
- Created: 2026-04-26T14:26:22.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-06-20T22:08:56.000Z (20 days ago)
- Last Synced: 2026-06-21T00:07:49.124Z (20 days ago)
- Topics: ai-coding-agents, blender, blender-addon, blender-python, bmesh, bpy, claude-code, cursor, developer-tools, extensions-platform, geometry-nodes, python
- Language: Python
- Homepage: https://tmhsdigital.github.io/Blender-Developer-Tools/
- Size: 288 KB
- Stars: 3
- Watchers: 0
- Forks: 1
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Roadmap: ROADMAP.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
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.
| 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](ROADMAP.md)) |
## Examples
Runnable, smoke-gated demos live in [`examples/`](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](https://tmhsdigital.github.io/Blender-Developer-Tools/gallery/)**.
### [swatch-grid](examples/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](examples/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](examples/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](examples/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).
## How content is organized
```
skills//SKILL.md - 12 skill files, YAML frontmatter, one canonical pattern each
rules/.mdc - 6 rule files, anti-pattern + correction
templates// - 2 template directories (extension-addon-template, headless-batch-script-template)
snippets/.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 --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](https://docs.blender.org/api/current/) | Authoritative reference for current stable APIs |
| [Blender 4.5 LTS Python API](https://docs.blender.org/api/4.5/) | LTS reference when targeting 4.5 |
| [Extensions Platform manual](https://docs.blender.org/manual/en/latest/advanced/extensions/index.html) | `blender_manifest.toml` schema, hosting, install flow |
| [developer.blender.org](https://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](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](LICENSE).