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

[TMHSDigital]

Summary

Ships examples/collision-hull-proxy/ — the first of a "game prop validation" pair aimed at game and FiveM prop developers. A fire hydrant street prop (lathed barrel, bonnet dome, three outlet caps, operating nut) plus the collision a prop pipeline ingests: a compound of four convex hull pieces, one per part group, each built with bmesh.ops.convex_hull from a coarse collision cage.

Scope guard: this witnesses the bpy-level contract a prop pipeline relies on. It is not an engine exporter and does not claim FiveM/engine compatibility — the README says so explicitly.

Contract witnessed

Engines (GTA/FiveM-style prop workflows included) ingest collision as a compound of convex pieces, each piece under a per-piece face limit (255 is the common cap). Per piece, derived from closed forms:

• Containment — every render-mesh vertex on the inner side of every face plane of its piece's hull (max excursion 5.9e-08, tol 2e-4). Holds by construction: cage rings are inflated by sec(π/n) so each n-gon cage ring circumscribes its render ring exactly.
• Convexity — the same plane test restricted to the hull's own vertices.
• Watertight + manifold — every edge borders exactly two faces; V − E + F = 2.
• Outward winding — positive signed volume (divergence theorem; body 0.968858).
• Budget — body 70, pumper 60, sides 60+60; compound 250. A hull of the dense render mesh measures 368 faces (measured, final geometry) — over budget, which is why pipelines hull cages. Proud details cost cage rows; concave grooves are free under the hull.

Falsification evidence (probes run, checks fail as claimed)

Probe	Breakage	Result
Post-hull render edit	pumper lug stretched 2× after hull generation	exit 3, measured escape 0.730000
Inverted winding	all body hull polygons flipped	exit 5, signed volume −0.968858 (exact negation)
Non-watertight piece	one hull face deleted	exit 4, three border edges

Visual notes

Hero render (Cycles, 48 samples): the prop inside its four faceted translucent hull pieces — a containment failure would read as painted metal poking through the shell. Contact sheet (candidate vs pinned calibration set armature-bend / damped-track-aim / bmesh-gear): collision-hull-proxy-contact-sheet.webp

Per-criterion verdicts: stage darkness matches (same floor/wall/world recipe); wedge warmth present (warm pool right of subject); subject fill ~75% of frame height; saturation in-family (enamel red/yellow vs calibration teal/gold); thumbnail legibility instant (hydrant + shell read at 320px). Mean luminance 136.3/255 vs calibration 139.4 (armature-bend), 100.1 (damped-track-aim), 143.4 (bmesh-gear) — inside the band, not the odd one out. No calibration-set change.

Test plan

• .scratch/blender-5.1.2-windows-x64/blender.exe (reports Blender 5.1.2, build 2026-05-19) — check-only run: exit 0, all four pieces pass; all three falsification probes confirmed; EEVEE draft renders + final Cycles hero rendered locally.
• .scratch/blender-4.5.11-windows-x64/blender.exe (reports Blender 4.5.11 LTS, build 2026-06-23) — check-only run: exit 0, output byte-identical to 5.1.2 (same counts, volumes, excursions).
• CI: blender-smoke runs the check-only step under both matrix series (4.5 + 5.1) on this PR.

Live-run vs inspection

• Proven by live run (5.1.2 + 4.5.11 local binaries): all check values above, probe exits, dense-hull 368-face measurement, hero/preview/contact-sheet pixels, gallery HTML output (card alt and witnesses callout read post-generation; 368 claim re-verified against final geometry).
• Inspection only: EEVEE hero path on 4.5 (the version-shared code path is the eevee_engine_id() branch, exercised on 5.1 only; Cycles is the shipped hero engine).

Integration

Example dir + README + preview, hero webp, committed contact sheet, gallery.json entry, plugin manifest (alphabetical), blender-smoke.yml step (both matrix series), top-level README counts 30→31 + Game asset pipeline row (5→6), ROADMAP pool drained/restocked (this subject shipped; custom-normals-shade, prop-origin-transform, mesh-hygiene-audit added), gallery regenerated via scripts/build_gallery.py.