Skip to content

Commit ae3ab05

Browse files
feat: add eval-mesh-datablock-name cross-version example
Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com> Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent 6c276b3 commit ae3ab05

8 files changed

Lines changed: 264 additions & 9 deletions

File tree

‎.cursor-plugin/plugin.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,7 @@
9393
"examples/degenerate-bevel-weld",
9494
"examples/depsgraph-export",
9595
"examples/driver-wave",
96+
"examples/eval-mesh-datablock-name",
9697
"examples/exit-pre-sidecar",
9798
"examples/export-preset-axis",
9899
"examples/gltf-export-roundtrip",

‎AGENTS.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ a `.cursor-plugin/plugin.json` manifest so the ecosystem drift checker
2020
classifies it as a `cursor-plugin`. This is content the AI loads when the user
2121
asks Blender questions or works on Blender add-ons in Cursor or Claude Code.
2222

23-
The content base is 16 skills, 9 rules, 3 templates, 27 snippets, and 57
23+
The content base is 16 skills, 9 rules, 3 templates, 27 snippets, and 58
2424
examples (counts are CI-enforced against README.md and the manifest). The full
2525
inventory tables and per-item purposes live in `CLAUDE.md`. Example anatomy
2626
and authoring rules: copy `examples/bmesh-gear/`; the render look is specified
@@ -35,7 +35,7 @@ Blender-Developer-Tools/
3535
rules/<rule-name>.mdc # 9 rule files
3636
templates/<template-name>/ # 3 starter templates
3737
snippets/<snippet-name>.py # 27 standalone Python snippets
38-
examples/<name>/ # 55 runnable smoke-gated examples (+ gallery.json)
38+
examples/<name>/ # 58 runnable smoke-gated examples (+ gallery.json)
3939
examples/gallery_framing.py # shared Layer 1 framing measurement (render path only)
4040
scripts/build_gallery.py # generates docs/gallery/ (stdlib only)
4141
scripts/site/ # vendored landing-page build (build_site.py + template)

‎CLAUDE.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ skills/<skill-name>/SKILL.md - AI workflow definitions, 16 total
2121
rules/<rule-name>.mdc - Anti-pattern rules, 9 total
2222
templates/<template-name>/ - Starter projects, 3 total
2323
snippets/<snippet-name>.py - Standalone code patterns, 27 total
24-
examples/<name>/ - Runnable smoke-gated examples, 57 total (+ gallery.json)
24+
examples/<name>/ - Runnable smoke-gated examples, 58 total (+ gallery.json)
2525
scripts/build_gallery.py - Regenerates docs/gallery/ from gallery.json (stdlib only)
2626
scripts/site/ - Vendored landing-page build (Jinja2)
2727
docs/gallery/ - Committed generated gallery pages + hero renders
@@ -99,7 +99,7 @@ v0.2.0: Principled BSDF material, driver-with-custom-function via `driver_namesp
9999

100100
AI asset pipeline track: `decimate_to_budget.py`, `convex_hull_collider.py`, `lod_chain.py` (helper duplicated, not imported), `gltf_draco_export.py`, `export_preset_unity.py`, `export_preset_godot.py`, `export_preset_unreal.py`, `setup_bake_target_image.py`, `bake_normal_high_to_low.py`, `save_baked_image.py`.
101101

102-
## Examples (57)
102+
## Examples (58)
103103

104104
Runnable scripts at `examples/<name>/`, each asserting a real API contract with
105105
deterministic checks (exit non-zero on failure) and optionally rendering a still via

‎README.md‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
</p>
1919

2020
<p align="center">
21-
<strong>16 skills</strong> &nbsp;&bull;&nbsp; <strong>9 rules</strong> &nbsp;&bull;&nbsp; <strong>3 templates</strong> &nbsp;&bull;&nbsp; <strong>27 snippets</strong> &nbsp;&bull;&nbsp; <strong>57 examples</strong>
21+
<strong>16 skills</strong> &nbsp;&bull;&nbsp; <strong>9 rules</strong> &nbsp;&bull;&nbsp; <strong>3 templates</strong> &nbsp;&bull;&nbsp; <strong>27 snippets</strong> &nbsp;&bull;&nbsp; <strong>58 examples</strong>
2222
</p>
2323

2424
<p align="center">
@@ -36,7 +36,7 @@
3636

3737
## Overview
3838

39-
This repository ships **16 skills, 9 rules, 3 templates, 27 snippets, and 57 examples** for Blender Python development targeting Blender 5.2 LTS (current stable) with Blender 4.5 LTS fallback support. Blender 5.1 is prior stable.
39+
This repository ships **16 skills, 9 rules, 3 templates, 27 snippets, and 58 examples** for Blender Python development targeting Blender 5.2 LTS (current stable) with Blender 4.5 LTS fallback support. Blender 5.1 is prior stable.
4040

4141
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.
4242

@@ -203,7 +203,7 @@ Gallery still is a dual-elevation diptych so the contract reads at thumbnail sca
203203
</details>
204204

205205
<details>
206-
<summary><strong>Mesh, curves &amp; text</strong> — 12 examples</summary>
206+
<summary><strong>Mesh, curves &amp; text</strong> — 13 examples</summary>
207207

208208
<table>
209209
<tr>
@@ -308,6 +308,20 @@ A depsgraph-evaluated export — builds a cube with `SUBSURF`, measures the eval
308308
`evaluated_get().to_mesh()` / `to_mesh_clear()`, and asserts `wm.obj_export` ships the
309309
modifier-applied geometry (exported vertex count == evaluated > base).
310310

311+
</td>
312+
</tr>
313+
<tr>
314+
<td width="46%" valign="middle">
315+
check-only, no gallery still — no geometry
316+
</td>
317+
<td valign="middle">
318+
319+
### [eval-mesh-datablock-name](examples/eval-mesh-datablock-name/)
320+
321+
`evaluated_get().data.name` is generic `Mesh` on 4.5.11 and 5.1.2 and equals
322+
the source name on 5.2.1. `to_mesh().name` stays the source name on all
323+
three. `--assume-distinct-names` is red only on 5.2.
324+
311325
</td>
312326
</tr>
313327
<tr>

‎ROADMAP.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,7 @@ Not committed; target list for the next content version. (v0.3.0 shipped the smo
142142
- UV atlas **utilization** witness — coverage/wasted-texel closed forms for a packed lightmap atlas (the non-overlap, unit-square, margin, and active/active_render contracts shipped in `lightmap-uv-channel`; utilization is the remaining unbuilt slice of the old "UV atlas pack" candidate)
143143
- ~~VSE `use_linear_modifiers` removal~~ **SHIPPED** as `examples/vse-linear-modifiers/` — bool on 4.5.11 and 5.1.2, `AttributeError` on 5.2.1; `--assume-present` red only on 5.2; pathology, no gallery still
144144
- ~~GN Compare / Random Value socket identifier rename~~ **SHIPPED** as `examples/gn-socket-rename/` — `A_INT` / `Min_001` present on 4.5.11 and 5.1.2, absent on 5.2.1; enabled-name lookup wires all three; `--legacy-ids` red only on 5.2
145-
- Evaluated mesh datablock `evaluated_get().data.name` is generic `Mesh` on 4.5.11 and 5.1.2 and equals the source name on 5.2.1 (`to_mesh().name` stays the source name on all three)
145+
- ~~Evaluated mesh datablock `evaluated_get().data.name` is generic `Mesh` on 4.5.11 and 5.1.2 and equals the source name on 5.2.1 (`to_mesh().name` stays the source name on all three)~~ **SHIPPED** as `examples/eval-mesh-datablock-name/` — `evaluated_get().data.name` is `Mesh` on 4.5.11 and 5.1.2, `SourceMesh` on 5.2.1; `to_mesh().name` stays `SourceMesh` on all three; `--assume-distinct-names` red only on 5.2; pathology, no gallery still
146146
- `MeshAutomaskingSettings` move: old `Brush` automasking attributes gone on 5.2
147147
- ~~GAMMA_CROSS blend-curve witness~~ **SHIPPED** as `examples/vse-gamma-cross/` — the cross blends in a gamma-0.5 space: `((1-t)·√A + t·√B)²` with `t = (frame − start)/duration`, never 1 inside the effect; mid-cross dips 0.115 below the sRGB lerp from crimson/teal (closed form (0.341, 0.349, 0.463) confirmed per frame); AgX-default sampling poisons the fit (0.146 red-channel error, `view_transform='Standard'` mandatory); deleting a consumed input orphans-and-deletes the effect — follow-up to `vse-cut-list`
148148
- Falsy `bpy_prop_collection` trap snippet: an empty collection is falsy, so `editor.strips or editor.sequences` silently falls through to the legacy accessor on an empty timeline — always branch on `hasattr`; likely generalizes across the API (found authoring `vse-cut-list`)
Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Evaluated mesh datablock name
2+
3+
Pathology witness for the 5.2 change in
4+
`Object.evaluated_get(depsgraph).data.name`. A cube plus SUBSURF is
5+
enough; there is no gallery still (same class as
6+
[`vse-linear-modifiers`](../vse-linear-modifiers/),
7+
[`ngon-triangulate`](../ngon-triangulate/)).
8+
9+
Follows [`depsgraph-and-evaluated-data`](../../skills/depsgraph-and-evaluated-data/SKILL.md)
10+
and the version-gated assertion shape of
11+
[`gn-modifier-inputs`](../gn-modifier-inputs/) (per-version contract, exit
12+
0 on every matrix leg). Scaffolding matches
13+
[`cross-version-property-delete`](../cross-version-property-delete/)
14+
(`check()` returns, argparse naive-API flag, FATAL wrapper). That example
15+
does **not** version-branch, so the gate itself is copied from
16+
`gn-modifier-inputs`, not from `del`.
17+
18+
**What it witnesses:** with source mesh named `SourceMesh`,
19+
`evaluated_get().data.name` is generic `Mesh` on 4.5.11 and 5.1.2, and
20+
`SourceMesh` on 5.2.1. `to_mesh().name` is `SourceMesh` on all three —
21+
that accessor is not the witness. SUBSURF `levels=1` on a cube is
22+
load-bearing: 8 source verts vs 26 evaluated (Catmull-Clark). Name
23+
comparison that treats inequality as "this is evaluated" is silently
24+
wrong on 5.2; nothing raises.
25+
26+
**What failure each check would catch:**
27+
28+
- exit 3 — source cube was not 8 verts, or evaluated data is missing
29+
- exit 4 — SUBSURF did not produce a distinct evaluated mesh (not 26 verts)
30+
- exit 5 — source datablock name is not `SourceMesh`
31+
- exit 6 — evaluated datablock name is wrong for this Blender
32+
(`--assume-distinct-names` on 5.2 lands here: names match)
33+
- exit 7 — `to_mesh().name` is not `SourceMesh`
34+
35+
`--assume-distinct-names` is the falsifier: skip the version gate and
36+
demand the 4.5/5.1 inequality. It exits **0 on 4.5.11 and 5.1.2** (the
37+
names still differ) and **6 on 5.2.1**. That is unlike `--same-axis`,
38+
which is red on every binary.
39+
40+
No `SMOKE_SKIP`. Every matrix leg exercises the contract.
41+
42+
## Run
43+
44+
```bash
45+
blender --background --python eval_mesh_datablock_name.py --
46+
blender --background --python eval_mesh_datablock_name.py -- --assume-distinct-names
47+
```
48+
49+
## Exit codes
50+
51+
Per-script sequential checks. `9` is a valid check code; there is no rule
52+
against it.
53+
54+
| Code | Meaning |
55+
| --- | --- |
56+
| 0 | Success |
57+
| 1 | Uncaught exception (FATAL wrapper) |
58+
| 2 | argparse / usage |
59+
| 3 | Source cube missing or not 8 verts |
60+
| 4 | SUBSURF did not produce a distinct evaluated mesh |
61+
| 5 | Source datablock name is not `SourceMesh` |
62+
| 6 | Evaluated datablock name wrong for this version (`--assume-distinct-names` on 5.2) |
63+
| 7 | `to_mesh().name` is not `SourceMesh` |
64+
65+
The `blender-smoke` workflow runs the check on Blender 5.2 LTS and 4.5 LTS
66+
(5.1 on the weekly cron, the `needs-5.1` PR label, or manual dispatch).
67+
Smoke does not pass `--assume-distinct-names`.
Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
"""Evaluated mesh datablock naming — a runnable example.
2+
3+
Witnesses that ``Object.evaluated_get(depsgraph).data.name`` is a generic
4+
``Mesh`` on 4.5 LTS and 5.1, and equals the source mesh name on 5.2.
5+
``to_mesh().name`` equals the source name on all three — it is not the
6+
witness. Code that treats name inequality as "this is evaluated geometry"
7+
is silently wrong on 5.2: nothing raises.
8+
9+
Pathology: no gallery still. A SUBSURF cube is enough to produce a
10+
distinct evaluated datablock (8 source verts vs 26 Catmull-Clark).
11+
12+
The default path asserts the names that are correct for *this* Blender
13+
and still exits 0 on all three. ``--assume-distinct-names`` is the naive
14+
script: fail if the names match. That is red only on 5.2.
15+
16+
blender --background --python eval_mesh_datablock_name.py --
17+
blender --background --python eval_mesh_datablock_name.py -- --assume-distinct-names
18+
"""
19+
import argparse
20+
import sys
21+
22+
import bpy
23+
24+
SOURCE_NAME = "SourceMesh"
25+
GENERIC_EVAL_NAME = "Mesh"
26+
SOURCE_VERTS = 8
27+
EVAL_VERTS = 26 # Catmull-Clark SUBSURF levels=1 on a cube
28+
CHANGED_AT = (5, 2, 0)
29+
30+
31+
def fail(msg, code):
32+
print(f"ERROR: {msg}", file=sys.stderr)
33+
return code
34+
35+
36+
def cube_mesh(name):
37+
me = bpy.data.meshes.new(name)
38+
me.from_pydata(
39+
[(-1, -1, -1), (1, -1, -1), (1, 1, -1), (-1, 1, -1),
40+
(-1, -1, 1), (1, -1, 1), (1, 1, 1), (-1, 1, 1)],
41+
[],
42+
[(0, 1, 2, 3), (4, 5, 6, 7), (0, 1, 5, 4),
43+
(2, 3, 7, 6), (0, 3, 7, 4), (1, 2, 6, 5)],
44+
)
45+
me.update()
46+
return me
47+
48+
49+
def build():
50+
bpy.ops.wm.read_factory_settings(use_empty=True)
51+
me = cube_mesh(SOURCE_NAME)
52+
obj = bpy.data.objects.new("SourceObj", me)
53+
bpy.context.collection.objects.link(obj)
54+
mod = obj.modifiers.new("ss", "SUBSURF")
55+
mod.levels = 1
56+
bpy.context.view_layer.update()
57+
return obj
58+
59+
60+
def check(obj, assume_distinct_names=False):
61+
ver = tuple(bpy.app.version)
62+
legacy_distinct = ver < CHANGED_AT
63+
require_distinct = assume_distinct_names or legacy_distinct
64+
print(
65+
f"blender={ver} assume_distinct_names={assume_distinct_names} "
66+
f"legacy_distinct={legacy_distinct} require_distinct={require_distinct}"
67+
)
68+
69+
if obj is None or obj.data is None:
70+
return fail("source object/mesh missing", 3)
71+
72+
dg = bpy.context.evaluated_depsgraph_get()
73+
ev = obj.evaluated_get(dg)
74+
if ev.data is None:
75+
return fail("evaluated_get().data is None", 3)
76+
77+
src_name = obj.data.name
78+
eval_name = ev.data.name
79+
src_verts = len(obj.data.vertices)
80+
eval_verts = len(ev.data.vertices)
81+
tm = ev.to_mesh()
82+
try:
83+
tm_name = tm.name
84+
tm_verts = len(tm.vertices)
85+
finally:
86+
ev.to_mesh_clear()
87+
88+
print(
89+
f"src_name={src_name!r} eval_data_name={eval_name!r} "
90+
f"to_mesh_name={tm_name!r}"
91+
)
92+
print(
93+
f"src_verts={src_verts} eval_verts={eval_verts} "
94+
f"to_mesh_verts={tm_verts} eval_is_src={ev.data is obj.data}"
95+
)
96+
97+
if src_verts != SOURCE_VERTS:
98+
return fail(
99+
f"source verts {src_verts} != {SOURCE_VERTS} (cube build)",
100+
3,
101+
)
102+
if eval_verts != EVAL_VERTS or ev.data is obj.data:
103+
return fail(
104+
f"SUBSURF did not produce a distinct evaluated mesh "
105+
f"(eval_verts={eval_verts}, same_datablock={ev.data is obj.data})",
106+
4,
107+
)
108+
if src_name != SOURCE_NAME:
109+
return fail(f"source name {src_name!r} != {SOURCE_NAME!r}", 5)
110+
111+
if require_distinct:
112+
if eval_name == src_name:
113+
return fail(
114+
f"evaluated datablock name {eval_name!r} equals source "
115+
f"{src_name!r} — naive name-inequality distinguisher is wrong",
116+
6,
117+
)
118+
if eval_name != GENERIC_EVAL_NAME:
119+
return fail(
120+
f"expected generic {GENERIC_EVAL_NAME!r} on {ver}, "
121+
f"got {eval_name!r}",
122+
6,
123+
)
124+
else:
125+
if eval_name != src_name:
126+
return fail(
127+
f"5.2+ evaluated datablock name {eval_name!r} != "
128+
f"source {src_name!r}",
129+
6,
130+
)
131+
if eval_name != SOURCE_NAME:
132+
return fail(
133+
f"expected source name {SOURCE_NAME!r} on {ver}, "
134+
f"got {eval_name!r}",
135+
6,
136+
)
137+
138+
if tm_name != SOURCE_NAME:
139+
return fail(
140+
f"to_mesh().name {tm_name!r} != {SOURCE_NAME!r} "
141+
"(this accessor is not the witness; it must stay the source)",
142+
7,
143+
)
144+
return 0
145+
146+
147+
def main():
148+
argv = sys.argv[sys.argv.index("--") + 1:] if "--" in sys.argv else []
149+
p = argparse.ArgumentParser()
150+
p.add_argument(
151+
"--assume-distinct-names",
152+
action="store_true",
153+
help="falsification: treat name inequality as the evaluated-mesh test",
154+
)
155+
args = p.parse_args(argv)
156+
157+
obj = build()
158+
code = check(obj, assume_distinct_names=args.assume_distinct_names)
159+
if code:
160+
return code
161+
print("eval-mesh-datablock-name OK")
162+
return 0
163+
164+
165+
if __name__ == "__main__":
166+
try:
167+
sys.exit(main())
168+
except Exception as e:
169+
import traceback
170+
traceback.print_exc()
171+
print(f"FATAL: {e}", file=sys.stderr)
172+
sys.exit(1)

‎tests/smoke/catalog.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,5 +71,6 @@
7171
{"name": "coincident-vert-weld", "script": "examples/coincident-vert-weld/coincident_vert_weld.py"},
7272
{"name": "bake-normal-high-to-low", "script": "examples/bake-normal-high-to-low/bake_normal_high_to_low.py"},
7373
{"name": "vse-linear-modifiers", "script": "examples/vse-linear-modifiers/vse_linear_modifiers.py"},
74-
{"name": "gn-socket-rename", "script": "examples/gn-socket-rename/gn_socket_rename.py"}
74+
{"name": "gn-socket-rename", "script": "examples/gn-socket-rename/gn_socket_rename.py"},
75+
{"name": "eval-mesh-datablock-name", "script": "examples/eval-mesh-datablock-name/eval_mesh_datablock_name.py"}
7576
]

0 commit comments

Comments
 (0)