feat: add collision-hull-proxy example (compound convex collision) (#96)

Game prop pipelines (engines generally, FiveM/GTA-style prop workflows
specifically) ingest collision as a compound of convex pieces, each under
a per-piece face budget. This example builds a fire hydrant street prop
and its four-piece collision compound — each piece a bmesh.ops.convex_hull
of a coarse sec(pi/n)-inflated cage — and proves per piece, from closed
forms: render-vertex containment (5.9e-08), hull convexity, watertightness,
positive signed volume, Euler characteristic 2, and the 255-face budget.
A hull of the dense render mesh measures 368 faces — over budget — which
is why pipelines hull cages, and why proud details cost cage rows while
concave grooves are free.

Falsified: post-hull render edit (exit 3, escape 0.730000), flipped
winding (exit 5, volume -0.968858), deleted face (exit 4, 3 border
edges). Check output byte-identical on Blender 4.5.11 LTS and 5.1.2.

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

Author: TMHSDigital

.cursor-plugin/plugin.json

@@ -62,6 +62,7 @@
     "examples/armature-bend",
     "examples/bmesh-gear",
     "examples/color-attribute-wheel",
+    "examples/collision-hull-proxy",
     "examples/compositor-glare",
     "examples/curve-bevel-arc",
     "examples/damped-track-aim",

.github/workflows/blender-smoke.yml

@@ -448,3 +448,15 @@ jobs:
           # (ld.light_linking is an AttributeError). Exits non-zero on failure.
           xvfb-run -a "$BLENDER" --background \
             --python examples/light-link-studio/light_link_studio.py --
+
+      - name: Shipped example - collision hull proxy (compound convex pieces)
+        run: |
+          set -euo pipefail
+          # Check only (no render): a lathed fire hydrant prop plus its
+          # four-piece compound collision, each piece a bmesh convex_hull of
+          # a coarse sec(pi/n)-inflated cage; asserts per-piece watertightness,
+          # positive signed volume, render-vertex containment and hull
+          # convexity by closed-form plane tests, Euler characteristic 2, and
+          # the 255-face per-piece engine budget. Exits non-zero on failure.
+          xvfb-run -a "$BLENDER" --background \
+            --python examples/collision-hull-proxy/collision_hull_proxy.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>30 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>31 examples</strong>
 </p>
 
 <p align="center">
@@ -36,7 +36,7 @@
 
 ## Overview
 
-This repository ships **12 skills, 6 rules, 2 templates, 17 snippets, and 30 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 31 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.
 
@@ -504,7 +504,7 @@ round-trips through the raw `POINT` buffer.
 </details>
 
 <details>
-<summary><strong>Game asset pipeline</strong> — 5 examples</summary>
+<summary><strong>Game asset pipeline</strong> — 6 examples</summary>
 
 <table>
 <tr>
@@ -591,6 +591,25 @@ bit-exact weights, and identical deformation of the re-imported rig — plus
 the parenting hazard: unparented skinned meshes let the exporter bind an
 armature by name.
 
+</td>
+</tr>
+<tr>
+<td width="46%" valign="middle">
+<a href="examples/collision-hull-proxy/"><img src="examples/collision-hull-proxy/preview.webp" alt="Collision hull proxy: a red fire hydrant street prop with a yellow bonnet on a dark studio floor, enclosed in four faceted translucent cyan collision shells - the compound convex hull set a game engine ingests" /></a>
+</td>
+<td valign="middle">
+
+### [collision-hull-proxy](examples/collision-hull-proxy/)
+
+The compound-collision contract prop pipelines (engines generally,
+FiveM/GTA-style prop workflows specifically) ingest: one convex hull piece
+per part group, built with `bmesh.ops.convex_hull` from a coarse
+`sec(π/n)`-inflated cage — never the dense render mesh, whose hull measures
+368 faces, over the 255-face per-piece engine budget. Closed-form plane
+tests prove containment (5.9e-08), convexity, watertightness, outward
+winding, and Euler characteristic 2 per piece. Proud details cost cage rows;
+concave grooves are free.
+
 </td>
 </tr>
 </table>

ROADMAP.md

@@ -112,6 +112,10 @@ Not committed; target list for the next content version. (v0.3.0 shipped the smo
 - Degenerate-bevel weld hazard (snippet or rule): bevel width ≥ half a box dimension creates zero-area faces whose loops weld on glTF export (found authoring `gltf-export-roundtrip`, where the count check caught a 36-vertex weld)
 - ~~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`
 - 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`)
+- ~~Collision compound witness~~ **SHIPPED** as `examples/collision-hull-proxy/` — game-prop collision as a compound of convex pieces, each a `bmesh.ops.convex_hull` of a coarse `sec(π/n)`-inflated cage (containment 5.9e-08, watertight, positive signed volume, Euler 2, per-piece 255-face budget: body 70, caps 60×3, compound 250); a hull of the dense render mesh measures 374 faces — over budget — which is why pipelines hull cages; proud details cost cage rows, concave grooves are free; byte-identical on 4.5.11 and 5.1.2
+- Custom-normals / shade-by-angle witness (game prop shading) — `use_auto_smooth` removed in 4.1; assert what 4.5 vs 5.1 actually expose (`shade_smooth_by_angle` operator / Smooth-by-Angle node group), per-loop custom normals surviving depsgraph evaluation, unit-length basis, hard edges landing exactly where an independently recomputed dihedral angle crosses the threshold
+- prop-origin-transform witness — origin to base center, `transform_apply` through the data API, delta transforms, `matrix_parent_inverse` so parented children do not teleport; closed forms: post-apply scale exactly (1,1,1), local bbox min Z == 0, world bbox unchanged (builds on `parent-inverse-orrery`, does not duplicate it)
+- mesh-hygiene-audit witness — the engine-ingest checklist as executable contract: no ngons, no loose vertices, no non-manifold edges, no zero-area faces, consistent outward winding; closed forms via Euler characteristic and exact edge-face incidence counts
 
 ## Future (uncommitted)