feat: add gltf-export-roundtrip example witnessing glTF interchange contracts#75
Merged
Merged
Conversation
…ontracts 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>
github-actions
Bot
added
documentation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
First example of a "game asset pipeline" arc: a sci-fi supply crate (35 beveled box shells, 3 material slots, box-mapped UVs) exported with
bpy.ops.export_scene.gltfand re-imported, with the round-trip verified against the depsgraph-evaluated mesh. glTF is the game-engine interchange format, and its silent-drift conventions are classic AI-miss territory.Contract witnessed
(x, y, z) → (x, z, −y)in the POSITION buffer, no node rotation/scale. The check parses the.gltfJSON and asserts accessor bounds equal the axis-converted evaluated bbox (measured err 0.0).export_yup=Falseships Z-up data every engine displays lying down.export_apply=Trueships the evaluated mesh, not the base cage — flat shading + UV seams split exactly one vertex per evaluated loop (7,560), so the on-disk POSITION count is an exact witness.export_apply=Falsesilently writes the 624-vertex cage..bindirectly.Version witness (probed on both binaries): exporter (109 props) and importer (20 props) RNA signatures are byte-identical between Blender 4.5.11 LTS and 5.1.2; exported JSON differs only in
asset.generator(v4.5.51vsv5.1.20). The example runs identical kwargs on both and guards the kwarg set explicitly so a future rename fails loudly. One genuine 5.x removal surfaced during authoring:Mesh.calc_normals()is gone — pinned in code comments.Falsification evidence (temporary one-line breaks in scratch copies, 5.1.2, restored after measurement):
export_yup=Falseexport_apply=Falseexport_normals=FalseVisual / contact-sheet gate: gltf-export-roundtrip-contact-sheet.webp — candidate beside the pinned set (armature-bend, damped-track-aim, bmesh-gear). Per-criterion verdicts: stage darkness ✓ (matches the set's near-black), wedge warmth ✓ (warm pool behind both crates), subject fill ✓ (comparable to bmesh-gear/tubes), saturation ✓ (designed military palette; teal glow accents, not washed), thumbnail legibility ✓ ("two identical props" story reads at 640×360). Mean luminance: candidate 129.9 vs calibration 139.4 / 100.1 / 143.4 (sRGB luma, 0–255) — inside the set's range, not the extreme.
Proven by live run vs inspection:
.scratch/blender-5.1.2-windows-x64/blender.exe(Blender 5.1.2, hash ec6e62d40fa9) and.scratch/blender-4.5.11-windows-x64/blender.exe(Blender 4.5.11 LTS, hash 4db51e9d1e1e) — identical measured values on both (verts=280 eval_loops=7560 disk_verts=7560 tris=3780,pos_err=0,nrm_err=6.35e-05,uv_err=3.11e-07). Render path exit 0 on both binaries (EEVEE), pixels iterated on this machine (4 drafts; framing/clip/design revisions). Falsification probes above all live on 5.1.2.Test plan
24 examples)examples/gltf-export-roundtrip/gltf_export_roundtrip.py --check-only, plus the 23 existing steps.scratch/blender-5.1.2-windows-x64/blender.exe(Blender 5.1.2) and.scratch/blender-4.5.11-windows-x64/blender.exe(Blender 4.5.11 LTS)Integration: example dir + README, gallery.json entry, plugin manifest, smoke step, top-level README (new "Game asset pipeline" category, counts 23→24), generated gallery pages (read character-by-character: card alt and witnesses callout verified full, no truncation/dotted-path artifacts), ROADMAP shipped entry.
🤖 Generated with Kimi Code