feat: add gltf-export-roundtrip example witnessing glTF interchange contracts (#75)

The game-engine interchange path is where AI-generated Blender code drifts
silently: the +Y-up convention, modifier application at export, UV V-flips.
This example pins them: a supply crate exported GLTF_SEPARATE and
re-imported, checked against the depsgraph-evaluated mesh (positions,
normals, UVs, per-triangle material bindings), with the on-disk JSON/buffer
parsed directly for the axis-conversion and V-flip witnesses.

Probed during authoring on 4.5.11 and 5.1.2: exporter/importer RNA is
byte-identical, so the example guards the kwarg set explicitly instead of
papering over a divergence that does not exist. Mesh.calc_normals() being
removed on 5.x surfaced as a real authoring hazard and is pinned in code.

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

Author: TMHSDigital

.cursor-plugin/plugin.json

@@ -67,6 +67,7 @@
     "examples/damped-track-aim",
     "examples/depsgraph-export",
     "examples/driver-wave",
+    "examples/gltf-export-roundtrip",
     "examples/gn-instance-grid",
     "examples/gn-sdf-remesh",
     "examples/grease-pencil-rosette",

.github/workflows/blender-smoke.yml

@@ -369,3 +369,16 @@ jobs:
           xvfb-run -a "$BLENDER" --background \
             --python examples/vse-cut-list/vse_cut_list.py -- \
             --check-pixels --engine cycles
+
+      - name: Shipped example - glTF export round-trip (+Y-up, applied modifiers, UVs)
+        run: |
+          set -euo pipefail
+          # Check only (no render): a 35-part supply crate exported GLTF_SEPARATE
+          # and re-imported; asserts the exporter/importer kwarg set still exists
+          # (RNA guard), the on-disk +Y-up conversion ((x,y,z)->(x,z,-y) baked
+          # into POSITION bounds, no node rotation), disk vertex count ==
+          # evaluated loop count (export_apply), V-flipped TEXCOORD_0, and the
+          # full round-trip of positions/normals/UVs/per-triangle material
+          # bindings within float tolerances. Exits non-zero on failure.
+          xvfb-run -a "$BLENDER" --background \
+            --python examples/gltf-export-roundtrip/gltf_export_roundtrip.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>23 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>24 examples</strong>
 </p>
 
 <p align="center">
@@ -36,7 +36,7 @@
 
 ## Overview
 
-This repository ships **12 skills, 6 rules, 2 templates, 17 snippets, and 22 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 24 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.
 
@@ -465,6 +465,32 @@ round-trips through the raw `POINT` buffer.
 
 </details>
 
+<details>
+<summary><strong>Game asset pipeline</strong> — 1 example</summary>
+
+<table>
+<tr>
+<td width="46%" valign="middle">
+<a href="examples/gltf-export-roundtrip/"><img src="examples/gltf-export-roundtrip/preview.webp" alt="glTF export round-trip: two identical olive-drab sci-fi supply crates on a dark studio floor - authored beside re-imported - with teal status strips, riveted panels, and corner armor, proving the export/import round-trip preserves the asset" /></a>
+</td>
+<td valign="middle">
+
+### [gltf-export-roundtrip](examples/gltf-export-roundtrip/)
+
+A game-prop supply crate round-tripped through `bpy.ops.export_scene.gltf` and
+the importer — the check reads the `.gltf` JSON and `.bin` buffer directly.
+Witnesses the +Y-up convention baked into vertex data with no node rotation,
+`export_apply` shipping the evaluated mesh (one disk vertex per evaluated
+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>
+</table>
+
+</details>
+
 ## How content is organized
 
 ```

ROADMAP.md

@@ -103,6 +103,7 @@ Not committed; target list for the next content version. (v0.3.0 shipped the smo
 - Attribute domain witness: writing a POINT-domain color attribute and reading it as if it were CORNER (or vice versa) silently shears colors across shared verts — companion to `color-attribute-wheel`
 - 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
 - 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`)