feat: add lod-decimate-chain example witnessing the modifier LOD contract (#76)

Game engines consume LOD chains, and the modifier-based chain is where
AI-generated code drifts: baking the reduction into the base mesh, stacking
ratios, or losing silhouette-critical extremes. A closed-form retro rocket
evaluated at LOD0/1/2 through the depsgraph pins all three: non-destructive
evaluation, ratio-bounded triangle counts, and bbox preservation.

The Decimate API is stable across 4.5 LTS and 5.1; the example demonstrates
that by producing identical measured values on both, and documents the
aggressive-ratio nose-tip collapse as the caught silhouette failure mode.

Signed-off-by: fOuttaMyPaint <TMhospitalitystrategies@gmail.com>

Author: TMHSDigital

.cursor-plugin/plugin.json

@@ -72,6 +72,7 @@
     "examples/gn-sdf-remesh",
     "examples/grease-pencil-rosette",
     "examples/image-pixels-testcard",
+    "examples/lod-decimate-chain",
     "examples/parent-inverse-orrery",
     "examples/png-exr-alpha",
     "examples/shader-node-group",

.github/workflows/blender-smoke.yml

@@ -382,3 +382,14 @@ jobs:
           # bindings within float tolerances. Exits non-zero on failure.
           xvfb-run -a "$BLENDER" --background \
             --python examples/gltf-export-roundtrip/gltf_export_roundtrip.py --
+
+      - name: Shipped example - LOD decimate chain (depsgraph + ratio bounds)
+        run: |
+          set -euo pipefail
+          # Check only (no render): a lathed retro rocket evaluated at LOD0/1/2
+          # through the Decimate modifier; asserts closed-form base topology and
+          # bbox, evaluated-vs-original non-destructiveness (obj.data unchanged),
+          # evaluated triangle counts within 5% of ratio*base, and silhouette
+          # (bbox) preservation within 1e-3. Exits non-zero on failure.
+          xvfb-run -a "$BLENDER" --background \
+            --python examples/lod-decimate-chain/lod_decimate_chain.py --

README.md

@@ -18,7 +18,7 @@
 </p>
 
 <p align="center">
-  <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>24 examples</strong>
+  <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>25 examples</strong>
 </p>
 
 <p align="center">
@@ -36,7 +36,7 @@
 
 ## Overview
 
-This repository ships **12 skills, 6 rules, 2 templates, 17 snippets, and 24 runnable examples** for Blender Python development targeting Blender 5.1 (current stable) with Blender 4.5 LTS fallback support.
+This repository ships **12 skills, 6 rules, 2 templates, 17 snippets, and 25 runnable examples** 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.
 
@@ -466,7 +466,7 @@ round-trips through the raw `POINT` buffer.
 </details>
 
 <details>
-<summary><strong>Game asset pipeline</strong> — 1 example</summary>
+<summary><strong>Game asset pipeline</strong> — 2 examples</summary>
 
 <table>
 <tr>
@@ -485,6 +485,23 @@ loop), V-flipped UVs, and per-triangle material bindings — all against the
 depsgraph-evaluated mesh. The exporter/importer RNA signatures are probed
 byte-identical on 4.5.11 and 5.1.2 and guarded against future renames.
 
+</td>
+</tr>
+<tr>
+<td width="46%" valign="middle">
+<a href="examples/lod-decimate-chain/"><img src="examples/lod-decimate-chain/preview.webp" alt="LOD decimate chain: three retro rockets side by side on a dark studio floor - cream body, red nose and fins, teal porthole - showing smooth LOD0, halved LOD1, and visibly crunched LOD2 with a hexagonal porthole" /></a>
+</td>
+<td valign="middle">
+
+### [lod-decimate-chain](examples/lod-decimate-chain/)
+
+One recognizable asset at three LODs via `DECIMATE` modifiers evaluated through
+the depsgraph. Asserts the reduction is non-destructive (the original datablock
+keeps its closed-form counts), each LOD's evaluated triangle count lands within
+5% of `ratio x base` (measured 0.0–0.44%), and the silhouette-critical bbox
+survives within 1e-3 — with the aggressive-ratio nose-tip collapse documented
+as the caught failure mode.
+
 </td>
 </tr>
 </table>

ROADMAP.md

@@ -104,6 +104,7 @@ Not committed; target list for the next content version. (v0.3.0 shipped the smo
 - Light-linking collection witness: object light linking / receiver collections so a key illuminates only the hero (common AI miss when staging multi-light studios)
 - ~~VSE sequences-to-strips witness~~ **SHIPPED** as `examples/vse-cut-list/` — `.sequences` removed on 5.x (4.5 bridges to `.strips`), `new_effect` end kwarg `frame_end=` (4.5) vs `length=` (5.x), `frame_final_*` deprecated in favor of `left_handle`/`right_handle`/`duration`, TRANSFORM effect type removed, GAMMA_CROSS clamps to the source overlap, effect strips consume inputs only when stacked above them, same-scene scene strips render transparent; save/reload round-trip + tiny-render pixel witness
 - ~~glTF export round-trip witness~~ **SHIPPED** as `examples/gltf-export-roundtrip/` — `export_yup` bakes `(x,y,z)→(x,z,−y)` into vertex data with no node rotation (probed identical on 4.5.11 and 5.1.2), `export_apply` ships the evaluated mesh (one disk vertex per evaluated loop), TEXCOORD_0 is V-flipped on disk, per-triangle material bindings survive; exporter/importer RNA signatures byte-identical between 4.5.11 and 5.1.2 (guarded against future renames); `Mesh.calc_normals()` removal on 5.x surfaced during authoring
+- ~~LOD decimate chain witness~~ **SHIPPED** as `examples/lod-decimate-chain/` — Decimate COLLAPSE evaluated through the depsgraph is non-destructive (obj.data keeps closed-form counts), evaluated tris hit `ratio × base` within 5% (measured 0.0–0.44%), silhouette bbox survives within 1e-3 (measured 7.7e-6); a stacked Decimate halves the effective ratio, an aggressive 0.02 ratio collapses the nose tip — both caught failure modes
 - GAMMA_CROSS blend-curve witness: the cross blend is not the naive linear mix (mid-cross measured (0.341, 0.349, 0.463) from crimson (0.85, 0.10, 0.22) and teal (0.06, 0.75, 0.80)) — derive and assert the gamma-space closed form per frame; follow-up to `vse-cut-list`
 - 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`)
 

docs/gallery/assets/lod-decimate-chain-hero.webp

@@ -469,6 +469,17 @@ <h2><a href="gltf-export-roundtrip/">gltf-export-roundtrip</a></h2>
           <a class="card-link" href="gltf-export-roundtrip/">View example <span aria-hidden="true">&rarr;</span></a>
         </div>
       </article>
+      <article class="card" data-tags="depsgraph mesh">
+        <a class="card-media" href="lod-decimate-chain/" aria-label="lod-decimate-chain example detail page">
+          <img src="assets/lod-decimate-chain-hero.webp" alt="lod-decimate-chain — A retro rocket at LOD0/1/2 via the Decimate modifier evaluated through the depsgraph." loading="lazy" decoding="async" />
+        </a>
+        <div class="card-body">
+          <h2><a href="lod-decimate-chain/">lod-decimate-chain</a></h2>
+          <p class="teaches">A retro rocket at LOD0/1/2 via the Decimate modifier evaluated through the depsgraph. The check proves the reduction is non-destructive, the triangle count hits ratio x base within bounds, and silhouette-critical dimensions survive.</p>
+          <p class="witnesses"><span class="tag">witnesses</span> Evaluated-vs-original: the depsgraph carries the reduction while obj.data keeps the closed-form counts. A stacked Decimate halves the effective ratio (caught); an aggressive ratio collapses the nose tip (caught).</p>
+          <a class="card-link" href="lod-decimate-chain/">View example <span aria-hidden="true">&rarr;</span></a>
+        </div>
+      </article>
     </div>
   </main>
   <footer>