Skip to content

Commit 5a05f16

Browse files
committed
feat: v0.2.0 content expansion, 4 skills, 2 rules, 1 template, 7 snippets
New skills covering procedural materials and shaders (Principled BSDF node tree construction, EEVEE Next stabilization, the Layered Textures roadmap deferral), depsgraph queries for evaluated geometry (the evaluated_get plus to_mesh plus to_mesh_clear lifetime contract), drivers and application handlers (driver_namespace escape hatch, @Persistent decorator, the new exit_pre handler in 5.1), and migration from legacy bl_info to the Extensions Platform (three concrete steps, dual-format pattern). New rules encoding two more common AI anti-patterns: prefer-temp-override-over-context-copy (the bpy.context.copy() pattern was deprecated in 4.x and the override semantics removed in 5.x) and use-foreach-set-for-bulk-data (per-element Python loops over mesh attributes versus the orders-of-magnitude faster foreach_set buffer write). New template: headless-batch-script-template with a complete working script that opens a .blend, applies a modifier to every mesh via temp_override, exports to glTF, and returns explicit exit codes for CI integration. Snippets covering Principled BSDF setup, driver custom functions via driver_namespace, app handler registration with @Persistent, shader node groups with the cross-version interface API, foreach_get bulk reads into numpy buffers, the canonical version-branching skeleton, and USD export with evaluation_mode='RENDER'. Audit pass on existing v0.1.0 content: bumped standards-version markers from 1.9.1 to 1.9.4 across all 8 skills, all 4 rules, AGENTS.md, CLAUDE.md, and ROADMAP.md to align with the meta-repo VERSION. Verified the bpy_extras.anim_utils.action_ensure_channelbag_for_slot import path against the current Blender 5.1 API reference and removed the stale "verify before production" caveat in slotted-actions-animation. No substantive content rewrites needed; existing content is consistent with the rules in the same repo. Aggregate counts updated: 12 skills, 6 rules, 2 templates, 17 snippets. Made-with: Cursor
1 parent 9642cc6 commit 5a05f16

31 files changed

Lines changed: 1674 additions & 80 deletions

File tree

AGENTS.md

Lines changed: 23 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- standards-version: 1.9.1 -->
1+
<!-- standards-version: 1.9.4 -->
22

33
# AGENTS.md
44

@@ -12,31 +12,34 @@ fallback. There is no MCP server and no `.cursor-plugin/plugin.json`. This is
1212
content the AI loads when the user asks Blender questions or works on Blender
1313
add-ons in Cursor or Claude Code.
1414

15-
The content base for v0.1.0:
15+
The content base as of v0.2.0:
1616

17-
- 8 skills covering scaffolding, operators, panels, properties, mesh and
18-
bmesh, headless batch scripts, slotted-actions animation (5.x), and
19-
programmatic geometry nodes.
20-
- 4 rules encoding the most common AI anti-patterns when writing Blender
21-
Python.
22-
- 1 template (`extension-addon-template`) demonstrating the Extensions
23-
Platform format with `register_classes_factory` and a `PointerProperty`
24-
binding.
25-
- 10 snippets covering canonical patterns from the research document.
17+
- 12 skills covering scaffolding, operators, panels, properties, mesh and
18+
bmesh, headless batch scripts, slotted-actions animation (5.x), programmatic
19+
geometry nodes, procedural materials and shaders, depsgraph and evaluated
20+
data, drivers and application handlers, and `bl_info` to Extensions
21+
Platform migration.
22+
- 6 rules encoding the most common AI anti-patterns when writing Blender
23+
Python (ops-in-loops, bmesh leaks, legacy `bl_info`-only, prop assignment,
24+
deprecated context-copy override, per-element loops over bulk mesh data).
25+
- 2 templates: `extension-addon-template` for Extensions Platform add-ons,
26+
and `headless-batch-script-template` for unattended batch jobs.
27+
- 17 snippets covering canonical patterns.
2628

2729
## Repository structure
2830

2931
```
3032
Blender-Developer-Tools/
31-
skills/<skill-name>/SKILL.md # 8 skill files
32-
rules/<rule-name>.mdc # 4 rule files
33-
templates/<template-name>/ # 1 starter template
34-
snippets/<snippet-name>.py # 10 standalone Python snippets
33+
skills/<skill-name>/SKILL.md # 12 skill files
34+
rules/<rule-name>.mdc # 6 rule files
35+
templates/<template-name>/ # 2 starter templates
36+
snippets/<snippet-name>.py # 17 standalone Python snippets
3537
.github/workflows/ # validate, drift-check, release, label-sync
3638
.github/dependabot.yml
3739
AGENTS.md, CLAUDE.md, README.md, ROADMAP.md, CHANGELOG.md
40+
CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md
3841
VERSION # source of truth for the repo version
39-
LICENSE # MIT
42+
LICENSE # CC-BY-NC-ND-4.0
4043
```
4144

4245
## Branching and commit model
@@ -71,7 +74,7 @@ Each skill lives at `skills/<skill-name>/SKILL.md`. Frontmatter is YAML:
7174
---
7275
name: <kebab-case-skill-name>
7376
description: <one-line, under 200 chars>
74-
standards-version: 1.9.1
77+
standards-version: 1.9.4
7578
---
7679
```
7780

@@ -90,7 +93,7 @@ Rules are `.mdc` files in `rules/`. Frontmatter:
9093
---
9194
description: <one-line>
9295
alwaysApply: true
93-
standards-version: 1.9.1
96+
standards-version: 1.9.4
9497
---
9598
```
9699

@@ -100,7 +103,7 @@ way, and a one-paragraph rationale. 30 to 80 lines is the right size.
100103
## CI/CD workflows
101104

102105
- `validate.yml` runs file structure checks plus a `validate-counts` job that
103-
asserts the README aggregate counts (8 skills, 4 rules, 1 template, 10
106+
asserts the README aggregate counts (12 skills, 6 rules, 2 templates, 17
104107
snippets) match filesystem reality. The counts language in `README.md` is
105108
load-bearing: the job greps for it.
106109
- `drift-check.yml` consumes `Developer-Tools-Directory/.github/actions/
@@ -125,4 +128,4 @@ property handling has invalidated a lot of community content.
125128

126129
## License
127130

128-
MIT. See `LICENSE`.
131+
CC-BY-NC-ND-4.0. See `LICENSE`.

CLAUDE.md

Lines changed: 31 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,28 @@
1-
<!-- standards-version: 1.9.1 -->
1+
<!-- standards-version: 1.9.4 -->
22

33
# CLAUDE.md
44

55
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
66

77
## Project Overview
88

9-
The **Blender Developer Tools** repository is at **v0.1.3**. It packages skills, rules, snippets, and a starter template for Blender Python development with Cursor and Claude Code. Coverage targets **Blender 5.1** (current stable) with **Blender 4.5 LTS** fallback. There is no MCP server in v0.1.3; content is consumed directly by the AI when working in Blender add-on or scripting projects.
9+
The **Blender Developer Tools** repository is at **v0.1.3**. It packages skills, rules, snippets, and starter templates for Blender Python development with Cursor and Claude Code. Coverage targets **Blender 5.1** (current stable) with **Blender 4.5 LTS** fallback. There is no MCP server; content is consumed directly by the AI when working in Blender add-on or scripting projects.
1010

1111
**Version:** 0.1.3
12-
**License:** MIT
13-
**Author:** TMHSDigital
12+
**License:** CC-BY-NC-ND-4.0
13+
**Author:** TM Hospitality Strategies
1414

1515
## Repository Architecture
1616

1717
```
18-
skills/<skill-name>/SKILL.md - AI workflow definitions, 8 total
19-
rules/<rule-name>.mdc - Anti-pattern rules, 4 total
20-
templates/<template-name>/ - Starter projects, 1 total
21-
snippets/<snippet-name>.py - Standalone code patterns, 10 total
18+
skills/<skill-name>/SKILL.md - AI workflow definitions, 12 total
19+
rules/<rule-name>.mdc - Anti-pattern rules, 6 total
20+
templates/<template-name>/ - Starter projects, 2 total
21+
snippets/<snippet-name>.py - Standalone code patterns, 17 total
2222
VERSION - Source of truth for the repo version
2323
```
2424

25-
## Skills (8)
25+
## Skills (12)
2626

2727
| Skill | Purpose |
2828
| --- | --- |
@@ -34,17 +34,23 @@ VERSION - Source of truth for the repo version
3434
| headless-batch-scripting | `blender --background --python`, temp_override, argparse after `--` |
3535
| slotted-actions-animation | Blender 5.x Slotted Actions, channelbag, 4.5 LTS fallback bridge |
3636
| geometry-nodes-python | Programmatic GN tree construction, interface sockets, NODES modifier |
37+
| procedural-materials-and-shaders | Node tree construction for Principled BSDF, emissive, node groups, EEVEE Next vs Cycles |
38+
| depsgraph-and-evaluated-data | `evaluated_get` / `to_mesh` / `to_mesh_clear` lifetime contract for exporters and measurement |
39+
| drivers-and-app-handlers | Driver expressions, `driver_namespace`, application handlers including the new 5.1 `exit_pre` |
40+
| bl-info-migration | Three-step migration from legacy `bl_info` to Extensions Platform, dual-format pattern |
3741

38-
## Rules (4)
42+
## Rules (6)
3943

4044
| Rule | Scope | What it flags |
4145
| --- | --- | --- |
4246
| prefer-data-over-ops-in-loops | Always on | `bpy.ops.*` calls inside iteration over many objects |
4347
| always-free-bmesh | `*.py` | `bmesh.new()` without paired `bm.free()` in a `try`/`finally` block |
4448
| target-extensions-platform-format | Add-on roots | Legacy `bl_info` only add-ons missing `blender_manifest.toml` |
4549
| type-annotate-props-and-defend-context | `*.py` | `bpy.props` defined as assignments, unguarded `context.active_object` |
50+
| prefer-temp-override-over-context-copy | `*.py` | `bpy.context.copy()` passed to operators (deprecated 4.x, removed 5.x) |
51+
| use-foreach-set-for-bulk-data | `*.py` | Python loops over `mesh.vertices` setting bulk attributes one at a time |
4652

47-
## Templates (1)
53+
## Templates (2)
4854

4955
`templates/extension-addon-template/` is a copy-paste-ready Blender extension demonstrating:
5056

@@ -54,9 +60,21 @@ VERSION - Source of truth for the repo version
5460
- A `PointerProperty` bound to `bpy.types.Scene`
5561
- Symmetric `register()` / `unregister()` with property cleanup before class unregister
5662

57-
## Snippets (10)
63+
`templates/headless-batch-script-template/` is a working starter for unattended Blender batch jobs:
5864

59-
Small standalone `.py` files at `snippets/<name>.py`, each 5 to 30 lines, covering: canonical object creation and deletion, depsgraph evaluated mesh, bmesh load-edit-free, temp_override context, foreach_set vertex bulk write, register_classes_factory, PointerProperty binding, cross-version property delete, and the `action_ensure_channelbag_for_slot` slotted-actions bridge.
65+
- `argparse` parsing of args after the `--` separator
66+
- Iteration over every mesh object via `bpy.data.objects`
67+
- Modifier application via `bpy.context.temp_override` (not the deprecated context-dict form)
68+
- glTF export via `bpy.ops.export_scene.gltf`
69+
- Explicit exit codes for CI integration
70+
71+
## Snippets (17)
72+
73+
Small standalone `.py` files at `snippets/<name>.py`, each 5 to 50 lines.
74+
75+
v0.1.0: canonical object creation and deletion, depsgraph evaluated mesh, bmesh load-edit-free, temp_override context, foreach_set vertex bulk write, register_classes_factory, PointerProperty binding, cross-version property delete, and the `action_ensure_channelbag_for_slot` slotted-actions bridge.
76+
77+
v0.2.0: Principled BSDF material, driver-with-custom-function via `driver_namespace`, application handler registration, shader node group with cross-version `interface` API, `foreach_get` bulk vertex read, version-branch skeleton, and USD export with `evaluation_mode='RENDER'`.
6078

6179
## Development Workflow
6280

README.md

Lines changed: 19 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
</p>
66

77
<p align="center">
8-
<a href="https://github.com/TMHSDigital/Blender-Developer-Tools/releases"><img src="https://img.shields.io/badge/version-0.1.1-e87d0d?style=flat-square" alt="Version" /></a>
8+
<a href="https://github.com/TMHSDigital/Blender-Developer-Tools/releases"><img src="https://img.shields.io/badge/version-0.2.0-e87d0d?style=flat-square" alt="Version" /></a>
99
<a href="https://github.com/TMHSDigital/Blender-Developer-Tools/releases"><img src="https://img.shields.io/github/v/release/TMHSDigital/Blender-Developer-Tools?style=flat-square&color=e87d0d&label=release" alt="Release" /></a>
1010
<a href="LICENSE"><img src="https://img.shields.io/badge/license-CC--BY--NC--ND--4.0-384d54?style=flat-square" alt="License" /></a>
1111
</p>
@@ -16,23 +16,23 @@
1616
</p>
1717

1818
<p align="center">
19-
<strong>8 skills</strong> &nbsp;&bull;&nbsp; <strong>4 rules</strong> &nbsp;&bull;&nbsp; <strong>1 template</strong> &nbsp;&bull;&nbsp; <strong>10 snippets</strong>
19+
<strong>12 skills</strong> &nbsp;&bull;&nbsp; <strong>6 rules</strong> &nbsp;&bull;&nbsp; <strong>2 templates</strong> &nbsp;&bull;&nbsp; <strong>17 snippets</strong>
2020
</p>
2121

2222
---
2323

2424
## Overview
2525

26-
This repository ships **8 skills, 4 rules, 1 template, and 10 snippets** for Blender Python development targeting Blender 5.1 (current stable) with Blender 4.5 LTS fallback support.
26+
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.
2727

2828
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.
2929

3030
| Layer | Role |
3131
| --- | --- |
32-
| **Skills** | Guided workflows: scaffolding, operators, panels, properties, mesh and bmesh, headless batch, slotted actions, geometry nodes |
33-
| **Rules** | Guardrails for the most common AI mistakes: ops-in-loops, bmesh leaks, legacy `bl_info` only, prop assignments |
34-
| **Templates** | A working Extensions Platform add-on starter with `register_classes_factory` and a PointerProperty binding |
35-
| **Snippets** | 10 small standalone Python files demonstrating canonical patterns |
32+
| **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 |
33+
| **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 |
34+
| **Templates** | A working Extensions Platform add-on starter and a headless batch script starter |
35+
| **Snippets** | 17 small standalone Python files demonstrating canonical patterns |
3636

3737
## Supported Blender versions
3838

@@ -45,27 +45,31 @@ The content is consumed by AI coding agents (Cursor, Claude Code, any MCP-capabl
4545
## How content is organized
4646

4747
```
48-
skills/<name>/SKILL.md - 8 skill files, YAML frontmatter, one canonical pattern each
49-
rules/<name>.mdc - 4 rule files, anti-pattern + correction
50-
templates/<name>/ - 1 template directory (extension-addon-template)
51-
snippets/<name>.py - 10 standalone Python snippets, 5 to 30 lines each
48+
skills/<name>/SKILL.md - 12 skill files, YAML frontmatter, one canonical pattern each
49+
rules/<name>.mdc - 6 rule files, anti-pattern + correction
50+
templates/<name>/ - 2 template directories (extension-addon-template, headless-batch-script-template)
51+
snippets/<name>.py - 17 standalone Python snippets, 5 to 50 lines each
5252
```
5353

5454
## Using rules in Cursor
5555

56-
The `.mdc` files in `rules/` apply automatically when Cursor opens a Blender Python project, scoped by the `globs` in each rule's frontmatter. The four rules are:
56+
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:
5757

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

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

65-
## Using the template
67+
## Using the templates
6668

6769
`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()`.
6870

71+
`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 ...`.
72+
6973
## Snippets
7074

7175
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.
@@ -83,8 +87,8 @@ When community content (Stack Overflow, older add-on source) conflicts with the
8387

8488
## Roadmap
8589

86-
See [ROADMAP.md](ROADMAP.md). v0.2.0 candidates include procedural materials, depsgraph queries, drivers, a `bl_info` to manifest migration skill, and a headless batch script template.
90+
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.
8791

8892
## License
8993

90-
Copyright (c) 2026 TMHSDigital. Licensed under [MIT](LICENSE).
94+
Copyright (c) 2026 TM Hospitality Strategies. Licensed under [CC-BY-NC-ND-4.0](LICENSE).

0 commit comments

Comments
 (0)