Skip to content

Commit 01c186b

Browse files
TMHSDigitalclaude
andauthored
feat: add armature-bend example (edit_bones + LBS closed-form witness) (#58)
Nothing in the gallery touched rigging, and armature code is where AI-generated Blender Python fails silently most often: edit_bones reads outside edit mode return nothing, and a mistyped vertex-group name deforms nothing without erroring. This example builds a four-bone chain via edit_bones, skins a tapered tube through name-bound vertex groups with smoothstep blend zones, poses a curl, and asserts the armature modifier is exactly linear blend skinning — every depsgraph-evaluated vertex must equal the re-implemented closed form (root ring pinned, tip deflected; a straight tube fails). It also bakes in a portability hazard found while authoring: holding a color-attribute reference across VertexGroup.add() dangles it when the deform layer allocates — a hard crash on 4.5 LTS that 5.1 survives by luck — so all weight writes finish before the attribute is created. Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
1 parent 96e6eae commit 01c186b

13 files changed

Lines changed: 979 additions & 11 deletions

File tree

‎.cursor-plugin/plugin.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@
5959
"templates/headless-batch-script-template"
6060
],
6161
"examples": [
62+
"examples/armature-bend",
6263
"examples/bmesh-gear",
6364
"examples/color-attribute-wheel",
6465
"examples/compositor-glare",

‎.github/workflows/blender-smoke.yml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -286,3 +286,15 @@ jobs:
286286
# the raw POINT attribute buffer. Exits non-zero on failure.
287287
xvfb-run -a "$BLENDER" --background \
288288
--python examples/grease-pencil-rosette/grease_pencil_rosette.py --
289+
290+
- name: Shipped example - armature bend (edit_bones + LBS closed form)
291+
run: |
292+
set -euo pipefail
293+
# Check only (no render): a four-bone chain skins a tapered tube via
294+
# name-bound vertex groups; asserts edit_bones is empty outside edit
295+
# mode and holds the closed-form chain inside it, then compares every
296+
# depsgraph-evaluated vertex against re-implemented linear blend
297+
# skinning (root ring pinned, tip deflected — a straight tube fails).
298+
# Exits non-zero on failure.
299+
xvfb-run -a "$BLENDER" --background \
300+
--python examples/armature-bend/armature_bend.py --

‎AGENTS.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ The content base (counts are CI-enforced against README.md and the manifest):
2727
- 2 templates: `extension-addon-template` for Extensions Platform add-ons,
2828
and `headless-batch-script-template` for unattended batch jobs.
2929
- 17 snippets covering canonical patterns.
30-
- 17 examples under `examples/<name>/`: runnable scripts that assert a real
30+
- 18 examples under `examples/<name>/`: runnable scripts that assert a real
3131
API contract with deterministic checks, exit non-zero on failure, and
3232
optionally render a still via `--output`. Each is executed headless on
3333
Blender 4.5 LTS and 5.1 by `blender-smoke.yml`; its render ships in the
@@ -41,7 +41,7 @@ Blender-Developer-Tools/
4141
rules/<rule-name>.mdc # 6 rule files
4242
templates/<template-name>/ # 2 starter templates
4343
snippets/<snippet-name>.py # 17 standalone Python snippets
44-
examples/<name>/ # 17 runnable smoke-gated examples (+ gallery.json)
44+
examples/<name>/ # 18 runnable smoke-gated examples (+ gallery.json)
4545
scripts/build_gallery.py # generates docs/gallery/ (stdlib only)
4646
scripts/site/ # vendored landing-page build (build_site.py + template)
4747
docs/gallery/ # committed generated gallery pages + hero assets

‎CLAUDE.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ skills/<skill-name>/SKILL.md - AI workflow definitions, 12 total
1919
rules/<rule-name>.mdc - Anti-pattern rules, 6 total
2020
templates/<template-name>/ - Starter projects, 2 total
2121
snippets/<snippet-name>.py - Standalone code patterns, 17 total
22-
examples/<name>/ - Runnable smoke-gated examples, 17 total (+ gallery.json)
22+
examples/<name>/ - Runnable smoke-gated examples, 18 total (+ gallery.json)
2323
scripts/build_gallery.py - Regenerates docs/gallery/ from gallery.json (stdlib only)
2424
scripts/site/ - Vendored landing-page build (Jinja2)
2525
docs/gallery/ - Committed generated gallery pages + hero renders
@@ -80,11 +80,11 @@ v0.1.0: canonical object creation and deletion, depsgraph evaluated mesh, bmesh
8080

8181
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'`.
8282

83-
## Examples (17)
83+
## Examples (18)
8484

8585
Runnable scripts at `examples/<name>/`, each asserting a real API contract with
8686
deterministic checks (exit non-zero on failure) and optionally rendering a still via
87-
`--output`. All seventeen run headless on Blender 4.5 LTS and 5.1 in `blender-smoke.yml`;
87+
`--output`. All eighteen run headless on Blender 4.5 LTS and 5.1 in `blender-smoke.yml`;
8888
their renders ship in the site gallery at `docs/gallery/`. `examples/gallery.json` is the
8989
gallery's source of truth. When authoring a new one, copy the anatomy of
9090
`examples/bmesh-gear/` (script structure, README shape, dark-studio render recipe) and

‎README.md‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,14 +17,14 @@
1717
</p>
1818

1919
<p align="center">
20-
<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> &nbsp;&bull;&nbsp; <strong>17 examples</strong>
20+
<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> &nbsp;&bull;&nbsp; <strong>18 examples</strong>
2121
</p>
2222

2323
---
2424

2525
## Overview
2626

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

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

@@ -297,6 +297,23 @@ while `grease_pencils` is still legacy; on 5.x legacy is gone and GPv3 owns the
297297
name. Point writes lazily materialize attribute layers, and every position
298298
round-trips through the raw `POINT` buffer.
299299

300+
</td>
301+
</tr>
302+
<tr>
303+
<td width="46%" valign="middle">
304+
<a href="examples/armature-bend/"><img src="examples/armature-bend/preview.webp" alt="Armature bend: three tapered tubes on a dark studio floor showing rest, half, and full curl under a four-bone armature, per-bone weight bands blending teal through amber to coral at the joints" /></a>
305+
</td>
306+
<td valign="middle">
307+
308+
### [armature-bend](examples/armature-bend/)
309+
310+
A four-bone chain built with `edit_bones` skins a tapered tube through name-bound
311+
vertex groups, posed into a curl and read back through the depsgraph. Asserts that
312+
`edit_bones` is empty outside edit mode, and that the armature modifier is exactly
313+
linear blend skinning — every evaluated vertex equals
314+
Σ wᵢ · (`pose_bone.matrix` @ `bone.matrix_local.inverted()`) @ rest, with the root
315+
ring pinned and the tip deflected. A straight tube is a failure.
316+
300317
</td>
301318
</tr>
302319
</table>

‎ROADMAP.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,7 @@ Not committed; target list for the next content version. (v0.3.0 shipped the smo
9797
- Refresh the `slotted-actions-animation` skill against any 5.2 changes
9898
- Bump `blender_version_min` in the templates if 5.2 APIs are used
9999
- Additional snippets for asset library scripting, EXR baking, multi-file extensions
100-
- Gallery coverage follow-ups from the GPv3 review: `armature-bend` (edit_bones + vertex groups + pose evaluation) and `text-version-stamp` (TextCurve self-labeling renders); lower priority: light-linking, bulk `pixels.foreach_set`, VSE sequences-to-strips witness (`grease-pencil-rosette` shipped first as the strongest 4.x-to-5.x drift witness)
100+
- Gallery coverage follow-ups from the GPv3 review: `text-version-stamp` (TextCurve self-labeling renders); lower priority: light-linking, bulk `pixels.foreach_set`, VSE sequences-to-strips witness (`grease-pencil-rosette` and `armature-bend` shipped first)
101101

102102
## Future (uncommitted)
103103

0 commit comments

Comments
 (0)